Tropo is part of CiscoLearn More

SMS Delivery Report

Text messaging is an asynchronous mechanism, so unlike phone calls, your app can't always know in real time if a message was successful or not. To provide you with information about message delivery, Tropo offers Delivery Reporting Webhooks. When the carrier delivers the message to the user's handset, or determines that a message cannot be delivered for some reason, Tropo will send the results as a JSON document to a URL on your server.

Not all carriers will return delivery receipts. For those carriers, Tropo's delivery report status will be sent. Tropo's provider for US SMS-enabled local and toll-free numbers doesn't currently support delivery receipts, so the status from these will be accepted. US short codes will report status accurately.

To set the URL, Tropo is not providing a self-service mechanism in this beta. When you are approved for the beta, Tropo support will ask for your webhook destination URL. After the beta, there will be APIs and web interfaces for managing your webhook URLs.

In addition to the delivery status, the The JSON will include the session and call ID so you can correlate this to the actual message.

Note
The mechanisms for configuring a webhook and the payload of the webhook are subject to change while this feature is in beta. Developers who use this beta feature should be prepared to change their handlers in subsequent releases.

Tropo will only send a delivery receipt with the final status; there is no intermediate status or webhooks. The delivery report webhook can take up to 24 hours to be sent, since it can take up to that time before the final status is known.

If Tropo is unable to reach your web server when delivering the webhook, it will try again few seconds later, and then a few seconds after that, if needed. After three attempts (about 6 seconds), Tropo will not retry again.

Fields

id

String

A unique ID for this webhook payload.

name

String

The name given to this webook. During the beta, Tropo support sets the name. Once we allow self-provisioning, you will be able to set the name.

resource

String

What resource the webhook is for. For Delivery Receipts this will read sms

event

String

The type of webhook this is. For Delivery Receipts this will read smsdlr

Delivery Report Data

The data element contains all the information specific to the Delivery Report.

accountid

Integer

The Tropo account ID the SMS delivery report is for. This can prove useful for systems that use the same endpoint to process webhooks for multiple parties or applications.

applicationid

Integer

The Tropo application that sent the message for this delivery report. Like accountId, this can help with endpoints processing multiple applications.

sessionid

String

The Tropo session ID that sent the SMS message. A single session might have multiple SMS messages, each with their own delivery report, so this is not a unique field

callid

String

The Tropo call ID that sent the SMS message. Every SMS sent will have a different call ID, but if your message is split into multiple messages due to message length, you will receive a delivery report for each message part, and these may all have the same call ID. The id field will be different, however.

eventTimeStamp

String

Unix Epoch (number of seconds since January 1, 1970) timestamp indicating when this webhook was sent. This is not the time the SMS was sent, but rather the time that Tropo triggered the webhook to you.

stat

String

The delivery state of the message. The status field (and the corresponding dlvrd field) will be one of the following values::

  • Delivered (dlvrd 2): The message has been delivered to the user's handset by their carrier.
  • Accepted (dlvrd 6): The message has been successfully delivered to the SMS network, but the carrier does not support delivery receipts, and we are unable to tell you if it reached the handset.
  • Sent (dlvrd 0): The message was sent successfully by Tropo to our upstream carriers, but we never received confirmation that was delivered or failed. We will be unable to tell you if the message was delivered. This can be because the delivery receipt we received from the SMS network did not contain a status, or because 24 hours elapsed without us receiving a delivery receipt and we have given up waiting.
  • Undelivered (dlvrd 5): The carrier attempted to deliver, but has failed to deliver the message. This may mean you sent a text message to a number that is not in service or cannot receive text messages (like a landline).
  • Rejected (dlvrd 8): The message was rejected by the carrier network. The most likely reason for this was that your application set a Caller ID that is not one of the SMS-enabled numbers attached to your application.
  • Expired (dlvrd 3): The message has timed out. The carrier thought the message was deliverable, but was unable to reach the user's handset. This is often because the phone is turned off, or out of range. Sometimes, a user roaming outside their home country can end up with no textable route to their phone and cause this result.

dlvrd

Integer

A numeric representation of the message status. See the stat field for a description of each status.

err

String

Any error code returned by the SMS operator

submitDate

String

The time the message was delivered to the SMS operator. In YYMMDDHHDD format.

doneDate

String

The time the message was delivered to the handset. In YYMMDDHHDD format.

id

String

The carrier's SMS ID transmitted back to us in the delivery report. This can be useful in the carrier troubleshooting delivery issues.

sub

Integer

The carrier's system's sub-id. This is not used in Tropo, and will be set to an arbitrary integer, usually "001"

to

String

The phone number the SMS was sent to.

from

String

The Tropo phone number the SMS was sent from.

Examples

{
  "id": "a74cf2f9-80fe-4c96-96eb-8d024dad923b",
  "name": "SMS Delivery Receipt webhook",
  "resource": "sms",
  "event": "smsdlr",
  "data": {
    "accountId": 12345,
    "applicationId": 5011111,
    "sessionId": "959f7b95fcede19963729803c1c926b9",
    "callId": "c0da8a8656d9e63f9ca352f071d1bfb0-1",
    "eventTimeStamp": 1477434664535,
    "sub": "001",
    "stat": "ACCEPTD",
    "dlvrd": "000",
    "err": "000",
    "submitDate": "1610252231",
    "from": "+16282390011",
    "id": "3266893717",
    "to": "14087995758",
    "doneDate": "1610252231"
  }
}