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 Helper Libraries 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
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
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
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
13
<?php
    // 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
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
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
To The number to which the SMS was sent.
From The number from which the SMS was sent.
Status The status of the message. Possible statuses include: 'queued', 'sent', 'failed', 'delivered', 'undelivered' or 'rejected'
MessageUUID A unique ID for the message
ParentMessageUUID ID of the first part of the message in case of a Long SMS
PartInfo Specifies the sequence of the message (useful for long messages split into multiple text messages)
Units Number of units into which a Long Message was split
TotalRate Cost per SMS unit
TotalAmount Total cost of the sent SMS
MNC Mobile Network Code of the destination number
MCC Mobile Country Code of the destination number

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. Forward SMS to Email