Available Operations Webhooks Errors
 
 

SMS API

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.nexmo.com/messaging/sms/overview

Available Operations:

Send an SMS

Send an outbound SMS from your Vonage account

POST https://rest.nexmo.com/sms/:format
Host https://rest.nexmo.com
POST /sms/:format

Path Parameters

format
string | Required | Default: json

The format of the response

Must be one of: json or xml

Request body application/x-www-form-urlencoded

api_key
string | Required | Min: 8 | Max: 8

Your API key

api_secret
string | Min: 6 | Max: 32

Your API secret. Required unless sig is provided

sig
string | Min: 16 | Max: 60

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details.

from
string | Required

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.

to
string | Required | Min: 7 | Max: 15

The number that the message should be sent to. Numbers are specified in E.164 format.

text
string

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.

ttl
integer | Min: 20000 | Max: 604800000 | Default: 259200000

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.

status-report-req
boolean | Default: true

Advanced: Boolean indicating if you like to receive a Delivery Receipt.

callback
string

Advanced: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard.

message-class
integer

Advanced: The Data Coding Scheme value of the message

Must be one of: 0, 1, 2 or 3
type
string | Default: text

Advanced: The format of the message body

Must be one of: text, binary, wappush, unicode, vcal or vcard
vcard
string (vcard)

Advanced: A business card in vCard format. Depends on type parameter having the value vcard.

vcal
string (vcal)

Advanced: A calendar event in vCal format. Depends on type parameter having the value vcal.

body
string

Advanced: Hex encoded binary data. Depends on type parameter having the value binary.

udh
string

Advanced: Your custom Hex encoded User Data Header. Depends on type parameter having the value binary.

protocol-id
integer

Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with udh.

title
string

Advanced: The title for a wappush SMS. Depends on type parameter having the value wappush.

url
string

Advanced: The URL of your website. Depends on type parameter having the value wappush.

validity
string

Advanced: The availability for an SMS in milliseconds. Depends on type parameter having the value wappush.

client-ref
string

Advanced: You can optionally include your own reference of up to 40 characters.

account-ref
string

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support@nexmo.com

Responses

200 Success
message-count
string

The amount of messages in the request

messages
array of objects
to
string

The number the message was sent to. Numbers are specified in E.164 format.

message-id
string

The ID of the message

status
string

The status of the message. See Troubleshooting Failed SMS.

remaining-balance
string

Your remaining balance

message-price
string

The cost of the message

network
string

The ID of the network of the recipient

client-ref
string

If a client-ref was included when sending the SMS, this field will be included and hold the value that was sent.

account-ref
string

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support@nexmo.com

message-count
string

The amount of messages in the request

messages
array of objects
status
string

The error status of the message

error-text
string

The description of the error

messages
array of objects
status
string

The error status of the message

error-text
string

The description of the error

Example Request

POST /sms/:format HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 45

api_key=abcd1234&from=AcmeInc&to=447700900000
POST /sms/:format HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 334

api_key=abcd1234&api_secret=abcdef0123456789&from=AcmeInc&to=447700900000&text=Hello+World%21&ttl=900000&callback=https%3A%2F%2Fexample.com%2Fsms-dlr&type=text&body=0011223344556677&udh=06050415811581&protocol-id=127&title=Welcome&url=https%3A%2F%2Fexample.com&validity=300000&client-ref=my-personal-reference&account-ref=customer1234

Example Responses

