Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Delivery Receipts Overview


With the Delivery Receipts feature, you can obtain information about the status of Conversations Messages sent to non-Chat Participants (i.e. SMS and WhatsApp channels).

You can verify if the Messages were sent, delivered or even read (for OTT(link takes you to an external page)) by other Conversations Participants.

Let's get started!


What are Delivery Receipts?

what-are-delivery-receipts page anchor

Delivery Receipts are summaries that contain detailed information about the messages sent to Participants in non-Chat channels.

This feature includes information about:

  • A summary of the Message's delivery statuses
  • The number of Messages sent
  • The number of Conversation Participants the message(s) was sent to

Types of Delivery Receipt Message Statuses

types-of-delivery-receipt-message-statuses page anchor

Delivery Receipts can contain the following message statuses:

  • sent
  • delivered
  • read
  • failed
  • undelivered

Aggregated Delivery Receipts

aggregated-delivery-receipts page anchor

An Aggregated Delivery Receipt contains a general summary of the delivery statuses of a Message to all non-Chat Participants in the Conversation.

Use aggregated receipts to represent the overall delivery status of a Message.

You can retrieve the Aggregated Delivery Receipts summaries from any Message object in a Conversation that contains non-Chat recipients. This is often enough to confirm successful delivery of the message.

Aggregated Delivery Receipts

aggregated-delivery-receipts-1 page anchor
Node.js
Typescript

_17
/* Retrieving Delivery Receipts (aggregated and detailed) for rendering */
_17
_17
const aggregatedDeliveryReceipt = message.aggregatedDeliveryReceipt;
_17
_17
// get amount (DeliveryAmount) of participants with particular delivery status
_17
const deliveredReceipts = aggregatedDeliveryReceipt?.delivered;
_17
const failedReceipts = aggregatedDeliveryReceipt?.failed;
_17
const readReceipts = aggregatedDeliveryReceipt?.read;
_17
const sentReceipts = aggregatedDeliveryReceipt?.sent;
_17
const undeliveredReceipts = aggregatedDeliveryReceipt?.undelivered;
_17
// get the amount of participants which have the status for the message
_17
const totalReceipts = aggregatedDeliveryReceipt?.total;
_17
_17
if (undeliveredReceipts !== "none") {
_17
// some delivery problems
_17
alert(`Out of ${totalReceipts} sent messages, ${deliveredReceipts} were delivered, ${failedReceipts} have failed.`);
_17
}


Detailed Delivery Receipts

detailed-delivery-receipts page anchor

A Detailed Delivery Receipt represents the Message delivery status to a specific non-Chat Participant in the Conversation.

Use detailed receipts when you want to show the specific recipient who didn't receive the message.

You can also get a list of the Detailed Delivery Receipts by calling the correct method on the same object. This is useful if you want to render separate sent/delivered/read statuses for specific Participants.

Node.js
Typescript

_12
// get the list of of delivery receipts
_12
const detailedDeliveryReceipts = await message.getDetailedDeliveryReceipts();
_12
_12
const statusMap = {};
_12
_12
detailedDeliveryReceipts.map((detailedDeliveryReceipt) => {
_12
// get status of the delivery receipts
_12
const receiptStatus = detailedDeliveryReceipt.status;
_12
const participantSid = detailedDeliveryReceipt.participantSid;
_12
statusMap[participantSid] = receiptStatus;
_12
_12
});


Delivery Receipts Error Handling

delivery-receipts-error-handling page anchor

Retrieving detailed receipts is necessary for error retrieval and handling. Each detailed receipt for a message that failed will contain a Twilio error code indicating the failure reason.

If the message status is failed or undelivered, you can handle the error code accordingly.

Read more in the Troubleshooting Undelivered Twilio SMS Messages support article.(link takes you to an external page)

Delivery Receipt Error Handling

delivery-receipt-error-handling page anchor
Node.js
Typescript

_29
/* Checking delivery receipts for errors */
_29
_29
// get the list of aggregated delivery receipts
_29
const aggregatedDeliveryReceipt = message.aggregatedDeliveryReceipt;
_29
_29
// retrieve delivery receipt status
_29
if (aggregatedDeliveryReceipt.failed !== "none" || aggregatedDeliveryReceipt.undelivered !== "none") {
_29
// handle error
_29
}
_29
_29
// get the list of delivery receipts
_29
const detailedDeliveryReceipts = await message.getDetailedDeliveryReceipts();
_29
_29
detailedDeliveryReceipts.map((detailedDeliveryReceipt) => {
_29
// check delivery receipt status
_29
if (!detailedDeliveryReceipt.status === "undelivered" && !detailedDeliveryReceipt.status === "failed") {
_29
return;
_29
}
_29
_29
// handle error. the error codes page: https://www.twilio.com/docs/sms/api/message-resource#delivery-related-errors
_29
if (detailedDeliveryReceipt.errorCode === 30006) {
_29
alert("The destination number is unable to receive this message.");
_29
return;
_29
}
_29
_29
if (detailedDeliveryReceipt.errorCode === 30007) {
_29
alert("Your message was flagged as objectionable by the carrier.");
_29
}
_29
});


Great work! You've learned the foundations of Delivery Receipts, you can continue with any of the following guides:


Rate this page: