Troubleshooting Undelivered Twilio for WhatsApp Messages

For issues sending messages to WhatsApp users, please use the following troubleshooting checklist:

Prerequisite: Twilio Sandbox Activation

Prior to sending WhatsApp messages, users must activate and configure the Twilio Sandbox for WhatsApp on their project. This process includes selecting a shared Twilio sandbox number to be used for testing (until your Twilio project is enabled by WhatsApp). For more details, please see our article Getting Started with Twilio for WhatsApp (Beta).

Is This Repeatable?

The first step to troubleshooting this issue is to attempt to replicate the problems. Attempt to send another test message to this user via a REST API request, or through the API Explorer in Console. Pay close attention to your request, and double check to verify you are attempting to send messages from the shared Twilio sandbox test number selected when activating, and that your To and From numbers are in the correct format of 'whatsapp:' followed by the number in E.164 formatting:

whatsapp:+13105551234

Twilio Sandbox Errors

Twilio Sandbox error messages are usually caused by the Sandbox not being configured on your project, or an issue with the API request. For a list of errors and how to resolve them, please see our article Troubleshooting the Twilio Sandbox for WhatsApp (Beta).

Undelivered WhatsApp Messages

WhatsApp messages may fail to be delivered for any of the following reasons:

  • The To destination has not joined your Twilio Sandbox. Users can join your sandbox by sending the message join <your sandbox keyword> to your shared Twilio sandbox number in WhatsApp. More details can be found in WhatsApp - Joining a Sandbox (Twilio Docs).
  • The message body does not match a valid pre-registered template. If more than 24hours have elapsed since your last inbound message from this user, you will only be able to reach out to them using a pre-registered template. Messages sent to the user within the 24hour session window do not have these template requirements. The default templates can be found in WhatsApp - Templates pre-registered for the Sandbox (Twilio Docs).

Additional Resources

Have more questions? Submit a request
Powered by Zendesk