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
- 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.
- 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
- At the moment (September 2022) any customer can request to enable DLR Webhook via Unifonic Customer Support. Customers will need to provide an 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 a 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"
}
Parameter | Description |
---|---|
deliveredUnitCount | A number of SMS parts delivered to the mobile device |
doneDate | A timestamp in mobile operator SMSC timezone when a message has been delivered to the mobile device |
errorCode | Currently not used, will be used for non-delivery error code indication in future updates |
finalStatus | DELIVRD or DELIVERED means that the mobile operator indicated the SMS has been delivered to the end user's mobile device |
freeText | A fragment of the original SMS message body - for troubleshooting purposes |
id | SMS segment ID |
messageId | Unifonic message ID |
submitDate | A timestamp in the mobile operator SMSC timezone when a message has been submitted to the mobile operator by Unifonic or one of Unifonic's partner providers |
submitUnitCount | A number of SMS parts submitted |
accountId | Customer's account ID in Unifonic |
timeStamp | A timestamp when the delivery receipt was received from the operator, can be used for approximate end-to-end delivery latency calculations |
eventName | "dlr" - for SMS delivery receipt |
productName | "sms" - for SMS delivery receipt |
Updated 8 months ago