Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Alerts

You use Event Based Alerts to communicate with people using Event Based Alerts. Provision a US Short Code with a standard or custom template that specifies the custom parameters for Alert messages.

Note: quality of delivery (QoD) statistics are based on delivery receipts (DLR). For the US we only receive intermediate and not handset DLRs. This means Dashboard analytics cannot show QoD statistics for short codes.

Sending Alerts

You use Event Based Alerts to send custom messages to your users. Before you use this API you have to Setup a Pre-approved Short Code for Event Based Alerts

The workflow for sending Event Based Alerts is:

Event Based Alerts Workflow

  1. Send an Event Based Alerts request.

  2. Check the response codes in the response and ensure that you sent the request to Nexmo correctly.

  3. Nexmo sends the alert to your user.

  4. Receive the delivery receipt at your webhook endpoint and verify delivery.

Implementing the Event Based Alerts workflow

To send Event Based Alerts to your users:

  1. Send an Event Based Alerts request. If you have multiple templates, remember to set the template number in your request.

    var https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET',
     to: 'TO_NUMBER',
     TEMPLATE_VARIABLE_NAME: 'VALUE'
    });
    
    var options = {
     host: 'rest.nexmo.com',
     path: '/sc/us/alert/json',
     port: 443,
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Content-Length': Buffer.byteLength(data)
     }
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
     res.on('end', function(){
       console.log(JSON.parse(responseData));
     });
    });
    

  2. Check the response codes in the response and ensure that you sent the request to Nexmo correctly:

    // Decode the json object you retrieved when you ran the request.
    
    var decodedResponse = JSON.parse(responseData);
    
    console.log('You sent ' + decodedResponse['message-count'] + ' messages.\n');
    
    decodedResponse['messages'].forEach(function(message) {
        if (message['status'] === "0") {
          console.log('Success ' + decodedResponse['message-id']);
        }
        else {
          console.log('Error ' + decodedResponse['status']  + ' ' +  decodedResponse['error-text']);
        }
    });
    

  3. Nexmo sends the alert to your user.

  4. Receive the delivery receipt at your webhook endpoint so you can see:

    1. If the status was delivered.
    2. When and how the message was made.
    3. How much the message cost.
    var app = require('express')();
    app.set('port', (process.env.PORT || 5000));
    app.use(require('body-parser').urlencoded({
        extended: false
    }));
    // Handle GET webhook
    app.get('/delivery-receipt-webhook', function(req, res) {
        handleWebhook(req.query, res);
    });
    // Handle POST webhook
    app.post('/delivery-receipt-webhook', function(req, res) {
        handleWebhook(req.body, res);
    });
    
    function handleWebhook(params, res) {
        if (!params['status'] || !params['messageId']) {
            console.log('This is not a delivery receipt');
        } else {
            //This is a DLR, check that your message has been delivered correctly
            if (params['status'] !== 'delivered') {
                console.log("Fail:", params['status'], ": ", params['err-code']);
            } else {
                console.log("Success");
              /*
                * The following parameters in the delivery receipt should match the ones
                * in your request:
                * Request - from, dlr - to\n
                * Response - message-id, dlr - messageId
                * Request - to, Responese - to, dlr - msisdn
                * Request - client-ref, dlr - client-ref
               */
            }
        }
        res.sendStatus(200);
    }
    app.listen(app.get('port'), function() {
        console.log('Example app listening on port', app.get('port'));
    });
    

Note: remember to send return 200 ok when you receive the delivery receipt.