openapi: 3.0.0
info:
  version: 1.5.0
  title: SMS API
  x-metaTitle: Vonage SMS API Reference | Vonage API Documentation
  x-metaDescription: Get started with the Vonage SMS API, a powerful tool for
    automating text message communications. Learn more in Vonage's API
    documentation.
  description: With the SMS API you can send SMS from your account and lookup
    messages both messages that you've sent as well as messages sent to your
    virtual numbers. Numbers are specified in E.164 format. More SMS API
    documentation is at <https://developer.vonage.com/messaging/sms/overview>
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.vonage.com/
servers:
  - url: https://rest.nexmo.com
security:
  - basicAuth: []
paths:
  /sms/{format}:
    post:
      operationId: send-an-sms
      summary: Send an SMS
      description: Send an outbound SMS from your Vonage account
      parameters:
        - name: format
          description: The format of the response
          in: path
          required: true
          schema:
            example: json
            type: string
            enum:
              - json
              - xml
            default: json
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/NewMessage"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SMS"
                  - $ref: "#/components/schemas/Error"
            text/xml:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SMSXml"
                  - $ref: "#/components/schemas/ErrorXml"
      callbacks:
        delivery-receipt:
          "{$request.body#/callback}":
            post:
              summary: Delivery Receipt
              operationId: delivery-receipt
              description: The following are parameters sent in as a [delivery
                receipt](/messaging/sms/guides/delivery-receipts) callback. You
                can subscribe to [webhooks](/getting-started/concepts/webhooks)
                to receive notification when the delivery status of an SMS that
                you have sent with Vonage changes.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/DeliveryReceipt"
              responses:
                "200":
                  description: Your server returns this code if it accepts the callback
x-webhooks:
  inbound-sms:
    "{$request.body#/callback}":
      post:
        summary: Inbound SMS
        operationId: inbound-sms
        x-example-path: /webhooks/inbound-sms
        description: >
          If you rent one or more virtual numbers from Vonage, inbound messages
          to that number are sent to your [webhook
          endpoint](/getting-started/concepts/webhooks).


          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.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InboundMessage"
        responses:
          "200":
            description: Your server returns this code if it accepts the callback
