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
88abcd1234Your API key
632abcdef0123456789Your API secret. Required unless sig is provided
1660The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details.
AcmeIncThe 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.
715447700900000The number that the message should be sent to. Numbers are specified in E.164 format.
Hello World!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.
20000604800000259200000900000Advanced: 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.
trueAdvanced: Boolean indicating if you like to receive a Delivery Receipt.
https://example.com/sms-dlrAdvanced: 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.
Advanced: The Data Coding Scheme value of the message
0123texttextAdvanced: The format of the message body
textbinaryunicode0011223344556677Advanced: Hex encoded binary data. Depends on type parameter having the value binary.
06050415811581Advanced: Your custom Hex encoded User Data Header. Depends on type parameter having the value binary.
127Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with udh.
my-personal-referenceAdvanced: You can optionally include your own reference of up to 100 characters.
customer1234Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support
1101456324675322134Advanced: 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
1107457532145798767Advanced: 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
Example Request
1The amount of messages in the request
447700900000The number the message was sent to. Numbers are specified in E.164 format.
aaaaaaaa-bbbb-cccc-dddd-0123456789abThe ID of the message
0The status of the message. See Troubleshooting Failed SMS.
3.14159265Your estimated remaining balance
0.03330000The estimated cost of the message
12345The estimated ID of the network of the recipient
my-personal-referenceIf a client-ref was included when sending the SMS, this field will be included and hold the value that was sent.
customer1234Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support
Example ResponseยปMessage sent
Delivery Receipt
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.
447700900000The number the message was sent to. Numbers are specified in E.164 format.
AcmeIncThe SenderID you set in from in your request.
12345The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.
0A0000001234567BThe Vonage ID for this message.
0.03330000The cost of the message
deliveredA code that explains where the message is in the delivery process.
2001011400When the DLR was received from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00
0The 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
abcd1234The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.
2020-01-01 12:00:00The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
Example Payload
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.
Available Operations
Inbound SMS
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.
abcd1234The Vonage API Key of the receiving account.
447700900001The phone number that this inbound message was sent from. Numbers are specified in E.164 format.
447700900000The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.
aaaaaaaa-bbbb-cccc-dddd-0123456789abThe ID of the message
Hello worldThe message body for this inbound message.
textPossible 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.
HELLOThe first word in the message body. Converted to upper case.
{}The time when Vonage started to push this Delivery Receipt to your webhook endpoint.
1578787200A unix timestamp representation of message-timestamp.
aaaaaaaa-bbbb-cccc-dddd-0123456789abA 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.
trueTrue - if this is a concatenated message. This field does not exist if it is a single message
1The transaction reference. All parts of this message share this value.
3The number of parts in this concatenated message.
2The number of this part in the message. Counting starts at 1.
The content of this message, if type is binary.
The hex encoded User Data Header, if type is binary
Example Payload
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 | Information |
|---|---|
| 1 | Description Throttled. You are sending SMS faster than the account limit. Resolution Refer to What is the Throughput Limit for Outbound SMS? for more information. |
| 2 | Description Missing Parameters. Your request is missing one of the required parameters 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 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. |
| 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. |
| 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 or use one of the SDKs to handle the signing. |
| 15 | Description Invalid Sender Address. You are using a non-authorized sender ID in the 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 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 |