Why a WhatsApp Message Was Not Delivered

When you send a message via the CRM's WhatsApp integration, you may notice it shows a status of "sent" but is never marked as "delivered." This article explains the most common reasons for this and provides steps to resolve the issue.

Common Reasons for Undelivered Messages

There are several factors that can prevent a message from being delivered to the recipient.

• Recipient Offline for an Extended Period: WhatsApp stores messages for offline users for up to 30 days. If the recipient does not reconnect to the internet within that time, the message will not be delivered.
• You Are Blocked: If the recipient has blocked your business phone number, your messages will not be delivered.
• Geographic Restrictions: The WhatsApp Business Platform is not available for users or businesses in certain countries, including Cuba, Iran, North Korea, Syria, and the regions of Crimea, Donetsk, and Luhansk in Ukraine.
• Outdated App or Unaccepted Terms: The message may fail if the recipient is using an outdated version of the WhatsApp application or has not accepted the latest Terms of Service.
• Marketing Message Limits: To maintain a high-quality experience, WhatsApp limits the number of marketing messages a user can receive in a day. If a user receives too many (typically 5-6), further marketing messages may be temporarily blocked.
• Invalid Phone Number: The message will not be delivered if the recipient's phone number is not registered with WhatsApp or was entered incorrectly.
• API Errors: If the API request sent from the CRM contains missing or incorrect information, it may be rejected.
• Conflicting Delivery Status: A message might show both "delivered" and "failed" statuses if the recipient is logged into WhatsApp on multiple devices. If the message was delivered to at least one device, it is considered successful.

What You Can Ask the Customer to Do

If the cause of the failure is not clear, you can guide your customer through these troubleshooting steps:

• Ask them to confirm they have not blocked your WhatsApp number.
• Request that they send a message to your business first. This action re-opens the 24-hour customer service window.
• Ensure they have accepted the latest WhatsApp Terms of Service.
• Suggest they update their WhatsApp application to the latest version.
• Verify they are not in a restricted region.

Technical Issues and How to Resolve Them

Authentication and Authorization Errors

These errors occur if the access token used by the CRM is invalid or lacks the necessary permissions.

Resolution: Use the token debugger tool to verify the token's permissions. Ensure it has the required scopes for WhatsApp business management and messaging. If not, you will need to regenerate the token with the correct permissions.

Platform API Downtime

Occasionally, the underlying platform that powers WhatsApp's API undergoes updates, which can cause brief outages.

Resolution: If you receive a specific error code indicating an API issue, wait approximately five minutes and then retry sending the message.

Frequently Asked Questions

Why was my message marked as sent but not delivered?

This can happen for many reasons, including the recipient being offline for over 30 days, having blocked your number, using an outdated app, or being located in a restricted country.

What does "Message Undeliverable" mean?

This status means the message left your system but could not reach the recipient's device due to a block, policy restriction, or technical issue.

How can I check if a recipient blocked my number?

You are not directly notified of a block. However, if messages consistently fail to deliver to one contact while others are successful, it is a strong indicator.

What is the 24-hour Customer Service Window?

After a user initiates a conversation with your business, you have a 24-hour window to send them free-form messages. Outside of this window, you can only use pre-approved message templates to re-engage them.

What is the "High-Quality User Experience" restriction?

This is a limit imposed by WhatsApp to prevent users from receiving excessive marketing messages. Utility templates are not subject to this limit.

How do I resolve a message blocked by the "High-Quality" restriction?

You can ask the customer to message you first, use a utility template instead of a marketing template, or wait and try again later.

Can users in all countries receive WhatsApp Business messages?

No. The service is restricted in several countries, including Cuba, Iran, North Korea, Syria, and the regions of Crimea, Donetsk, and Luhansk.

What should I do for authentication errors?

Use the token debugger to validate your access token and ensure it has the correct permissions for sending messages.