Available Operations
Authentication
This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.
You can use either JWT or Basic authentication, but not both at the same time.
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Hello from Vonage!The text of message to send; limited to 1000 characters. Unless unless text or unicode has been explicitly set as the value for sms.encoding_type, the Messages API automatically detects whether unicode characters are present in text and sends the message as appropriate as either a text or unicode SMS. For more information on concatenation and encoding please visit: developer.vonage.com/messages/guides/sms/concatenation-and-encoding.
715447700900000The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.
447700900001The phone number of the message sender in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
smsThe channel to send to. You must provide sms in this field
sms90000The duration in seconds 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.
An object of optional settings for the SMS message.
textThe encoding type to use for the message. If set to either text or unicode the specified type will be used. If set to auto (the default), the Messages API will automatically set the type based on the content of text; i.e. if unicode characters are detected in text, then the message will be encoded as unicode, and otherwise as text.
textunicodeauto1107457532145798767A 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"
1101456324675322134A 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
v1Specifies which version of the Messages API will be used to send Status Webhook messages for this particular message. For example, if v0.1 is set, then the JSON body of Status Webhook messages for this message will be sent in Messages v0.1 format. Over-rides account-level and application-level API version settings on a per-message basis.
v0.1v1abc123Client reference of up to 100 characters. The reference will be present in every message status.
https://example.com/statusSpecifies the URL to which Status Webhook messages will be sent for this particular message. Over-rides account-level and application-level Status Webhook url settings on a per-message basis.
textThe type of message to send. You must provide text in this field
textExample Request
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Your JSON web token. | Headers | Bearer <JWT> |
revokedThe status to set for the message. Setting the status of an outbound RCS message to revoked revokes that message if possible. See RCS Message Revocation for more information.
revokedExample Request»RCS
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
aaaaaaaa-bbbb-4ccc-8ddd-0123456789abThe UUID of the message
715447700900000The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.
447700900001The phone number of the message sender in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
2025-02-03T12:14:25ZThe datetime of when the event occurred, in ISO 8601 format.
submittedThe status of the message.
submitteddeliveredrejectedundeliverableIf the message encountered a problem a descriptive error will be supplied in this object.
https://developer.vonage.com/api-errors/messages#1000The type of error encountered, follow URL for more details
1000The error code encountered when sending the message. See our errors list for a list of possible errors
Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retryText describing the error. See our errors list for a list of possible errors
bf0ca0bf927b3b52e3cb03217e1a1ddfThe record id of this error's occurrence.
abc123Client reference of up to 100 characters. Only present if this was set in the associated outbound message.
EURThe charge currency in ISO 4217 format.
EUR0.0333The charge amount as a stringified number.
smsThe channel for the message to which this status relates.
sms12345Code indicating the terminating network for the number to which the message was sent. May not always be included in the message status data.
Channel specific metadata for SMS
2The number of SMS messages concatenated together to comprise the submitted message. SMS messages are 160 characters, if a submitted message exceeds that size it is sent as multiple SMS messages. This number indicates how many SMS messages are required.
Example Payload
smsThe channel the message came in on
smsaaaaaaaa-bbbb-4ccc-8ddd-0123456789abThe UUID of the message
715447700900000The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.
447700900001The phone number of the message sender in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
2025-02-03T12:14:25ZThe datetime of when the event occurred, in ISO 8601 format.
Hello From Vonage!The UTF-8 encoded text of the inbound message.
Channel specific metadata for SMS
2The number of inbound SMS messages concatenated together to comprise this message. SMS messages are 160 characters, if an inbound message exceeds that size they are concatenated together to form a single message. This number indicates how many messages formed this webhook.
HELLOThe first word of the message sent to uppercase.
EURThe charge currency in ISO 4217 format.
EUR0.0333The charge amount as a stringified number.
12345The network code of the network from which the message originated (if available).
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 |
|---|---|
| 1000 | Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry |
| 1010 | Missing params - Your request is incomplete and missing some mandatory parameters. |
| 1020 | Invalid params - The value of one or more parameters is invalid. |
| 1021 | Invalid tag - The tag value is invalid. |
| 1022 | Invalid template - Invalid template or template parameters |
| 1030 | Internal error - There was an error processing your request in the Platform. |
| 1040 | Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number. |
| 1050 | Number barred - The number you are trying to submit to is blacklisted and may not receive messages. |
| 1060 | Partner account barred - The |
| 1070 | Partner quota exceeded - Your pre-paid account does not have sufficient credit to process this message. |
| 1080 | Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API. |
| 1090 | Message too long - The length of |
| 1100 | Communication Failed - Message was not submitted because there was a communication failure. |
| 1120 | Illegal Sender Address - rejected - Due to local regulations, the |
| 1130 | Invalid TTL - The value of |
| 1140 | Facility not allowed - Your request makes use of a facility that is not enabled on your account. |
| 1150 | Invalid Message class - The value of |
| 1160 | Non White-listed Destination - The 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. |
| 1170 | Invalid or Missing Msisdn Param - The phone number you supplied in the to parameter of your request was either missing or invalid. |
| 1180 | Absent Subscriber Temporary - This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result. |
| 1190 | Absent Subscriber Permanent - |
| 1200 | Portability Error - There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly. |
| 1210 | Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content. |
| 1220 | Handset Busy - The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours. |
| 1230 | Network Error - A network failure while sending your message. This is a temporary failure, retry later for a positive result. |
| 1240 | Illegal Number - You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you. |
| 1241 | Too many send requests - Too many send requests to phone numbers. |
| 1250 | Unroutable - The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message. |
| 1251 | Unable to route traffic to a destination - This may be due to the routing rules applied for your destination network. |
| 1260 | Destination unreachable - The message could not be delivered to the phone number. If using Viber Business Messages your account might not be enabled for this country. |
| 1270 | Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions. |
| 1280 | Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended. |
| 1282 | 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. |
| 1290 | Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message. |
| 1300 | Not part of the provider network - The number or ID is not a user in the provider network. |
| 1310 | Not suitable device - The user's device can't receive the message. |
| 1320 | Message already sent - The message was already sent. |
| 1330 | Unknown - An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid. |
| 1331 | Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time. |
| 1340 | Outside of the allowed window - This message is sent outside of allowed response window. |
| 1350 | Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page. |
| 1360 | TTL was activated. |
| 1370 | Expired access Token - Please reauthenticate your Facebook Page with Vonage. |
| 1380 | Invalid resource - Please check that the URL your provided to your resource is accessible and valid. |
| 1381 | Resource size is too large - Please try sending a smaller media file. |
| 1382 | Resource type is invalid - Please check that the file you are trying to send is valid. |
| 1400 | Unsupported channel - The channel specified in the request is not supported. |
| 1410 | Invalid channel parameters - The value of one or more parameters is invalid. |
| 1420 | Invalid sender - The |
| 1430 | Invalid recipient - The |
| 1440 | Invalid message type - The message type specified in the request is not supported for the given channel. |
| 1450 | Invalid client reference - The client reference can be a string of up to 100 characters. |
| 1451 | Invalid context - the reference to the original message could not be found because it is invalid or no longer available. |
| 1460 | Daily message limit exceeded - Check compliance with regulations such as 10DLC. |
| 1461 | Auto-limiting of messages by Provider - This message was not delivered by Provider to avoid excessive messages to the end user. For details please see this knowledgebase article. |
| 1470 | Fraud Defender Traffic Rule - Rejected due to prefix block list. |
| 1471 | Abnormal Sequential Dialing Detected - The High Density Contact Number Range threshold has been exceeded. |
| 1472 | Abnormal Traffic Burst Detected - The Relative Increase threshold has been exceeded. |
| 1473 | AIT protection - Enforcer reject due to AIT intelligence DB. |
| 1474 | Fraud Score Exceeded - Enforcer reject due to fraud score threshold breach. |
| 1480 | Entity Filter - The message failed due to |
| 1481 | Header Filter - The message failed because the header ID ( |
| 1482 | Content Filter - The message failed due to |
| 1483 | Consent Filter - The message failed due to consent not being authorized. More information on country specific regulations. |
| 1484 | Regulation Error - Unexpected regulation error - contact support. |