Delivery Receipts in Conversations

You can use Delivery Receipts to check the Message Status of the Conversations Messages. This information is a quick way to gauge if your messages reach your end users. If the delivery receipt indicates that the message wasn't delivered, you'll know to look into carrier disruptions or issues with mobile connectivity or availability.

Unlike the Message Status of individual SMS and WhatsApp messages, Delivery Receipts in Conversations correlate the Message Status information with your Conversation SID as well as relevant error code information. Rather than tracking individual messages, you can see both aggregated delivery information as well as the most recent status for messages in a particular Conversation.

Delivery Receipts in Conversations support the following message statuses:

• sent: Twilio has sent the message
• delivered: Twilio has received confirmation of message delivery from the carrier (and, where available, the destination handset). See below for more information.
• read: The user has opened the message on their device, and the read status has been reported back to Twilio. This applies only to over-the-top, or OTT, channels, such as WhatsApp.
• failed: The message could not be sent.
• undelivered: Twilio has received a delivery receipt indicating that the message was not delivered.
• null: The message has been created, but it's still within Twilio.

For failed and undelivered statuses, Twilio provides an error code with the reason that the Message was not delivered.

Please note that SMS statuses received via Delivery Receipts are tentative. (Read more on SMS-specific message statuses.) For SMS, the last possible status is "delivered," which indicates that the carrier has accepted the SMS message as sent from Twilio. If the carrier has not yet accepted the Message, its status remains "sent."

Delivery Receipts for WhatsApp messages are more granular. A "delivered" status indicates that the WhatsApp application has accepted the message. Otherwise, the status remains as "sent," for example if the mobile device is off. WhatsApp messages can also have the "read" status, indicating that the recipient has consumed the message on their device.

There are two ways that you can consume Delivery Receipts information:

Delivery Receipts information is available at two levels: a summary with aggregated totals for a given Message and a detailed view, broken down by recipient for a given Message.

The Delivery property of the Conversations Message resource contains an aggregated summary delivery information. This provides a high-level overview of the Message Status information for the Conversation, including count breakdowns by status of the Conversational messages.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchConversationMessage() {
11
  const message = await client.conversations.v1
12
    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .messages("IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
    .fetch();
15

16
  console.log(message.delivery);
17
}
18

19
fetchConversationMessage();

1
{
2
  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
  "body": "Welcome!",
6
  "media": null,
7
  "author": "system",
8
  "participant_sid": null,
9
  "attributes": "{ \"importance\": \"high\" }",
10
  "date_created": "2016-03-24T20:37:57Z",
11
  "date_updated": "2016-03-24T20:37:57Z",
12
  "index": 0,
13
  "delivery": {
14
    "total": 2,
15
    "sent": "all",
16
    "delivered": "some",
17
    "read": "some",
18
    "failed": "none",
19
    "undelivered": "none"
20
  },
21
  "content_sid": null,
22
  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
23
  "links": {
24
    "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts",
25
    "channel_metadata": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelMetadata"
26
  }
27
}

For example, imagine the following sample delivery object returned as part of a fetched Message:

1
"delivery": {
2
    "total": 5,
3
    "sent": "all",
4
    "delivered": "some",
5
    "read": "some",
6
    "failed": "none",
7
    "undelivered": "none"
8
}

This information indicates that of the five delivery receipts for a given message, the message was sent to all of the Participants. Some messages are delivered, indicating that Twilio has received delivery confirmation from a carrier. The some next to read indicates that some of the messages--those sent over an OTT channel--have been opened or read by the Participants. No messages have the failed or undelivered status.

For a more granular view of message delivery status, you can make a request to the Receipts resource, described below.

A request to the Delivery Receipt resource returns individual statuses for each Message, by each recipient. This is a more detailed view of Message Status information; it includes Channel SIDs for the Conversation Participants.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function listConversationMessageReceipt() {
11
  const deliveryReceipts = await client.conversations.v1
12
    .conversations("ConversationSid")
13
    .messages("IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14
    .deliveryReceipts.list({ limit: 20 });
15

16
  deliveryReceipts.forEach((d) => console.log(d.accountSid));
17
}
18

19
listConversationMessageReceipt();

1
{
2
  "meta": {
3
    "page": 0,
4
    "page_size": 50,
5
    "first_page_url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts?PageSize=50&Page=0",
6
    "previous_page_url": null,
7
    "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts?PageSize=50&Page=0",
8
    "next_page_url": null,
9
    "key": "delivery_receipts"
10
  },
11
  "delivery_receipts": [
12
    {
13
      "sid": "DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15
      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16
      "message_sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
      "channel_message_sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
      "status": "failed",
19
      "error_code": 3000,
20
      "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21
      "date_created": "2016-03-24T20:37:57Z",
22
      "date_updated": "2016-03-24T20:37:57Z",
23
      "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts/DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
24
    },
25
    {
26
      "sid": "DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28
      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29
      "message_sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30
      "channel_message_sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
31
      "status": "failed",
32
      "error_code": 3000,
33
      "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34
      "date_created": "2016-03-24T20:37:57Z",
35
      "date_updated": "2016-03-24T20:37:57Z",
36
      "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts/DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
37
    },
38
    {
39
      "sid": "DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
40
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
41
      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
42
      "message_sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
43
      "channel_message_sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
44
      "status": "failed",
45
      "error_code": 3000,
46
      "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
47
      "date_created": "2016-03-24T20:37:57Z",
48
      "date_updated": "2016-03-24T20:37:57Z",
49
      "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Receipts/DYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
50
    }
51
  ]
52
}

In the response, delivery_receipts is a list of individual statuses for each Message that was sent to an individual recipient or Participant in the Conversation.

For example, if a Chat user is corresponding with one SMS Participant and one WhatsApp Participant, delivery_receipts will contain two different objects, one for each Message sent to a specific Participant:

1
{
2
   “delivery_receipts” : [
3
         {
4
            "sid": "DYXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
            "message_sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6
            "channel_message_sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7
            "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8
            "status": "sent",
9
            "error_code": null,
10
            "date_created": "2020-03-23T18:45:17Z",
11
            "date_updated": "2020-03-23T18:45:17Z"
12
         },
13
         {
14
            "sid": "DYXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15
            "message_sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
16
            "channel_message_sid": "WAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
17
            "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
18
            "status": "read",
19
            "error_code": null,
20
            "date_created": "2020-03-23T19:45:17Z",
21
            "date_updated": "2020-03-23T18:45:17Z"
22
         }
23
     ]
24
}
25

In the sample output, we see that for the Message for the SMS Participant (the SMXXX Channel SID), the most recent status is sent, meaning that Twilio has passed the message on to the appropriate carrier. However, for the WhatsApp Participant, the most recent status is read, indicating that the Participant has consumed the message in their WhatsApp application.

Webhooks are user-defined HTTP callbacks. They are usually triggered by some event, such as receiving an SMS message or an incoming phone call. When that event occurs, Twilio makes an HTTP request (usually a POST or a GET) to the URL configured for the webhook.

To handle a webhook, you only need to build a small web application that can accept the HTTP requests. Almost all server-side programming languages offer some framework for you to do this. Examples across languages include ASP.NET MVC for C#, Servlets and Spark for Java, Express for Node.js, Django and Flask for Python, and Rails and Sinatra for Ruby. PHP has its own web app framework built in, although frameworks like Laravel, Symfony and Yii are also popular.

Whichever framework and language you choose, webhooks function the same for every Twilio application. They will make an HTTP request to a URI that you provide to Twilio. Your application performs whatever logic you feel necessary - read/write from a database, integrate with another API or perform some computation - then replies to Twilio with a TwiML response with the instructions you want Twilio to perform.

As mentioned above, the information retrieved via the REST API and the Delivery Receipt Resource displays the last or most recent update for a given Message. However, what if you want automatic updates on a message's status, as it passes through Twilio's systems and onto the carrier or OTT application? For this, you'll set up your webhook URL.

Each Delivery Receipt event that you receive on your webhook URL represents a status change for a given message.

A new post-webhook event called onDeliveryUpdated is executed for every delivery receipt notification received by Twilio. For every delivery receipt event, Twilio will send a request to your post-event URL that you have configured for Conversations. (Read more about using Webhooks in Conversations.)

Twilio sends the same information found in the Receipt resource to your post-event URL for every onDeliveryUpdated event.

You can turn on webhooks and configure the post-event URL for Delivery Receipts using the Conversations REST API:

1
curl -X POST "https://conversations.twilio.com/v1/Conversations/Webhooks" \
2
--data-urlencode "PostWebhookUrl=https://www.example.com/postWebhook" \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "pre_webhook_url": "https://example.com/pre",
4
  "post_webhook_url": "https://www.example.com/postWebhook",
5
  "method": "GET",
6
  "filters": [
7
    "onConversationUpdated"
8
  ],
9
  "target": "webhook",
10
  "url": "https://conversations.twilio.com/v1/Conversations/Webhooks"
11
}

You can also configure the onDeliveryUpdated webhook through the Twilio Console in the Conversations section. (Read more about Conversations Webhooks and how to configure them.)

Delivery Receipts in Conversations provide visibility into the statuses of messages sent across different channels. Let's look at two common use cases for Delivery Receipts.

The primary use case for Delivery Receipts involves an agent on a Chat interface sending messages to an SMS or WhatsApp end user. In this case, the agent on Chat wants to know if their message has been received by the SMS user or read by the WhatsApp (OTT) user.

First, use the aggregated status on the Message resource to get a quick overview of the situation. This aggregated view is often sufficient to see that all of the messages have the delivered status. Twilio works with carriers to ensure a high rate of message deliverability, so you can use delivered: "all" as a quick indicator that the messages are reaching your end users successfully.

If necessary, you can take a deeper dive into the Message status for a specific Participant in the Conversation. An example of this would be the aggregated delivery object indicating that only some or none of the messages were delivered.

In this case, you can utilize Webhooks or the Receipts resource to examine individual message statuses. Make a request to the Receipts resource to find the SIDs and error codes for specific Messages that have undelivered or failed statuses.

It is also possible to track the status of any message sent between non-Chat Participants in a Conversation. In other words, you can use Delivery Receipts to answer the question "Where is the message between two SMS Participants in my Conversation?"

For example, imagine a Conversation between an Agent on Chat and two SMS Participants (end users). You can verify that a message sent from one SMS end user reached the other. These details are available through Webhooks (as a onDeliveryUpdated event) or via the Conversations REST API.

When a Message is delivered to another Chat Participant, it does not emit any Delivery Receipt information. Therefore, Delivery Receipts information is only available for messages sent to non-Chat (SMS or WhatsApp) Participants.

SMS delivery statuses have limited reliability, and Twilio cannot guarantee against last-leg disruptions from the carrier. This is the same reliability as seen in SMS status callbacks. In most cases, these statuses are accurate.

In addition, SMS statuses in Delivery Receipts do not reveal whether the end user's mobile handset is turned on or off. If the end user's mobile device is switched off, the status of this SMS message is delivered.

Barring any carrier disruptions, the message will 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.

In this guide, we covered using Delivery Receipts to check the status of messages in Conversations.

Check out the following resources to continue building rich conversational experiences for your customers:

• The Conversations Quickstart
• Setting up Webhooks in Conversations
• Configuring WhatsApp and Conversations
• Message Statuses for SMS Messages