README.md

Receive an SMS Delivery Receipt

Specification

A building block that shows how to handle an inbound call

• You must specify one endpoint must be on the path /webhooks/delivery-receipt
• Your endpoint must be accessible on GET and on POST requests
• Your endpoint must listen on port 3000
• Your response should return a 204 status code
• Your endpoint should handle query string parameters on GET
• Your endpoint should handle application/x-www-form-urlencoded parameters on POST
• Your endpoint should handle JSON on POST

Note: Please test using all three settings in Dashboard > Settings: GET, POST & POST-JSON.

• Code examples should include a GitHub link to the file
• Code examples should include the line numbers used from the linked file
• All code examples must be present in the master branch of the relevant quickstart repo
• All code examples must be tested to work (manual testing is fine)

Instructions

1. Fork this gist
2. Edit the gist and the building block files to match the specification
3. Return Gist as a comment in the original issue

receive-an-sms-delivery-receipt.md

Receive an SMS Delivery Receipt

You can subscribe to be notified of the delivery status of your outbound messages. This example shows you how to configure your webhook and implement the endpoint.

Implement a webhook endpoint

// GITHUB: https://github.com/nexmo-community/nexmo-java-quickstart/blob/master/src/main/java/com/nexmo/quickstart/sms/ReceiveDLR.java#L12-L35
// Lines: 12-35

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 {
        IncomingDlrPayload jsonPayload = IncomingDlrPayload.fromJson(req.bodyAsBytes());
        System.out.println(jsonPayload);
    }

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

Run your server

Add the following dependencies to your project:

compile 'com.nexmo:client:3.1.0'
compile "com.sparkjava:spark-core:2.6.0"

Then run your class in whichever way you find easiest.

You'll need to expose your server to the open internet. During development you can use a tool like Ngrok to do that.

Configure your SMS endpoint with Nexmo

From Nexmo Dashboard go to Settings and enter your endpoint in the field labeled Webhook URL for Delivery Receipt.

Send an outbound SMS

Now when you send an outbound SMS with Nexmo you should see the status logged to your console.

$ nexmo sms YOUR_NUMBER 'A text message sent using the Nexmo SMS API'