Delivery Reports


    Once the Message API request is successful, your SMS will be put into a queue to be sent to its destination. 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 "failed" 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 `MessageUUID`, 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.


    In this section, we will guide you to build an app to Receive Delivery Reports.


    1. Plivo account: Sign up for a Plivo account if you don’t have one already.
    2. Plivo phone number:: To receive MMS, you must have a Plivo phone number that supports MMS. You can purchase numbers from the Numbers page of the Plivo console or by using the Numbers API.

    Buy a New Plivo Number

    Install Java, Spring and the Plivo Java package

    You must set up and install Java(Java 1.8 or higher) and Plivo’s Java SDK to Receive Delivery Reports. Here’s how.

    Install Java

    Operating SystemInstructions
    macOS & LinuxTo see if you already have Java installed, run the command java -version in the terminal. If you do not have it installed, you can install it from here.
    WindowsTo install Java on Windows follow the instructions listed here.

    Install Spring and Plivo Java Package using IntelliJ Idea

    • Use Spring Initializr to create a boilerplate project with Spring Boot framework.

      Create Boilerplate code

    • Choose the “Spring Web” dependency, Give the project a friendly name and click “Generate” to download the boilerplate code and open it in IntelliJ Idea.

      Boilerplate project in IntelliJ

      Note: Please set the Java target as 11.
    • Install the Plivo Java package by adding the dependency in pom.xml


      Install Plivo package

    Create a Spring Webapp to Deliver Reports

    Now, import the downloaded folder from Spring Initializr & open the file PlivoSmsApplication and paste the below code

    package com.example.Plivo.SMS;
    import com.plivo.api.exceptions.PlivoXmlException;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    public class PlivoSmsApplication {
    	public static void main(String[] args) {, args);
    	@GetMapping(value = "/delivery_reports/")
    	public String getBody(String From, String To, String Text, String MessageUUID) throws PlivoXmlException {
    		System.out.println(From + " " + To + " " + Text+ " " + MessageUUID);
    		return "Delivered";

    Run the project and you should see your basic server app in action on http://localhost:8080/delivery_reports/

    Exposing your local server to the internet

    To receive delivery reports incoming messages and to handle callbacks, your local server should be able to connect with Plivo API service, Ngrok is a tunneling software used to expose a web server running on your local machine to the internet. Using Ngrok you can set webhooks which can talk to Plivo server.

    ngrok block diagram

    Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (8080 in this case):

    $ ./ngrok http 8080

    Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network.

    Sample ngrok CLI

    In this case, the ngrok url will be something like

    Create an Application

    1. Create an Application by visiting the Application Page and click on New Application. You can also use Plivo’s Application API.
    2. Give your application a name. Let’s call it Delivery Reports. Enter your server URL (e.g. in the Message URL field and set the method as GET. See our Application API docs to learn how to modify your application through our APIs.
    3. Click on Create Application to save your application.

    Create Application

    Assign a Plivo number to your app

    1. Navigate to the Numbers page and select the phone number you want to use for this app.
    2. Select Delivery Reports (name of the app) from the Plivo App dropdown list.
    3. Click on Update Number to save.

    Assign Phone Number to Receive Delivery Reports

    Test and validate

    Send an SMS to your Plivo number using a regular mobile phone. Plivo will send a request to your Message URL with the parameters listed in the Messages Documentation.