Handling SMS Delivery Reports

Once the Message API request is successful, your SMS will be put into a queue to be sent to its destination. Plivo has a throughput of 1 SMS per second. That is, Plivo will send 1 SMS every second for each 'src' (source) number in the API request.

By default, you will not receive an automatic notification regarding the delivery of your SMS. To get notified on the status of your message, include the url parameter in your API request. You can also find your SMS delivery reports in the SMS Logs of your Plivo account. This will automatically output a notification when your SMS reaches its destination, or if it fails to deliver. Your delivery report will update to show either "queued", "sent", "delivered", "undelivered", or "rejected" for each individual recipient.

Note: Long SMS messages are automatically split and concatenated into a seamless user experience. When checking Message Logs and Delivery Reports for long SMS messages that are split, look for the ParentMessageUUID, which is the same in all split messages and identical to the UUID of the first message in the split sequence of messages.
Advanced Hack: Check out our Message API docs to see how you can get the details of a single message or all your messages in a single GET request.

Prerequisites

  1. Sign up for a free Plivo trial account.
  2. Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
  3. Buy a Plivo phone number (optional).
    Note: A phone number is required only for sending SMS to US and Canadian phone numbers. However, country-specific carrier conditions may still apply. You can buy a US or Canadian phone number through the Buy Numbers tab on your Plivo account UI.
  4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.
    Note: If you are using a Plivo Trial account for this example, you can only send sms to phone numbers that have been verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.

Set up a Web Server

Let’s assume your web server is located at http://example.com. Below is a snippet to set up a route on your webserver. Now when we send an HTTP request to http://example.com/delivery_report/ this route will be invoked. This route will be the 'url' parameter when sending an sms using the Message API.

Note: For PHP, the route will be example.com/delivery_report.php.

  1. Copy the relevant code below into a text file and save it. Lets call it, 'delivery_report'.
  2. Customize the delivery report to include the parameters you need.

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import plivo, plivoxml
from flask import Flask, request

app = Flask(__name__)

@app.route("/delivery_report/", methods=['GET','POST'])
def report():
    # Sender's phone number
    from_number = request.values.get('From')
    # Receiver's phone number - Plivo number
    to_number = request.values.get('To')
    # Status of the message
    status = request.values.get('Status')
    # Message UUID
    uuid = request.values.get('MessageUUID')

    # Prints the status of the message
    print "From: %s, To: %s, Status: %s, MessageUUID: %s" % (from_number, to_number, status, uuid)
    return "Delivery status reported"

if __name__ == '__main__':
    app.run(host='0.0.0.0', debug=True)
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
require 'sinatra'
require 'plivo'
include Plivo

post '/delivery_report/' do
    # Sender's phone number
    from_number = params[:To]
    # Receiver's phone number - Plivo number
    to_number = params[:From]
    # Status of the message
    status = params[:Status]
    # Message UUID
    uuid = params[:MessageUUID]

    # Prints the status of the message
    puts "From: #{from_number}, To: #{to_number}, Status: #{status}, MessageUUID: #{uuid}"

    "Delivery status reported"
end
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
var plivo = require('plivo');
var express = require('express');
var bodyParser = require('body-parser');
var app = express();

app.use(bodyParser.urlencoded({extended: true}));
app.set('port', (process.env.PORT || 5000));
app.all('/delivery_report/', function(request, response) {
    // Sender's phone number
    var from_number = request.body.From || request.query.From;
    // Receiver's phone number - Plivo number
    var to_number = request.body.To || request.query.To;
    // Status of the message
    var status = request.body.Status || request.query.Status;
    // Message UUID
    var uuid = request.body.MessageUUID || request.query.MessageUUID;

    // Print the status of the message
    console.log ('From: ' + from_number + ', To: ' + to_number + ', Status: ' + status + ', MessageUUID: ' + uuid);
    response.send("Delivery status reported");
});