200
{
  "message-count": "1",
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345",
      "client-ref": "my-personal-reference",
      "account-ref": "customer1234"
    }
  ]
}
{
  "message-count": "1",
  "messages": [
    {
      "status": "2",
      "error-text": "Missing to param"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<mt-submission-response>
  <messages count="1">
    <message>
      <to>447700900000</to>
      <messageId>0A0000000123ABCD1</messageId>
      <status>0</status>
      <remainingBalance>3.14159265</remainingBalance>
      <messagePrice>0.03330000</messagePrice>
      <network>12345</network>
      <client-ref>my-personal-reference</client-ref>
      <account-ref>customer1234</account-ref>
    </message>
  </messages>
</mt-submission-response>
<?xml version="1.0" encoding="UTF-8"?>
<mt-submission-response>
  <messages>
    <message>
      <status>2</status>
      <error-text>Missing to param</error-text>
    </message>
  </messages>
</mt-submission-response>

Delivery Receipt Callback

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.

POST https://example.com/webhooks/event

Request body application/json

msisdn
string

The number the message was sent to. Numbers are specified in E.164 format.

to
string

The SenderID you set in from in your request.

network-code
string

The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.

messageId
string

The Vonage ID for this message.

price
string

The cost of the message

status
string

A code that explains where the message is in the delivery process.

scts
string

When the DLR was received from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00

err-code
string

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 for more details

api-key
string

The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.

client-ref
string

If the client-ref is set when the SMS is sent, it will be included in the delivery receipt

message-timestamp
string

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

timestamp
string

A timestamp in Unix (seconds since the epoch) format. Only included if you have signatures enabled

nonce
string

A random string to be used when calculating the signature. Only included if you have signatures enabled

sig
string

The signature to enable verification of the source of this webhook. Please see the developer documentation for validating signatures for more information, or use one of our published SDKs. Only included if you have signatures enabled

Example Payload

{
  "msisdn": "447700900000",
  "to": "AcmeInc",
  "network-code": "12345",
  "messageId": "0A0000001234567B",
  "price": "0.03330000",
  "status": "delivered",
  "scts": "2001011400",
  "err-code": "0",
  "api-key": "abcd1234",
  "client-ref": "my-personal-reference",
  "message-timestamp": "2020-01-01 12:00:00 +0000",
  "timestamp": "1582650446",
  "nonce": "ec11dd3e-1e7f-4db5-9467-82b02cd223b9",
  "sig": "1A20E4E2069B609FDA6CECA9DE18D5CAFE99720DDB628BD6BE8B19942A336E1C"
}

Webhooks

Webhooks are an extension of an API, but instead of your code requesting data, the API sends data to you. The data arrives in a web request to your application.

To learn more about webhooks, see our webhooks documentation

This API may send any of the webhooks documented below to the URL that you have configured. You must respond with a 200 or 204 HTTP response, or the requests will be retried

 

Inbound SMS Webhook

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.

POST https://example.com/webhooks/inbound-sms

Request body application/json

api-key
string | Required

The Vonage API Key of the receiving account.

msisdn
string | Required

The phone number that this inbound message was sent from. Numbers are specified in E.164 format.

to
string | Required

The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.

messageId
string | Required

The ID of the message

text
string | Required

The message body for this inbound message.

type
string | Required

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.
keyword
string | Required

The first word in the message body. Converted to upper case.

message-timestamp
string | Required

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

timestamp
string

A unix timestamp representation of message-timestamp.

nonce
string

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.

concat
string

True - if this is a concatenated message. This field does not exist if it is a single message

concat-ref
string

The transaction reference. All parts of this message share this value.

concat-total
string

The number of parts in this concatenated message.

concat-part
string

The number of this part in the message. Counting starts at 1.

data
string (binary)

The content of this message, if type is binary.

udh
string

The hex encoded User Data Header, if type is binary

Example Payload

{
  "api-key": "abcd1234",
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello world",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01 12:00:00 +0000"
}
{
  "api-key": "abcd1234",
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello world",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01 12:00:00 +0000",
  "timestamp": "1578787200",
  "nonce": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "concat": "true",
  "concat-ref": "1",
  "concat-total": "3",
  "concat-part": "2"
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.

Code Details
1

Throttled. You are sending SMS faster than the account limit.

2

Missing Parameters. Your request is missing one of the required parameters from, to, api_key, api_secret or text.

3

Invalid Parameters. The value of one or more parameters is invalid.

4

Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled.

5

Internal Error. An error has occurred in the platform whilst processing this message.

6

Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix.

7

Number Barred. The number you are trying to send messages to is blacklisted and may not receive them.

8

Partner Account Barred. Your Vonage account has been suspended.

9

Partner Quota Violation. You do not have sufficient credit to send the message.

10

Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation.

11

Account Not Enabled For HTTP. This account is not provisioned for the SMS API.

12

Message Too Long. The message length exceeds the maximum allowed.

14

Invalid Signature. The signature supplied could not be verified.

15

Invalid Sender Address. You are using a non-authorized sender ID in the from field.

22

Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address.

23

Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters.

29

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.

32

Signature And API Secret Disallowed. A signed request may not also present an api_secret.

33

Number De-activated. The number you are trying to send messages to is de-activated and may not receive them.