Objective
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. Please send another test message to this user via a REST API request. 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:+13105551234Twilio 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
Todestination has not joined your Twilio Sandbox. Users can join your sandbox by sending the messagejoin <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
bodydoes 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. Troubleshooting |
| 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 |