Message Not Delivered

The following scenarios can cause a message to appear as sent but not delivered. For many of these reasons, we will not disclose the underlying cause of the error, due to privacy and policy reasons.

• The customer did not come online during the 30 day window where we hold messages for offline customers.
• The customer has blocked the business phone number, or another business phone number owned by the business.
• The customer is in a restricted or sanctioned country.

In some scenarios, the API returns an error code with an error message describing the nature of the error. Example scenarios:

• Invalid request parameters
• Integrity errors
• The customer has not accepted our new Terms of Service and Privacy Policy. Please send your end user this link https://wa.me/tos/20210210 to accept the latest Terms of Service.
• The customer is using an old version of WhatsApp. Customers should use the following version or greater:
  • Android: 2.21.15.15
  • SMBA: 2.21.15.15
  • iOS: 2.21.170.4
  • SMBI: 2.21.170.4
  • KaiOS: 2.2130.10
  • Web: 2.2132.6
• The customer is part of an experiment group.
• The message was not delivered to create a high quality user experience. See Per-User Marketing Template Message Limits.

Possible Solutions

Using a non-WhatsApp communication method, ask the WhatsApp user to:

• confirm that they can actually send a message to your WhatsApp business phone number(s)
• confirm that none of your WhatsApp business phone numbers are in their list of blocked numbers (Settings > Privacy > Blocked or Blocked contacts)
• confirm that they have accepted our latest Terms of Service (Settings > Help, or Settings > Application information will prompt them to accept the latest terms/policies if they haven’t done so already)
• update to the latest version of the WhatsApp client

Country Restrictions

Businesses in Cuba, Iran, North Korea, Syria, and three sanctioned regions in Ukraine (Crimea, Donetsk, Luhansk) are not eligible to use the WhatsApp Business Platform.

WhatsApp Messenger (WhatsApp) and WhatsApp Business app users in Cuba, Iran, North Korea, Syria, and three sanctioned regions in Ukraine (Crimea, Donetsk, Luhansk) are not eligible to receive messages sent via the WhatsApp Business Platform.

As of May 15, 2024, Türkiye is no longer restricted for Cloud API business messaging. Cloud API businesses can now initiate conversations and receive messages from WhatsApp users with Turkish numbers.

Webhooks

Conflicting Message Delivery Status

In rare cases, the same message may trigger both success and failure message status update webhooks. For example, a message may trigger message webhooks with "status":"delivered" and another webhook with "status":"failed". This can happen when a customer is logged in to WhatsApp on multiple devices and the message is successfully delivered to one device but not the other. Any message that triggers a "delivered" message status webhook has been delivered to at least one of the user’s devices.

Error Code 2 – API Service

When we update the API, you may experience up to 5 minutes of downtime. During this period of time, the service is unavailable. We try to make these updates with minimal disruption to businesses, but you may end up being affected

How To Debug

We suggest that you wait 5 minutes and try to make the API call again.

Authentication and Authorization Errors

These errors are returned when there was a problem with the access token you are using for the API call.

How To Debug

You can directly paste the access token you are using into the Access Token Debugger. Then, check if you have selected the whatsapp_business_management and whatsapp_business_messaging permissions.

If your token doesn’t have access to the permissions, you need to generate a new one. While generating the token, make sure to select:

• The Meta app you are using for the API calls
• The following permissions: whatsapp_business_management and whatsapp_business_messaging

How We Notify via Error Code

Soon, we will also introduce a new error code to help businesses understand when a message has not been delivered in order to maintain ecosystem health.

If a marketing template message is not delivered to a given user due to the limit, Cloud API will return error code 131049 with the description “This message was not delivered to maintain a healthy ecosystem.”

If you do receive this error code and suspect it is due to the limit, avoid immediately resending the template message. Doing so will only result in another error response since the limit may be in effect for differing periods of time. Instead, retry sending the message in increasingly larger time increments until it is delivered.

We will continue to refine our approach, and we appreciate your partnership as we invest in making WhatsApp the best possible experience for your business and your customers.