Potential Support Response Time Delays Due to Surge in Toll-Free Queries: We’re experiencing a surge in inquiries due to the November 8, 2023 Toll-Free Restricted Traffic Shutdown Deadline. We’re committed to helping you; please bear with us as there might be some delays. For more details, see Toll-Free Message Verification for US/Canada.

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.

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

Notice: The API Explorer will reach its End of Life on December 15th, 2023, and will no longer be accessible after this date. For alternatives, please visit our API Reference docs.

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.

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 24-hour session window do not have these template requirements. The default templates can be found in WhatsApp - Templates pre-registered for the Sandbox (Twilio Docs).

Common WhatsApp message errors

Users may see the following errors when attempting to send messages to WhatsApp users via Twilio:

Error Message Information
63003 Channel could not find To address Messages may return this error if the To value is not recognized. Troubleshooting
63016 Failed to send freeform message because you are outside the allowed window. Please use a Template. Messages may return this error if a template issue was found. Troublshooting
63018 Rate limit exceeded for Channel Messages may return this error if your volume exceeds the limits for the channel. Details
63020 Twilio encountered a Business Manager account error Messages may return this error if the Facebook Business Manager has not been fully configured. Troubleshooting

Additional Resources

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