What are the reasons my templated messages fail and how to solve this?
When attempting to send templated messages to users, companies sometimes face message failure – even when the message templates have been approved by WhatsApp.
Here are a few reasons why they fail – and how you can solve this issue.
Wrong language and locale combination
Commonly seen is the usage of the wrong language and locale combination. This mistake happens mostly on languages that provide a locale.
For example: english (en) with the subcodes en_UK, en_US for british and english locale.
Error code via MessageStatus::channelFailed
whatsapp::external::2003
ℹ️ How to solve:
Check the localizations available for your template. You can either use the correct language and local combination or submit a new localization with the expected language code.
Template does not exist in the requested language code
This error has a subtle difference to the language and locale one. Whereas on the first case the local was wrong / not requested, in this case no localization at all for the language exists.
Error code via MessageStatus::channelFailed
whatsapp::external::2001
ℹ️ How to solve:
Check the localizations available for your template and submit the missing localization.
Wrong number of parameters on body
Another common error case is that on a component of the template the wrong number of parameters was used.
WhatsApp requires having the exact number of parameters set as specified in the template body.
Error code via MessageStatus::channelFailed
whatsapp::external::2000
ℹ️ How to solve:
Check for the template how many parameters, {{N}}: N natural number, are defined for the language code you want to use and use the required number of parameters, on messaging request.
Rich Media Template: No document / image provided
When you use a rich media template, WhatsApp requires having the matching media send with it.
Error code via MessageStatus::channelFailed
whatsapp::external::2012
ℹ️ How to solve:
Send the matching media with the messaging request.
Rich Media Template: Wrong size on media
In this error case, the provided media file does not match size for the media type.
Error code via MessageStatus::channelFailed
whatsapp::error::invalidFileSize
ℹ️ How to solve:
Make sure the media respects the limit as returned by the details. You can find them as well here https://developers.facebook.com/docs/whatsapp/api/media#post-processing
No valid contact
This is a general error for both templated messages and customer care messages. It indicates that the number that you want to send the message to is not a valid WhatsApp contact. Most likely the number is not registered with WhatsApp.
Error code via MessageStatus::channelFailed
whatsapp::error::noValidContact
ℹ️ How to solve:
Make sure the phone number you want the message send to does exist.