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
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"
}
Parameter | Description |
---|---|
submitUnitCount | Number of SMS of the submitted message |
deliveredUnitCount | A number of SMS parts delivered to the mobile device |
submitDate | A timestamp when the message was triggered. |
doneDate | A timestamp in mobile operator SMSC timezone when a message has been delivered to the mobile device |
finalStatus | DELIVRD or DELIVERED means that the mobile operator indicated the SMS has been delivered to the end user's mobile device |
errorCode | Currently not used, will be used for non-delivery error code indication in future updates |
freeText | A fragment of the original SMS message body - for troubleshooting purposes (DLR nature) |
destinationAddress | Mobile Number/ Recipient |
correlationId | Unique identifier sent via API. |
messageId | Unifonic message ID |
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 |
accountId | Customer's account ID in Unifonic |
Updated 4 months ago