swagger: '2.0'
info:
  title: SMS-Vonage
  version: "v1.1.1"
  termsOfService: 'https://developer.kpn.com/legal'
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: 'https://developer.kpn.com/support'
  description: >-
    Vonage's SMS API allows you to send and receive text messages to users around the globe through simple RESTful APIs.
      
      * Programmatically send and receive high volume of SMS anywhere in the world.
      * Build apps that scale with the web technologies that you are already using.
      * Send SMS with low latency and high delivery rates.
      * Receive SMS for free using SMS-enabled local numbers in countries around the world.
      * Only pay for what you use, nothing more.

      
    ## [Source view](https://app.swaggerhub.com/apis/kpn/sms-nexmo/)<br/>
    [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/sms-nexmo/)
    
    ---
    
    ## [KPN Developer](https://developer.kpn.com/)<br/>
    [Getting Started](https://developer.kpn.com/getting-started)
    
     ---
    
host: api-prd.kpn.com
basePath: /communication/nexmo/sms
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers
schemes:
  - https
paths:
  '/send':
    post:
      summary: Send SMS
      tags:
        - Send SMS
      description: Send an outbound SMS
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: from
          type: string
          required: true
          description: >-
            The name or number the message should be sent from. Alphanumeric
            senderID's are not supported in all countries, see Global Messaging
            for more details. If alphanumeric, spaces will be ignored. Numbers
            are specified in E.164 format. You can use any alphanumeric string up to 11 characters (or up to 15 numeric characters).  It is recommended to send at least "3" characters (in case of alphanumeric), as it might show differently on different mobile devices. Moreover, alphanumeric cannot contain spaces as well.
              example: `AcmeInc`.Note: If the value in your from parameter does not obey these rules it might be modified in transit or not delivered at all.
        - in: formData
          name: to
          type: string
          required: true
          description: >-
            The number that the message should be sent to. Numbers are specified
            in E.164 format.
              minLength: 7
              maxLength: 15
              pattern: '\d{7,15}'
              example: 447700900000              
        - in: formData
          name: text
          type: string
          required: false
          description: >-
            The body of the message being sent. If your message contains
            characters that can be encoded according to the GSM Standard and
            Extended tables then you can set the `type` to `text`. If your
            message contains characters outside this range, then you will need
            to set the `type` to `unicode`.
              example: Hello World! 
        - in: formData
          name: ttl
          type: integer
          required: false
          description: >-
            **Advanced**: The duration in milliseconds the delivery of an SMS
            will be attempted.§§ By default Vonage attempt delivery for 72 hours,
            however the maximum effective value depends on the operator and is
            typically 24 - 48 hours. We recommend this value should be kept at
            its default or at least 30 minutes.
              minimum: 20000
              maximum: 604800000
              example: 900000
          #default: 259200000
        - in: formData
          name: status-report-req
          type: boolean
          required: false
          default: false
          description: >-
            **Advanced**: Boolean indicating if you like to receive a [Delivery
            Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).'
        - in: formData
          name: callback
          type: string
          required: false
          # default: 'https://example.com/sms-dlr'
          description: >-
            **Advanced**: The webhook endpoint the delivery receipt for this
            sms is sent to. This parameter overrides the webhook endpoint you
            set in Dashboard.
              
        - in: formData
          name: message-class
          type: integer
          required: false
          enum: [0,1,2,3]
          description: >- 
            **Advanced**: The Data Coding Scheme value of the message
            
        - in: formData
          name: type
          type: string
          required: false
          enum: ['text','binary','wappush','unicode','vcal','vcard']
          description: >-
            **Advanced**: The format of the message body'' example: text
          
          #default: 'text'
        - in: formData
          name: vcard
          type: string
          required: false
          description: >-
            **Advanced**: A business card in [vCard
            format](https://en.wikipedia.org/wiki/VCard). Depends on `type`
            parameter having the value `vcard`.
          format: vcard
        - in: formData
          name: vcal
          type: string
          required: false
          description: >-
            **Advanced**: A calendar event in [vCal
            format](https://en.wikipedia.org/wiki/VCal). Depends on `type`
            parameter having the value `vcal`.
          format: vcal
        - in: formData
          name: body
          type: string
          required: false
          # default: 0011223344556677
          description: >-
            **Advanced**: Hex encoded binary data. Depends on `type` parameter
            having the value `binary`.
          
        - in: formData
          name: udh
          type: string
          required: false
          # default: 06050415811581
          description: >-
            **Advanced**: Your custom Hex encoded [User Data
            Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on
            `type` parameter having the value `binary`.
        - in: formData
          name: protocol-id
          type: integer
          required: false
          # default: 127
          description: >-
            **Advanced**: The value of the [protocol
            identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier)
            to use. Ensure that the value is aligned with `udh`.
        - in: formData
          name: title
          type: string
          required: false
          # default: Welcome
          description: >-
            **Advanced**: The title for a wappush SMS. Depends on `type`
            parameter having the value `wappush`.   
        - in: formData
          name: url
          type: string
          required: false
          # default: https://example.com
          description: >-
            **Advanced**: The URL of your website. Depends on `type` parameter
            having the value `wappush`.
        - in: formData
          name: validity
          type: string
          required: false
          description: >-
            **Advanced**: The availability for an SMS in milliseconds. Depends
            on `type` parameter having the value `wappush`.
        - in: formData
          name: client-ref
          type: string
          required: false
          description: >-
            **Advanced**: You can optionally include your own reference of up
            to 40 characters.
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SendSMSResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  /register:
    post:
      summary: Register callback URL to webhook for incoming messages
      description: |
        Handling inbound SMS with with API is easy. You just need to create a webhook endpoint and configure your number or account to point to the endpoint. 
        - If you are a test user  try inbound messaging using below using 'Register Webhook endpoint'. 
        - If you are production user,  use the `Phone Numbers API` to search, buy and manage your virtual number.
      tags:
        - Register webhook - Demo testing ONLY
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: to
          type: string
          required: true
          description: >-
            The phone number you use for testing, without buying a virtual number. This is not applicable if you are a premium user.
            Remember, this is only applicable if you are a demo user.
        - in: formData
          name: callback_url
          type: string
          required: true
          description: >-
            The callback URL for inbound SMS.           
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RegisterWebhookResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  '/https://example.com:webhooks/delivery-receipt':
    post:
      summary: Delivery Receipt
      description: >-
        This is not an API call but it is to showcase how the schema of delivery receipt will look like.
        You can get delivery receipt by using `status-report-req` and `callback` parameters of 'Send SMS' request body.
      tags:
        - Callback
      parameters:
        - in: body
          name: delivery-receipt
          description: >- 
            The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Vonage changes.
          schema:
            $ref: "#/definitions/DeliveryReceipt"
      responses:
        '200':
          description: Your server returns this code if it accepts the callback
  '/https://example.com:webhooks/inbound-sms':
    post:
      summary: Inbound SMS
      description: >-
        This is not an API call but it is to showcase how the schema of inbound SMS will look like.
        You can get inbound SMS by registering your webhook URL using `Register webhook` and then passing 'inbound' header value as 'yes' in 'Send SMS'.
      tags:
        - Webhook
      parameters:
        - in: body
          name: inbound-sms
          description: >- 
            If you rent one or more virtual numbers from Vonage, inbound messages to that number are sent to your webhook endpoint. When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Vonage will resend the inbound message for the next 24 hours.
          schema:
            $ref: "#/definitions/InboundMessage"
      responses:
        '200':
          description: Your server returns this code if it accepts the callback       
securityDefinitions:
  OAuth2:
    type: oauth2
    tokenUrl: >-
      https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
    flow: application
definitions:
  RegisterWebhookRequest:
    type: object
    properties:
      callback_url:
        type: string
        example: 'https://yourdomain.com/webhook'
        description: your webhook endpoint on an HTTP server
        title: Callback URL
      to:
        type: string
        example: 3161111111
        description: >-
          Please enter the virtual number that has been provided to you. If you
          are a test user then please enter the same mobile number that you are
          using for test purposes. Individual virtual numbers can be alloted to
          premium users which can be registered against the webhook enpoint.
        title: Mobile Number
  RegisterWebhookResponse:
    type: object
    properties:
      message:
        type: string
        description: response message
        example: Your callback url is registered.
  SendSMSResponse:
    type: object
    properties:
      message-count:
        type: integer
        description: The amount of messages in the request
        example: 1
      messages:
        type: array
        items:
          $ref: '#/definitions/SendSMSResponseMessage'
  SendSMSResponseMessage:
    type: object
    properties:
      to:
        type: string
        description: The number the message was sent to
        example: '447700900000'
      message-id:
        type: string
        description: The ID of the message
        example: 0A0000000123ABCD1
      status:
        type: string
        description: "Code | Description\n   -- | --\n   '1' | You have exceeded the submission capacity allowed on this account. Please wait and retry.\n   '2' | Your request is incomplete and missing some mandatory parameters.\n   '3'\t| The value of one or more parameters is invalid.\n   '4'\t| The api_key / api_secret you supplied is either invalid or disabled.\n   '5'\t| There was an error processing your request in the Platform.\n   '6' | The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.\n   '7'\t| The number you are trying to submit to is blacklisted and may not receive messages.\n   '8' | The api_key you supplied is for an account that has been barred from submitting messages.\n   '9' | Your pre-paid account does not have sufficient credit to process this message.\n   '11' | This account is not provisioned for REST submission, you should use SMPP instead.\n   '12' | The length of udh and body was greater than 140 octets for a binary type SMS request.\n   '13' |\tMessage was not submitted because there was a communication failure.\n   '14' |\tMessage was not submitted due to a verification failure in the submitted signature.\n   '15' |\tDue to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.\n   '16' |\tInvalid TTL\tThe value of ttl in your request was invalid.\n   '19' |\tYour request makes use of a facility that is not enabled on your account.\n   '20' |\tThe value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.\n   '23' |\tYou did not include https in the URL you set in callback.\n   '29' |\tThe phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.\n   '34' |\tThe phone number you supplied in the to parameter of your request was either missing or invalid.\n"
        example: '0'
      network:
        type: string
        description: The ID of the network of the recipient
        example: '12345'
  DeliveryReceipt:
      type: object
      properties:
        msisdn:
          type: string
          description: The number the message was sent to. Numbers are specified in E.164 format.
          example: '447700900000'
        to:
          type: string
          description: The SenderID you set in `from` in your request.
          example: AcmeInc
        network-code:
          type: string
          description: The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.
          example: '12345'
        messageId:
          type: string
          description: The Vonage ID for this message.
          example: '0A0000001234567B'
        price:
          type: string
          description: The cost of the message
          example: '0.03330000'
        status:
          type: string
          description: A code that explains where the message is in the delivery process.
          example: 'delivered'
          x-possible-values:
            - delivered
            - expired
            - failed
            - rejected
            - accepted
            - buffered
            - unknown
        scts:
          type: string
          description: When the DLR was recieved from the carrier in the following format `YYMMDDHHMM`. For example, `2001011400` is at `2020-01-01 14:00`
          example: '2001011400'
        err-code:
          type: string
          description: The status of the request. Will be a non `0` value if there has been an error. See the [SMS error reference](/api-errors/sms) for more details
          example: '0'
        message-timestamp:
          description: The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
          type: string
          example: 2020-01-01 12:00:00
  InboundMessage:
      type: object
      properties:
        msisdn:
          type: string
          description: >- 
            `required`
            The phone number that this inbound message was sent from. Numbers are specified in E.164 format.
          example: '447700900001'
          
        to:
          type: string
          description: >- 
            `required`
            The phone number the message was sent to. **This is your virtual number**. Numbers are specified in E.164 format.
          example: '447700900000'
        messageId:
          type: string
          description: >- 
            `required`
            The ID of the message  (required)
          example: 0A0000000123ABCD1
        text:
          type: string
          description: >-
            `required`
            The message body for this inbound message.  (required)
          example: Hello world
        type:
          type: string
          description: |
            Possible values are: >-
              `required`
              - `text` - standard text.
              - `unicode` - URLencoded   unicode  . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
              - `binary` - a binary message.
          example: 'text'
        keyword:
          type: string
          description: >- 
            `required`
            The first word in the message body. This is typically used with short codes.
          example: Hello
        message-timestamp:
          description: >- 
            `required`
            The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
          type: string
          example: 2020-01-01 12:00:00
        timestamp:
          description: A unix timestamp representation of message-timestamp.
          type: string
          example: "1578787200"
        nonce:
          type: string
          description: A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        concat:
          type: string
          description: True - if this is a concatenated message.
          example: 'true'
        concat-ref:
          type: string
          description: The transaction reference. All parts of this message share this value.
          example: '1'
        concat-total:
          type: string
          description: The number of parts in this concatenated message.
          example: '3'
        concat-part:
          type: string
          description: The number of this part in the message. Counting starts at 1.
          example: '2'
        data:
          type: string
          format: binary
          description: The content of this message, if type is binary.
        udh:
          type: string
          description: The hex encoded User Data Header, if type is binary          
  ErrorResponse:
    type: object
    properties:
      transactionId:
        type: string
        description: transaction id of the the request
        title: Transaction ID
      status:
        type: string
        description: Status
        title: Status
      name:
        type: string
        description: Error name
        title: Error name
      message:
        type: string
        description: Error message
        title: Error message
      info:
        type: string
        description: Additional information about error
        title: Info