Disposition notification format¶

Introduction¶

Disposition Notifications are acknowledgments sent back to the sender to confirm the delivery and/or display status of a message.

Requesting disposition notifications¶

When sending a message via Send Message, the sender can request delivery and display acknowledgments by including a disposition_notification node in the message payload, for example:

{
    "from"         : "johndow",
    "password"     : "12345678",
    "sms_to"       : "+1(555)123-1234",
    "sms_body"     : "Hello World",
    "content_type" : "text/plain",
    "disposition_notification" : "xkXRBMCL.twvNcfC9:positive-delivery, display"
}

Format¶

The disposition_notification node follows this structure:

{
    "disposition_notification": "message_id:notification-types"
}

message_id

A unique identifier for the message generated by sender, used to correlate the notification with the original message.

notification-types

A comma-separated list specifying the types of notifications requested. Valid values are:

positive-delivery: Requests a delivery notification when the message is delivered to the recipient's device.
display: Requests a display notification when the message is displayed to the recipient.

Processing on the recipient's side¶

Upon receiving a message with a disposition_notification node, the recipient's application should generate the appropriate notifications:

Delivery Notification: Sent when the message is delivered to the device.
Display Notification: Sent when the message is displayed to the user.

Notification format¶

{
    "message_id" : "xkXRBMCL.twvNcfC9",
    "delivery-notification" :
    {
        "datetime" : "2018-26-07T01:02:03Z",
        "status" : "delivered"
    },
    "display-notification" :
    {
        "datetime" : "2018-26-07T01:02:03Z",
        "status" : "displayed"
    }
}

Alternatively, multiple disposition notifications can be grouped in a JSON array:

[
    {
        "message_id" : "message.1",
        "..." : "..."
    },
    {
        "message_id" : "message.2",
        "..." : "..."
    }
]

message_id

Mandatory. It identifies the message being confirmed and comes from the disposition_notification node of the send message web service call of the original message.

delivery-notification

This node is present when the user agent is notifying the other party that the message was delivered to the device.

datetime: It is the date and time (RFC 3339) of the moment when the device got the message.
status: Only possible value is delivered

display-notification

This node is present when the user agent is notifying the other party that the message was displayed to the user.

datetime: It is the date and time (RFC 3339) of the moment when user displayed the message.
status: Only possible value is displayed

The content-type of the disposition notification is application/x-acro-disposition-notification.

Implementation¶

If the server sends the current time in the fetch response, the server/local clock difference should be computed and datetime fields in the disposition notifications should be adjusted by the computed clock difference.

Note

The display notification needs to be sent and the correct datetime needs to be set only after the user displays the message. The clock difference at that time may be completely different but we still use the clock difference detected during the fetch time - can't think of any other solution.

Important

If the delivery of the disposition notification fails because of the transmission problems or the server responds with 5xx HTTP code, the disposition notification delivery should be retried later.