SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Tracking Message Delivery Failures and Retry Behavior

Overview

When using the Twilio Conversations API to send messages to participants on non-Chat channels (such as SMS and WhatsApp), it’s important to understand how to track delivery failures and what retry options are available. This article explains the recommended webhook configuration, terminal message states, and retry mechanisms for message delivery in Conversations.

 

What You Need To Know

How to Track Delivery Failures

Twilio Conversations provides Delivery Receipts for messages sent to non-Chat participants. These receipts allow you to monitor whether a message has been delivered, failed, or remains undelivered.

Recommended Approach:

  • Configure and listen for the onDeliveryUpdated webhook event at the Conversation Service level.
  • The onDeliveryUpdated event notifies your application whenever the delivery status of a message changes (e.g., delivered, undelivered, failed).

Example Use Case:

  • If you want to track when a message fails to deliver to an SMS or WhatsApp participant, set up the onDeliveryUpdated webhook and process the event payloads for statuses such as undelivered or failed.

For more details, see the Twilio Conversations Delivery Receipts documentation.

 

Automatic Retry Behavior

  • Once a message sent via the Conversations API reaches an undelivered or failed state, this is considered a terminal state for that specific MessageSid.
  • Twilio does not perform any further automatic retries for messages in these terminal states.

 

Manual Retry Options

  • There is no mechanism to re-trigger or resume delivery for an existing MessageSid that has failed or is undelivered.
  • If you wish to attempt delivery again, you must send a new message (which will generate a new MessageSid).

 

Frequently Asked Questions

Can I track delivery status for all channels?

Delivery Receipts are available for non-Chat channels (SMS, WhatsApp). For Chat participants, delivery is assumed once the message is accepted by Twilio.

What should I do if a message fails?

Listen for the onDeliveryUpdated webhook, log the failure, and if needed, send a new message to retry delivery.

 

Conclusion

Summary Table

Scenario Supported? How to Implement
Track delivery failures Yes Use onDeliveryUpdated webhook
Automatic retry after failure/undelivered No Not supported
Manual retry for same MessageSid No Not supported
Manual retry by sending new message Yes Send a new message

Below you will find references to useful documents: 

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk