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.