app.listen(app.get('port'), function() {
    console.log('Node app is running on port', app.get('port'));
});
        
1
2
3
4
5
6
7
8
9
10
11
12
// Sender's phone numer
$from_number = $_REQUEST["From"];
// Receiver's phone number - Plivo number
$to_number = $_REQUEST["To"];
// Status of the message
$status = $_REQUEST["Status"];
// Message UUID
$uuid = $_REQUEST["MessageUUID"];

// Prints the status of the message
echo("From: $from_number, To: $to_number, Status: $status, MessageUUID: $uuid");
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
package com.plivo.test;

import java.io.IOException;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class handleDeliveryReport extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String from_number = req.getParameter("From"); // Sender's phone number
        String to_number = req.getParameter("To"); // Receiver's phone number - Plivo number
        String status = req.getParameter("Status"); // Status of the message
        String uuid = req.getParameter("MessageUUID"); // Message UUID

        // Prints the status of the message
        System.out.println("From: " + from_number + ", To: " + to_number + ", Status: " + status + ", MessageUUID: " + uuid);
        resp.getWriter().print("Delivery status reported");
    }

    public static void main(String[] args) throws Exception {
        String port = System.getenv("PORT");
        if (port==null) port ="8080";
        Server server = new Server(Integer.valueOf(port));
        ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
        context.setContextPath("/");
        server.setHandler(context);
        context.addServlet(new ServletHolder(new handleDeliveryReport()),"/delivery_report/");
        server.start();
        server.join();
    }
}
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
using System;
using System.Collections.Generic;
using System.Reflection;
using Nancy;
using RestSharp;
using Plivo.API;

namespace Handle_delivery
{
    public class Program : NancyModule
    {
        public Program()
        {
            Post["/delivery_report/"] = x =>
            {
                String from_number = Request.Form["From"]; // Sender's phone number
                String to_number = Request.Form["To"]; // Receiver's phone number - Plivo number
                String status = Request.Form["Status"]; // Status of the message
                String uuid = Request.Form["MessageUUID"]; // Message UUID

                // Prints the status of the message
                Console.WriteLine("From: {0}, To: {1}, Status: {2}, MessageUUID: {3}", from_number, to_number, status, uuid);

                return "Delivery status reported";
            };
        }
    }
}
        

Sample Output

From: 1111111111, To: 3333333333, Status: delivered, MessageUUID: 0936ec98-7c4c-11e4-9bd8-22000afa12b9

SMS Delivery and Notifications

The following parameters are then sent to the URL:

Parameter Description
MessageUUID The unique ID for the message.
To Phone number of the recipient.
From The sender ID used as the source address for the message.
Status Status of the message including “queued”, “sent”, “failed”, “delivered”, “undelivered” or “rejected”.
Units Number of units into which a long SMS was split
TotalRate This is the charge applicable per outbound SMS unit.
TotalAmount Total charge for sending the SMS (TotalRate * No. of Units)
MCC Mobile Country Code of the To number. (See here for more details)
MNC Mobile Network Code of the To number. (See here for more details)
ErrorCode The Plivo error code which identifies the reason for the message delivery failure. This parameter is only defined for ‘failed’ or ‘undelivered’ messages.
ParentMessageUUID (reserved for future use) Same as the MessageUUID. This parameter is reserved for future use, and should be ignored for now.
PartInfo (reserved for future use) This parameter is reserved for future use, and should be ignored for now.

Next Step

Learn how to forward sms to your email.

  1. Send a Single SMS
  2. Send a Long SMS
  3. Send Multiple (Bulk) SMS
  4. Send an SMS with Alphanumeric Sender ID
  5. Receive an SMS
  6. Reply to an Incoming SMS
  7. Forward an Incoming SMS
  8. Get Details of all Messages
  9. Get Details of a Single Message
  10. Handling SMS Delivery Reports
  11. Forward SMS to Email