Skip to main content

Why a WhatsApp Message Was Not Delivered

When using Stack to send messages via the WhatsApp Business API, you might encounter situations where a message is marked as "sent" but not "delivered." Below are common reasons for this issue and guidance on how to troubleshoot and resolve it.

Common Reasons for Undelivered Messages​

  1. User Was Offline for More Than 30 Days
    WhatsApp stores messages for offline users for up to 30 days. If the recipient does not come online within that period, the message will not be delivered.

  2. User Has Blocked Your Number
    If the recipient has blocked your business number, messages will not be delivered.

  3. Geographic Restrictions
    The WhatsApp Business Platform is unavailable in the following regions:

    • Cuba
    • Iran
    • North Korea
    • Syria
    • Crimea, Donetsk, and Luhansk (Ukraine)

    Note: Türkiye is supported for Cloud API messaging as of May 15, 2024.

  4. Outdated App Version or Terms Not Accepted
    Messages may fail if the customer:

    • Is using an outdated version of WhatsApp.
    • Has not accepted the latest Terms of Service.

    To resolve this, ask the user to update their app and accept the latest Terms via this link.

  5. High-Quality Messaging Restrictions
    WhatsApp limits the number of marketing messages a user can receive to maintain quality. If a user receives too many marketing messages (typically 5–6 in a day), further messages may be temporarily blocked.

  6. Invalid or Unregistered Phone Number
    If the phone number is not registered with WhatsApp or is entered incorrectly, the message will not be delivered.

  7. API Errors or Invalid Parameters
    If your API request has missing or incorrect fields, such as improperly formatted variables, it may be rejected.

  8. Conflicting Delivery Status
    A message might show both "delivered" and "failed" statuses if the user is logged into WhatsApp on multiple devices. If a message is delivered to at least one device, it is considered successfully delivered.

What You Can Ask the Customer to Do​

If the reason for the failed delivery is unclear, consider these steps to help identify or resolve the issue:

  • Confirm that the customer has not blocked your WhatsApp number.
  • Ask them to send a message to your business first (this reopens the 24-hour customer service window).
  • Ensure they have accepted WhatsApp’s latest Terms of Service.
  • Have them update to the latest version of WhatsApp based on their device.
  • Verify that they are not using a restricted version or are in an unsupported region.

Technical Issues and How to Resolve Them​

Authentication and Authorization Errors​

These errors occur when your access token is invalid or missing required permissions.

Resolution:

  • Use the Meta Access Token Debugger to verify token permissions.
  • Ensure the token has the necessary scopes:
    • whatsapp_business_management
    • whatsapp_business_messaging

Meta API Downtime (Error Code 2)​

Brief outages (up to 5 minutes) may occur when Meta updates its API.

Resolution:

  • Wait five minutes and retry the API call.

FAQ​

  1. Why was my WhatsApp message marked as sent but not delivered?
    Possible reasons include:

    • The recipient has been offline for over 30 days.
    • The recipient has blocked your number.
    • The recipient hasn’t accepted the latest WhatsApp Terms of Service.
    • The recipient is using an outdated version of WhatsApp.
    • The recipient’s number is invalid or not connected to WhatsApp.
    • Your message was flagged due to quality limits on marketing messages.
    • The recipient is located in a region where the WhatsApp Business Platform is restricted.

  2. What does “Message Undeliverable” mean?
    This usually means the message was sent from your system but could not be delivered to the recipient’s device due to blocking, being offline too long, or technical/policy restrictions on Meta’s end.

  3. How can I check if the recipient blocked my number?
    You won’t be notified directly due to privacy policies. However, if other messages are delivered to the same recipient or they are unresponsive over a long period, they may have blocked you.

  4. What is the 24-hour Customer Service Window?
    Once a user sends a message to your business, you have 24 hours to respond using free-form messages. After that, only pre-approved templates can be used to re-initiate the conversation.

  5. What is the “High-Quality User Experience” error?
    If a user receives too many marketing messages (e.g., 5–6 per day), WhatsApp may restrict further marketing messages to maintain quality. Utility templates are not affected by this restriction.

  6. How can I resolve the “High-Quality User Experience” delivery issue?
    Try these steps:

    • Ask the customer to send you a message first (this opens the 24-hour window again).
    • Use a Utility Template instead of a Marketing Template.
    • Wait and retry the message after some time.

  7. How do I know if a user’s WhatsApp version is outdated?
    Ask the user to update WhatsApp to the following or newer versions:

    • Android: 2.21.15.15+
    • iOS: 2.21.170.4+
    • Web: 2.2132.6+

    Older versions may not support newer API features and may block message delivery.

  8. Can users in all countries receive WhatsApp Business messages?
    No. The WhatsApp Business Platform is restricted in certain countries, including:

    • Cuba
    • Iran
    • North Korea
    • Syria
    • Crimea, Donetsk, and Luhansk (Ukraine)

  9. What does it mean if I see both “delivered” and “failed” statuses for the same message?
    This can happen if the user is logged in on multiple devices. The message was delivered to at least one device but may have failed on another.

  10. What should I do if I get authentication or permission errors when sending messages?

    • Use the Meta Access Token Debugger to validate your token.
    • Ensure the token includes these permissions:
      • whatsapp_business_management
      • whatsapp_business_messaging