components:
  schemas:
    NewMessage:
      required:
        - from
        - to
        - text
      properties:
        api_key:
          description: Your API key. Only required if setting `sig`.
          type: string
          minLength: 8
          maxLength: 8
          example: abcd1234
        sig:
          description: |
            The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.
            Note: **DO NOT** set an `Authorization` header when using `sig`.
          type: string
          minLength: 16
          maxLength: 60
          example: 5d41402abc4b2a76b9719d911017c592
        timestamp:
          description: An integer containing the number of seconds since the epoch (this
            is sometimes also known as UNIX time). Only required if setting
            `sig`. See [Signing
            Requests](https://developer.vonage.com/getting-started/concepts/signing-messages)
            for more details.
          type: integer
          example: 1617187200
        from:
          description: The name or number the message should be sent from. Alphanumeric
            senderID's are not supported in all countries, see [Global
            Messaging](https://developer.vonage.com/messaging/sms/guides/global-messaging#country-specific-features)
            for more details. If alphanumeric, spaces will be ignored. Numbers
            are specified in E.164 format.
          type: string
          example: AcmeInc
        to:
          description: The number that the message should be sent to. Numbers are
            specified in E.164 format.
          type: string
          minLength: 7
          maxLength: 15
          pattern: \d{7,15}
          example: "447700900000"
        text:
          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`.
          type: string
          example: Hello World!
        ttl:
          description: "**Advanced**: The duration in milliseconds the delivery of an SMS
            will be attempted. By default Vonage attempts 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."
          type: integer
          example: 900000
          default: 259200000
          minimum: 20000
          maximum: 604800000
        status-report-req:
          description: "**Advanced**: Boolean indicating if you like to receive a
            [Delivery
            Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt)\
            ."
          type: boolean
          example: false
          default: true
        callback:
          description: "**Advanced**: The webhook endpoint the delivery receipt for this
            sms is sent to. This parameter overrides the webhook endpoint you
            set in Dashboard. Max 100 characters."
          type: string
          example: https://example.com/sms-dlr
        message-class:
          description: "**Advanced**: The Data Coding Scheme value of the message"
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
        type:
          description: "**Advanced**: The format of the message body"
          type: string
          enum:
            - text
            - binary
            - unicode
          example: text
          default: text
        body:
          description: "**Advanced**: Hex encoded binary data. Depends on `type` parameter
            having the value `binary`."
          type: string
          example: "0011223344556677"
        udh:
          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`."
          type: string
          example: "06050415811581"
        protocol-id:
          description: "**Advanced**: The value of the [protocol
            identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identi\
            fier) to use. Ensure that the value is aligned with `udh`."
          type: integer
          example: 127
        client-ref:
          description: "**Advanced**: You can optionally include your own reference of up
            to 100 characters."
          type: string
          example: my-personal-reference
        account-ref:
          description: "**Advanced**: An optional string used to identify separate
            accounts using the SMS endpoint for billing purposes. To use this
            feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})"
          type: string
          example: customer1234
        entity-id:
          description: "**Advanced**: A string parameter that satisfies regulatory
            requirements when sending an SMS to specific countries. For more
            information please refer to the [Country-Specific Outbound SMS
            Features](https://api.support.vonage.com/hc/en-us/articles/11501178\
            1468)"
          type: string
          example: "1101456324675322134"
        content-id:
          description: "**Advanced**: A string parameter that satisfies regulatory
            requirements when sending an SMS to specific countries. For more
            information please refer to the [Country-Specific Outbound SMS
            Features](https://api.support.vonage.com/hc/en-us/articles/11501178\
            1468)"
          type: string
          example: "1107457532145798767"
        trusted-number:
          description: >
            Setting this parameter to `true` overrides, on a per-message basis,
            any protections set up via [Fraud
            Defender](https://developer.vonage.com/en/fraud-defender/overview)
            (Traffic Rules, SMS Burst Protection, AIT Protection).


            This parameter only has any effect for accounts subscribed to Fraud
            Defender Premium.
          type: boolean
          example: true
          default: false
        pool-id:
          description: |
            The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the `from` number. 
            The `from` parameter is still required even when specifying a `pool-id` and will be used as a fall-back if the number pool cannot be used.
            See the [Number Pools documentation](https://developer.vonage.com/numbers/number-pools-api/overview) for more information.
          type: string
          example: abc123
    Error:
      description: Error
      type: object
      properties:
        message-count:
          type: string
          description: The amount of messages in the request
          example: "1"
        messages:
          type: array
          items:
            $ref: "#/components/schemas/ErrorMessage"
    ErrorXml:
      type: object
      description: Error
      xml:
        name: mt-submission-response
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/ErrorMessage"
    ErrorMessage:
      type: object
      xml:
        name: message
      properties:
        status:
          type: string
          description: The error status of the message
          example: "2"
        error-text:
          type: string
          description: The description of the error
          example: Missing to param
    SMS:
      description: Message sent
      type: object
      properties:
        message-count:
          type: string
          description: The amount of messages in the request
          example: "1"
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
    SMSXml:
      type: object
      description: Message sent
      xml:
        name: mt-submission-response
      properties:
        messages:
          x-skip-response-description: true
          type: array
          items:
            $ref: "#/components/schemas/Message"
          properties:
            count:
              type: integer
              example: 1
              xml:
                attribute: true
    InboundMessage:
      type: object
      required:
        - msisdn
        - to
        - messageId
        - text
        - type
        - keyword
        - message-timestamp
        - api-key
      properties:
        api-key:
          type: string
          description: The Vonage API Key of the receiving account.
          example: abcd1234
        msisdn:
          type: string
          description: The phone number that this inbound message was sent from. Numbers
            are specified in E.164 format.
          example: "447700900001"
        to:
          type: string
          description: 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: The ID of the message
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        text:
          type: string
          description: The message body for this inbound message.
          example: Hello world
        type:
          type: string
          description: >
            Possible values are:

              - `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: The first word in the message body. Converted to upper case.
          example: HELLO
        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
        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. This field does not exist
            if it is a single 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
    Message:
      type: object
      properties:
        to:
          type: string
          description: The number the message was sent to. Numbers are specified in E.164
            format.
          example: "447700900000"
        message-id:
          type: string
          description: The ID of the message
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          xml:
            name: messageId
        status:
          type: string
          description: The status of the message. See [Troubleshooting Failed
            SMS](/messaging/sms/guides/troubleshooting-sms).
          example: "0"
        remaining-balance:
          type: string
          description: Your estimated remaining balance
          example: "3.14159265"
          xml:
            name: remainingBalance
        message-price:
          type: string
          description: The estimated cost of the message
          example: "0.03330000"
          xml:
            name: messagePrice
        network:
          type: string
          description: The estimated ID of the network of the recipient
          example: "12345"
        client-ref:
          description: If a `client-ref` was included when sending the SMS, this field
            will be included and hold the value that was sent.
          type: string
          example: my-personal-reference
        account-ref:
          type: string
          description: "**Advanced**: An optional string used to identify separate
            accounts using the SMS endpoint for billing purposes. To use this
            feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})"
          example: customer1234
    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 received 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, or if the status is unknown. See the [Delivery
            Receipt
            documentation](/messaging/sms/guides/delivery-receipts#dlr-error-codes)
            for more details
          example: "0"
        api-key:
          type: string
          description: The API key that sent the SMS. This is useful when multiple
            accounts are sending webhooks to the same endpoint.
          example: abcd1234
        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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-errors:
  "1":
    description: Throttled. You are sending SMS faster than the account limit.
    resolution: Refer to [What is the Throughput Limit for Outbound
      SMS?](https://api.support.vonage.com/hc/en-us/articles/203993598) for more
      information.
  "2":
    description: Missing Parameters. Your request is missing one of the required
      parameters `from`, `to`, `api_key`, `api_secret` or `text`.
    resolution: Check your parameters and try again.
  "3":
    description: Invalid Parameters. The value of one or more parameters is invalid.
    resolution: Check your parameters and try again.
  "4":
    description: Invalid Credentials. Your API key and/or secret are incorrect,
      invalid or disabled.
    resolution: Visit the [Dashboard](${CUSTOMER_DASHBOARD_URL}) and check your
      credentials.
  "5":
    description: Internal Error. An error has occurred in the platform whilst
      processing this message.
    resolution: If the error persists, contact [support](mailto:${CUSTOMER_SUPPORT_EMAIL}).
  "6":
    description: Invalid Message. The platform was unable to process this message,
      for example, an un-recognized number prefix.
    resolution: N/A
  "7":
    description: Number Barred. The number you are trying to send messages to is
      blacklisted and may not receive them.
    resolution: N/A
  "8":
    description: Partner Account Barred. Your Vonage account has been suspended.
    resolution: Contact [support](mailto:${CUSTOMER_SUPPORT_EMAIL}).
  "9":
    description: Partner Quota Violation. You do not have sufficient credit to send
      the message.
    resolution: Top-up and retry.
  "10":
    description: Too Many Existing Binds. The number of simultaneous connections to
      the platform exceeds your account allocation.
    resolution: Back-off and retry.
  "11":
    description: Account Not Enabled For HTTP. This account is not provisioned for
      the SMS API.
    resolution: This error usually indicates that you should use SMPP instead.
  "12":
    description: Message Too Long. The message length exceeds the maximum allowed.
    resolution: Send shorter messages.
  "14":
    description: Invalid Signature. The signature supplied could not be verified.
    resolution: Check the [documentation for signing
      messages](/getting-started/concepts/signing-messages) or use one of the
      [SDKs](/tools) to handle the signing.
  "15":
    description: Invalid Sender Address. You are using a non-authorized sender ID in
      the `from` field.
    resolution: This is most commonly seen in North America, where a Vonage long
      virtual number or short code is required.
  "17":
    description: Message Blocked by Provider. The messaging provider has chosen to
      block this message. This may be due to content or restrictions imposed by
      the provider.
    resolution: N/A
  "22":
    description: Invalid Network Code. The network code supplied was either not
      recognized, or does not match the country of the destination address.
    resolution: Check the network code or remove it from your request.
  "23":
    description: Invalid Callback Url. The callback URL supplied was either too long
      or contained illegal characters.
    resolution: Supply a valid URL for the callback.
  "29":
    description: Non-Whitelisted Destination. Your Vonage account is still in demo
      mode. While in demo mode you must add target numbers to your whitelisted
      destination list.
    resolution: Top-up your account to remove this limitation.
  "32":
    description: Signature And API Secret Disallowed. A signed request may not also
      present an `api_secret`.
    resolution: Remove the API secret from your request, or don't sign the message.
  "33":
    description: Number De-activated. The number you are trying to send messages to
      is de-activated and may not receive them.
    resolution: N/A
