Alerts - Sending API Reference

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:

Parameters

The following table shows the parameters you use in the request:

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.

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.

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: