Delivery Receipts

You can verify that a message you sent using the Vonage SMS API reached your customer by requesting a delivery receipt from the carrier.

NOTE: Not all networks and countries support delivery receipts. You can check our knowledge base for some further information on what you might receive if your network does not support delivery receipts. For detailed information on delivery receipts see our documentation.

To access the delivery receipt, you need to:

Create a webhook endpoint using one of the code examples shown below
Configure the webhook endpoint in your Vonage Dashboard

NOTE: After you send a message there may be a delay before you receive the delivery receipt.

Prerequisites

npm install express body-parser

Write the code

Add the following to dlr-express.js:

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

const handleDeliveryReceipt = (request, response) => {
  const params = Object.assign(request.query, request.body);
  console.log(params);
  response.status(204).send();
};

app
  .route('/webhooks/delivery-receipt')
  .get(handleDeliveryReceipt)
  .post(handleDeliveryReceipt);

app.listen(process.env.PORT || 3000);

View full source

Run your code

Save this file to your machine and run it:

node dlr-express.js

Prerequisites

Add the following to build.gradle:

implementation 'io.ktor:ktor-server-netty'
implementation 'io.ktor:ktor-serialization-jackson'

Write the code

Add the following to the main method of the ReceiveSmsDlr file:

embeddedServer(Netty, port = 8000) {
    routing {
        route("/webhooks/delivery-receipt") {
            handle {
                if (call.request.queryParameters.isEmpty()) {
                    val json = call.receive<String>()
                    println(json)
                }
                else {
                    call.request.queryParameters.forEach { key, values ->
                        println("$key: ${values.first()}")
                    }
                }
                call.respond(HttpStatusCode.NoContent)
            }
        }
    }
}.start(wait = true)

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.sms with the package containing ReceiveSmsDlr:

gradle run -Pmain=com.vonage.quickstart.kt.sms.ReceiveSmsDlr

Prerequisites

Add the following to build.gradle:

implementation 'com.vonage:server-sdk:8.15.1'
implementation 'com.sparkjava:spark-core:2.9.4'

Write the code

Add the following to the main method of the ReceiveDLR file:

port(3000);

get("/webhooks/delivery-receipt", (req, res) -> {
    for (String param : req.queryParams()) {
        System.out.printf("%s: %s\n", param, req.queryParams(param));
    }
    res.status(204);
    return "";
});

post("/webhooks/delivery-receipt", (req, res) -> {
    // The body will be form-encoded or a JSON object:
    if (req.contentType().startsWith("application/x-www-form-urlencoded")) {
        for (String param : req.queryParams()) {
            System.out.printf("%s: %s\n", param, req.queryParams(param));
        }
    } else {
        System.out.println(req.body());
    }

    res.status(204);
    return "";
});

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.vonage.quickstart.sms with the package containing ReceiveDLR:

gradle run -Pmain=com.vonage.quickstart.sms.ReceiveDLR

Prerequisites

Install-Package Vonage

Create a file named SmsController.cs and add the following code:

{
    [HttpGet("webhooks/inbound-sms")]

View full source

Write the code

Add the following to SmsController.cs:

}

[HttpGet("webhooks/verify-sms")]
public IActionResult VerifySms()
{
    var vonageApiSignatureSecret = Environment.GetEnvironmentVariable("VONAGE_API_SIGNATURE_SECRET") ?? "VONAGE_API_SIGNATURE_SECRET";
    var sms = WebhookParser.ParseQuery<InboundSms>(Request.Query);

View full source

Prerequisites

composer require slim/slim:^3.8 vonage/client

Create a file named index.php and add the following code:

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

View full source

Add the following to index.php:

$app = new \Slim\App;

View full source

Write the code

Add the following to index.php:

$handler = function (Request $request, Response $response) {
    $receipt = \Vonage\SMS\Webhook\Factory::createFromRequest($request);

    error_log(print_r($receipt, true));

    return $response->withStatus(204);
};

$app->map(['GET', 'POST'], '/webhooks/delivery-receipt', $handler);

$app->run();

View full source

Run your code

Save this file to your machine and run it:

php -S localhost:3000 -t .

Prerequisites

pip install fastapi[standard]

Write the code

Add the following to delivery-receipts.py:

from fastapi import FastAPI, Request
from pprint import pprint

app = FastAPI()


@app.get('/delivery-receipt')
async def get_delivery_receipt(request: Request):
    data = await request.json()
    pprint(data)

View full source

Run your code

Save this file to your machine and run it:

fastapi dev delivery-receipts.py

Prerequisites

gem install sinatra sinatra-contrib

Create a file named delivery_receipt.rb and add the following code:

require 'sinatra'
require 'sinatra/multi_route'
require 'json'

helpers do
  def parsed_body
     json? ? JSON.parse(request.body.read) : {}
  end

  def json?
    request.content_type == 'application/json'
  end
end

View full source

Write the code

Add the following to delivery_receipt.rb:

route :get, :post, '/webhooks/delivery-receipt' do
  puts params.merge(parsed_body)
  status 204
end

set :port, 3000

View full source

Run your code

Save this file to your machine and run it:

ruby delivery_receipt.rb

Configure the webhook endpoint in your Vonage Dashboard

So that Vonage knows how to access your webhook, you must configure it in your Vonage account.

In the code snippets, the webhook is located at /webhooks/delivery-receipt. If you are using Ngrok, the webhook you need to configure in your Vonage Dashboard API Settings page is of the form https://demo.ngrok.io/webhooks/delivery-receipt. Replace demo with the subdomain provided by Ngrok and enter your endpoint in the field labeled Webhook URL for Delivery Receipts:

Try it out

Send a message to a mobile number and, if the network supports it, you will receive a delivery receipt in the following format:

{
  "err-code": "0",
  "message-timestamp": "2020-10-25 12:10:29",
  "messageId": "0B00000127FDBC63",
  "msisdn": "447700900000",
  "network-code": "23410",
  "price": "0.03330000",
  "scts": "1810251310",
  "status": "delivered",
  "to": "Vonage"
}

NOTE: After you send a message there may be a delay before you receive the delivery receipt.

More information

SMS Delivery Receipt documentation