Receiving delivery receipts (DLRs)

A delivery receipt (DLR) is a packet of information that contains the delivery status of the message. Delivery receipts allow you to check whether your message has ultimately been received at the destination handset, or whether it never reached the handset and why. There should be one DLR event per MT event.

Mobile API may be configured to send DLR events as webhooks on a specified endpoint. Typically, you should expect a DLR to be sent within seconds of sending a message, but in case the destination handset has issues receiving the message (network issues, it’s turned off, etc.), Mobile API and the carriers may retry sending a message to that device up to 72 hours. If all retries have been exhausted after about 72 hours, you should expect a final DLR indicating delivery failure.

Webhook DLR events

While the payloads for the DLR event are predefined, you will work with your account manager to enable and customize webhook events.

You’ll need to provide this information:

1. Endpoint (mandatory): The URL to which Mobile API will send the event.

2. HTTP verb/method (mandatory): The HTTP method used to send the request. Mobile API supports standard verbs: POST, PUT, PATCH, GET.

3. Custom headers (optional): Custom headers that Mobile API may add to the webhook request.

4. Authentication scheme (optional): You may provide us with credentials to confirm the authenticity of requests being sent to your endpoint. Mobile API currently supports the following authentication schemes:

   • Basic: A username/password combination that is base64 encoded (Base64({username}:{password})).

   • Token: An access token that you can validate. You will also have to provide us with the token header location.

5. In addition to the authentication scheme, Mobile API is able to provide a list of IP ranges for our servers that the client may use as a whitelist to authenticate incoming requests.

After providing this information, you will need to set up the event listeners/handlers on the endpoints you've provided for us. Mobile API will expect that any response with HTTP status code of 200 is a successful confirmation, while any other status response will be considered a failure. In case of failures, Mobile API will retry the request according to an exponential back-off strategy.

After setting up your listeners, you will need to inform us when you want to enable webhooks for DLR events.

DLR payload from Mobile API

A DLR payload supplied from our webhook callback will look like:

{
  "gateway_ref": "1727268401846005014",
  "notified_at": "230327132513",
  "gateway_name": "OpenMarketApi",
  "status_code": "4",
  "delivery_log": "Message Delivered",
  "mt_id": "6421994a500a54428af55384",
  "type": "SMS"
}

where:

• gateway_ref (string, always returned): The message ID on the gateway (message aggregator) used to send the request.

  This may be useful for debugging issues.

• notified_at (string, always returned): The date/time DLR was sent from Mobile API.

  Returned in the format: %y%m%d%H%M%S (for example, 2023-02-12 15:30:00 → "230212153000").

• gateway_name (string, always returned): The name of the gateway that Mobile API used to send the request.

• status_code (string, always returned): The delivery status code.

• delivery_log (string, always returned): A description of or explanation for the status code.

• mt_id (string): The ID of the MT for this delivery receipt, as the id field in the response for sending a message.

  This DLR will update the referenced MT’s status.

• type (string, always returned): The message type: SMS, MMS, or RCS.

• receipt_type (string, only returned for RCS): The type of the receipt (delivery or read). This field is only returned for RCS receipts to differentiate delivery and read receipts. For more information, see Receiving read receipts..

• fallback_from (string, sometimes returned): Returned for fallback messages. This field indicates the original message channel (eg: MMS or RCS) that resulted in the fallback message. For more information, see "Fallback DLRs" section below.

• fallback_mt (object, sometimes returned): Returned for RCS MTs that failed over to SMS. An object that provides information about the fallback MT being sent. For more information, see "Fallback DLRs" section below.

RCS DLR Sample

RCS DLRs will differ slightly from other DLRs:

• The type should be RCS.

• An additional receipt_type field will be included that indicates the type of the receipt (delivery or read).

• The gateway_name may differ for RCS.

• There are different status codes for RCS, which are elaborated in the "DLR status and error codes" section below.

• When an RCS fails over to SMS, there will be an additional fallback_mt object in the DLR, as explained in the next section.

{
  "gateway_ref": "1727268401846005014",
  "notified_at": "230327132513",
  "gateway_name": "InfoBipApi",
  "status_code": "5",
  "delivery_log": "Message has been successfully delivered to the recipient's handset.",
  "mt_id": "6421994a500a54428af55384",
  "type": "RCS",
  "receipt_type": "delivery"
}

Fallback DLRs

When an RCS message falls back to SMS, you should expect two DLRs:

• A DLR for the original RCS MT, taking the form described in the previous section "RCS DLR Sample", indicating that it failed over to SMS.

• A DLR for the dispatched SMS MT indicating the status of the fallback SMS.

Original RCS DLR

{
  "gateway_ref": "WU230-0327G-13257-280K7",
  "notified_at": "230327132513",
  "gateway_name": "InfoBipApi",
  "status_code": "9",
  "delivery_log": "Message was not delivered to the intended recipient and considered undeliverable, typically due to factors such as an invalid or unreachable destination number. Resolution steps involve verifying the accuracy of the recipient's number. If the issue persists, contact Support for assistance.",
  "mt_id": "6421994a500a54428af55384",
  "type": "RCS",
  "receipt_type": "delivery",
  "fallback_mt": {
    "umm_mt_id": "fe665a7d-4347-4bcd-9a35-c51b124740b9",
    "inserted_at": "2024-05-14T15:30:00Z"
  }
}

The fields will retain their semantics from normal RCS DLRs, but there will be an additional fallback_mt object that will convey information about the dispatched fallback SMS:

• umm_mt_id (string, always returned): The ID of the fallback MT.

• inserted_at (string, always returned): An ISO-8601-formatted date-time of when the fallback MT was created.

Fallback SMS DLR

{
  "gateway_ref": "WU230-0327G-13257-280K7",
  "notified_at": "230327132513",
  "gateway_name": "OpenMarketApi",
  "status_code": "4",
  "delivery_log": "Message delivered",
  "mt_id": "6421994a500a54428af55384",
  "type": "SMS",
  "fallback_from": "RCS"
}

The fields will retain their semantics from normal SMS DLRs, but with some differences:

• mt_id: This will represent the originating_platform_mt_id sent in the original RCS request. This will allow you to use this field to determine which MT this DLR belongs to.

• fallback_from: A field indicating this DLR was the result of an RCS message failing over to SMS.

Multi-Channel DLR Webhooks

If you’re using Mobile API to send messages on more than one channel, it is expected that a single webhook configuration will be provided for all channels.

For instance, if you’re sending both SMS and RCS through Mobile API, and you’ve configured a DLR webhook, both SMS and RCS DLRs will be sent on the same URL. A unified schema is used for all our DLRs, which should simplify processing on your webhook handler. In addition, you will be able to use the type field returned in the DLR webhook to determine which channel this DLR was sent for.

DLR status and error codes

Source: "Delivery Receipts and Response Codes," Open Market, https://www.openmarket.com/docs/Content/apis/v4http/delivery-receipts.htm

Source: "Response status and error codes," Infobip, https://www.infobip.com/docs/essentials/response-status-and-error-codes