Receiving Delivery Status via Webhook

In this section, we will provide instructions on how to set up DLR Webhook and receive delivery receipts from operators.

Unifonic provides SMS delivery status tracking with a webhook solution. Webhooks are user-defined HTTPS callbacks. They are usually triggered by some event, such as receiving an SMS message by the end-user handset or an incoming WhatsApp Business message.
When that event occurs, Unifonic makes an HTTPS POST request to the URL configured by the customer for the webhook. SMS Delivery status is tracked based on DLR (Delivery Receipt) – a signal that Unifonic receives from mobile operators.

There are Positive DLR and Negative DLR signals that we can receive from a mobile operator.

• Positive DLR is a confirmation that SMS has been received by the mobile handset. Normally, it means that an end-user has been notified about an incoming message by their mobile phone. This signal does NOT specify whether a message has been opened and read by the human.

• Negative DLR is a confirmation that SMS has NOT been delivered to the mobile device because of various reasons which are out of Unifonic's control.

📘

Example

1. An example of a reason for receiving a Negative DLR could be Absent Subscriber i.e. when a handset has been out of coverage for 48 hours or more and the mobile operator has dropped the message.
2. If the end user’s mobile device is switched off, the message is attempted to be delivered when the end user’s handset is switched on and can once again receive messages. For example, a handset would be able to receive messages again upon re-entering a coverage area or turning off Airplane Mode.

📘

Note

A mobile operator might not send us the delivery receipt for a message, in that case, the delivery status via webhook is not triggered.

For more information on the delivery status, see Understanding SMS Delivery

How To Set Up a DLR Webhook

In your unifonic account, click on Developers> Webhook management.

Then click on ADD NEW WEBHOOK

Add a webhook name, the endpoint URL in which the callback will be sent, click on active, and then click on ADD EVENT

In the events, select the Product: sms and Event type:dlr

The payload of the webhook will be displayed; it can be modified to receive a customized version based on the relevant parameters for your integration.

Finally, click on SAVE

Request Parameters

• This is an example of POST request payload Unifonic will send to the DLR Webhook indicating a successful SMS delivery:

{
  "body": {
    "submitUnitCount": "1",
    "deliveredUnitCount": "1",
    "submitDate": "202402211640",
    "doneDate": "202402211641",
    "finalStatus": "DELIVRD",
    "errorCode": "000",
    "freeText": "hello",
    "destinationAddress": "9665534XXXXX",
    "correlationId": "correlationId",
    "messageId": "41000032776314"
  },
  "timeStamp": "2024-02-21T16:41:00+00:00",
  "eventName": "dlr",
  "productName": "sms",
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865bacc"
}

• Here is an example of a delivery receipt indicating non-delivery from the operator's side:

{
  "body": {
    "submitUnitCount": "1",
    "deliveredUnitCount": "1",
    "submitDate": "202402211640",
    "doneDate": "202402211641",
    "finalStatus": "UNDELIV",
    "errorCode": "000",
    "freeText": "223203",
    "destinationAddress": "9665534XXXXX",
    "correlationId": "correlationId",
    "messageId": "41000032776314"
  },
  "timeStamp": "2024-02-21T16:41:00+00:00",
  "eventName": "dlr",
  "productName": "sms",
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865bacc"
}