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 states see Understanding SMS Delivery

How To Set Up a DLR Webhook

• At the moment (September 2022) any customer can request to enable DLR Webhook via Unifonic Customer Support. Customer will need to provide HTTPS endpoint capable of accepting POST requests from Unifonic.

Request Parameters

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

{
     "body": {
         "deliveredUnitCount": "1",
         "doneDate": "20220904162355",
         "errorCode": "000",
         "finalStatus": "DELIVRD",
         "freeText": "webhook",
         "id": "127011000000026C20001400018308ABE67E003E6D",
         "messageId": "41000347193391",
         "submitDate": "20220904162347",
         "submitUnitCount": "1"
    },  
  "timeStamp": "2022-09-04T13:23:56.487581Z",  
  "eventName": "dlr",  
  "productName": "sms",  
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865bacc"
}

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

{
  "body": {
    "deliveredUnitCount": "1",
    "doneDate": "20220809134254",
    "errorCode": "000",
    "finalStatus": "UNDELIV",
    "freeText": "Hello",
    "id": "127011000000026B800008500182823318FC00xxxx",
    "messageId": "4100033113xxxx",
    "submitDate": "20220809134244",
    "submitUnitCount": "1"
  },
  "timeStamp": "2022-08-09T10:42:56.648988Z",
  "eventName": "dlr",
  "productName": "sms",
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865xxxx"
}