Receiving SMS Delivery Status by Webhook

Configure a webhook to receive SMS delivery receipts (DLRs). When Unifonic receives a DLR from a mobile operator, it sends an HTTPS POST request to your configured endpoint.

Understand delivery receipts

Positive DLR: The operator reports that the SMS reached the recipient's mobile device. This does not confirm that the recipient opened or read the message.
Negative DLR: The operator reports that the SMS was not delivered to the mobile device.

For example, if the recipient is absent, the operator might continue trying to deliver the message for 48 hours or more before returning a final status.

	Operator reporting If the operator does not send a delivery receipt, Unifonic cannot trigger the delivery-status webhook.

For details about message states, see Understanding SMS Delivery.

Configure a DLR webhook

In the Unifonic platform, select Developers > Webhook Management.

Webhook Management option in the Developers menu

Select Add New Webhook.

Add New Webhook button

Enter a webhook name and the HTTPS endpoint URL that will receive callbacks.
Enable Active.
Select Add Event.

Webhook name, endpoint URL, Active option, and Add Event button

For Product, select sms.
For Event type, select dlr.

SMS product and DLR event type selections

Review the displayed webhook payload. Modify it if your integration requires a custom payload.

Editable DLR webhook payload

Select Save.

Payload examples

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": "YOUR_ACCOUNT_ID"
}

SMS non-delivery

{
  "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": "YOUR_ACCOUNT_ID"
}

Payload parameters

Parameter	Description
`submitUnitCount`	Number of SMS parts submitted.
`deliveredUnitCount`	Number of SMS parts delivered to the mobile device.
`submitDate`	Timestamp when the message was triggered.
`doneDate`	Timestamp in the operator SMSC time zone when delivery completed.
`finalStatus`	Final operator status. `DELIVRD` or `DELIVERED` indicates delivery to the recipient's device.
`errorCode`	Reserved for a non-delivery error code; currently not used.
`freeText`	Fragment of the original message body used for DLR troubleshooting.
`destinationAddress`	Recipient's mobile number.
`correlationId`	Unique identifier supplied in the API request.
`messageId`	Unifonic message ID.
`timeStamp`	Timestamp when Unifonic received the DLR from the operator. It can be used to estimate end-to-end delivery latency.
`eventName`	`dlr` for an SMS delivery receipt.
`productName`	`sms` for an SMS delivery receipt.
`accountId`	Customer account ID in Unifonic.