Alerts - Sending API Reference
Action Needed For Vonage Customers Using US Shared Short Codes
Effective immediately, Vonage will no longer accept new programs for Shared Short Codes for A2P messaging. T-Mobile and AT&T's new code of conduct prohibits the use of shared originators for A2P (application to person) traffic. Please migrate any existing Shared Short Code traffic to one of our alternative solutions. To help you with this transition, please use the Vonage guide to alternatives. Please contact us to migrate to a new solution.
This defines Event Based Alerts API:
- Request - send an Event Based Alert to you user. If you have multiple templates, remember to set the template number in your request.
-
Response - Check the
status
field to ensure that you sent the request to Vonage correctly. - Delivery receipt - verify that the Event Based Alert was delivered.
Request
Before calling this API, you need to configure your message in the Dashboard. A message template normally contains custom parameters that you supply in your request.
A basic Short Code Event Based Alert request looks like:
https://rest.nexmo.com/sc/us/alert/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&to=xxxxxxxxxxxx
If you have a template in the form:
Your ${server} is down, for more details check ${link}
Your request will be:
https://rest.nexmo.com/sc/us/alert/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&to=xxxxxxxxxxxx&server=host3&link=https://example.com/host3/mon
This request contains:
- A Base URL
- Parameters
- Authentication information
- Security
- Encoding
Base URL
All requests to the Short Code Event Based Alert API must contain:
https://rest.nexmo.com/sc/us/alert
- A response object: json or xml
Your base URL becomes either:
JSON | XML |
---|---|
https://rest.nexmo.com/sc/us/alert/json |
https://rest.nexmo.com/sc/us/alert/xml |
Parameters
The following table shows the parameters you use in the request:
Parameter | Description | Required |
---|---|---|
to |
The single phone number to send pin to. Mobile number in US format and one recipient per request. For example, to=16365553226. | |
status-report-req |
Set to 1 to receive a delivery receipt. To receive the delivery receipt, you have to configure a webhook endpoint in Dashboard. |
❎ |
client-ref |
A 40 character reference string for your internal reporting. | ❎ |
template |
If you have multiple templates, this is the index of the template to call. The default template starts is 0, each Event Based Alert campaign can have up to 6 templates. If you have one template only it is the default. That is, template=0. If you create a request with template=1 the API call will default, template=0 instead. After you add a valid campaign alert for 2FA, the request will call template 1 instead of template 0. |
❎ |
type |
Default value is text. Possible values are: text for plain text SMS or unicode only use this when your SMS must contain special characters. |
❎ |
custom |
Any custom parameters you need for template. | ❎ |
Security
To ensure privacy, you must use HTTPS for all Vonage API requests.
Encoding
You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:
application/json
application/jsonrequest
application/x-javascript
text/json
text/javascript
text/x-javascript
-
text/x-json
when posting parameters as a JSON object.
Response
Each request you make using the SMS API returns a:
- Response - the status and price of your request to Vonage in JSON or XML format.
- Delivery receipt - the status and cost of the SMS sent by Vonage to your user.
Note: you are only charged for correctly submitted outbound SMS. If status is not 0, you are not charged.
The response is send in the api.txt file when you make a request from the browser.
Each response comes:
- In a specific Format
- With Keys and values
Format
You set the response type using the Base URL. The following table shows example responses in JSON or XML:
{
"message-count":"1",
"messages":[
{
"status":"returnCode",
"message-id":"messageId",
"to":"to",
"client-ref":"client-ref",
"remaining-balance":"remaining-balance",
"message-price":"message-price",
"network":"network",
"error-text":"error-message"
}
]
}
<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
<messages count='x'>
<message>
<messageId>${messageId}</messageId>
<to>${to}</to>
<clientRef>${client-ref}</clientRef>
<status>${returnCode}</status>
<errorText>${error-message}</errorText>
<remainingBalance>${account-balance}</remainingBalance>
<messagePrice>${message-price}</messagePrice>
<network>${network}</network>
</message>
</messages>
</mt-submission-response>
Keys and Values
The response contains the following keys and values.
Key | Description |
---|---|
message-count |
The number of parts the message was split into. |
messages |
Contains each message part. |
status |
The processing status of the message. |
message-id |
The ID of the SMS that was submitted (8 to 16 characters). |
to |
The phone number your request was sent to. |
client-ref |
The client-ref you set in your request. |
remaining-balance |
The remaining balance in your account. The value is in EUR. |
message-price |
The price charged for your request. The value is in EUR. |
network |
The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier of the recipient. |
error-text |
If an error occurred, this explains what happened. |
Key | Description |
---|---|
messages |
Contains each message part. The count attribute contains the number of message parts. |
message |
A single message part. |
status |
The processing status of the message. |
messageId |
The ID of the SMS that was submitted (8 to 16 characters). |
to |
The phone number your request was sent to. |
clientRef |
The client-ref you set in your request. |
remainingBalance |
The remaining balance in your account. The value is in EUR. |
messagePrice |
The price charged for your request. The value is in EUR. |
network |
The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier of the recipient. |
errorText |
If an error occurred, this explains what happened. |
Delivery Receipt
Each request you make using the Vonage API returns a:
- Response - the status and cost of your request to Vonage in JSON or XML format.
- Delivery Receipt - if you have set a webhook endpoint, Vonage forwards this delivery receipt to it. Carriers return a Delivery Receipt (DLR) to Vonage to explain the delivery status of your message. If the message is not received, the delivery receipt explains why your message failed to arrive.
The Delivery Receipt is sent using a GET HTTP request to your webhook endpoint. When you receive the DLR, you must send a 200 OK response. If you do not send the 200 OK
, Vonage resends the delivery receipt for the next 72 hours. Please ensure that you have configured a webhook endpoint in the Vonage dashboard.
When you implement your response, ensure that your logic is not case-sensitive for the response codes.
A Delivery Receipt has a:
- Format
- Keys and Values
Format
The following code shows an example of a Delivery Receipt:
?msisdn=66837000111&to=12150000025&network-code=52099&messageId=000000FFFB0356D2&price=0.02000000&status=delivered&scts=1208121359&err-code=0&message-timestamp=\2020-01-01\+12%3A00%3A00
{
"msisdn": "447700900000",
"to": "447700900001",
"network-code": "52099",
"messageId": "02000000E68951D8",
"price": "0.02000000",
"status": "delivered",
"scts": "1208121359",
"err-code": "0",
"message-timestamp": "2020-01-01 12:00:00"
}
Keys and Values
The Delivery Receipt includes:
Key | Value |
---|---|
to |
The SenderID you set in from in your request. |
network-code |
The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with. |
messageId |
The Vonage ID for this message. |
msisdn |
The phone number this message was sent to. |
status |
A code that explains where the message is in the delivery process., If status is not delivered check err-code for more information. If status is accepted ignore the value of err-code. Possible values |
err-code |
If the status is not accepted, this key will have one of the these possible values |
price |
How much it cost to send this message. |
scts |
The Coordinated Universal Time (UTC) when the DLR was received from the carrier. The scts is in the following format: YYMMDDHHMM. For example, 1101181426 is 2011 Jan 18th 14:26. |
message-timestamp |
The time at UTC±00:00 when Vonage started to push this Delivery Receipt to your webhook endpoint. The message-timestamp is in the following format YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00. |
client-ref |
The client-ref you set in the request. |
status
values
Key | Value |
---|---|
delivered |
this message has been delivered to the phone number. |
expired |
the target carrier did not send a status in the 72 hours after this message was delivered to them. |
failed |
the target carrier failed to deliver this message. |
rejected |
the target carrier rejected this message. |
accepted |
the target carrier has accepted to send this message. |
buffered |
This message is in the process of being delivered. |
unknown |
the target carrier has returned an undocumented status code. |
Code | Description |
---|---|
0 |
Delivered. |
1 |
Unknown - either: 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. |
2 |
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. |
3 |
Absent Subscriber Permanent - to is no longer active, you should remove this phone number from your database. |
4 |
Call barred by user - you should remove this phone number from your database. If the user wants to receive messages from you, they need to contact their carrier directly. |
5 |
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. |
6 |
Anti-Spam Rejection - carriers often apply restrictions that block messages following different criteria. For example, on SenderID or message content. |
7 |
Handset Busy - the handset associated with to was not available when this message was sent. If status is Failed, this is a temporary failure; retry later for a positive result. If status is Accepted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours. |
8 |
Network Error - a network failure while sending your message. This is a temporary failure, retry later for a positive result. |
9 |
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. |
10 |
Invalid Message - the message could not be sent because one of the parameters in the message was incorrect. For example, incorrect type or udh. |
11 |
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 sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com. |
12 |
Destination unreachable - the message could not be delivered to the phone number. |
13 |
Subscriber Age Restriction - the carrier blocked this message because the content is not suitable for to based on age restrictions. |
14 |
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. |
15 |
Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message. |
99 |
General Error - there is a problem with the chosen route to send your message. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com. |