Support

Terms and policies

• Meta Hosting Terms for Cloud API
• WhatsApp Business Messaging Policy
• WhatsApp Business Terms of Service
• Meta Commerce Policy
• Meta Terms for WhatsApp Business

API status

See WhatsApp Business API Status to learn about our WhatsApp Business API Status page and what information it reports.

Developer support

All WhatsApp Business Platform developers can contact Meta developer support at:

https://developers.facebook.com/support/

Developer community forum

All WhatsApp Business Platform developers can ask a question on the Meta Developer Community Forum.

Reporting bugs

All WhatsApp Business Platform developers can report a bug, file a bug report at:

https://developers.facebook.com/support/bugs/

Enterprise developer support

If you are an enterprise developer, such as a solution provider or managed partner, you can open a Direct Support ticket using the link below. If you have multiple Meta business accounts, be sure to select the appropriate account.

https://business.facebook.com/direct-support/

Note that if you are an end-client of a Solution Partner or managed partner, contact your Solution Partner or managed partner for support directly.

We do our best to provide an initial response to your ticket within 24 hours on business days. Business days are Monday through Friday, in the customer's country set in the Business Account, excluding holidays.

Ticket severity

Ticket severity is generated based on the type of issue selected and information provided in your submission. We will review your ticket and investigate the issue according to the severity level and time of submission.

The criteria used to evaluate the severity of your ticket is outlined in the table below.

When a Critical or Urgent ticket is resolved but with outstanding request(s), we update the severity to Mitigated.

Troubleshooting

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, because of privacy and policy reasons. The reasons messages appear as 'sent' but are not delivered include, but are not limited to, the following:

• 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.

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 send and receive messages to and from WhatsApp users who have Turkish numbers.

Webhooks

Conflicting message delivery status

In rare cases, the same message might trigger both success and failure status messages webhooks. For example, a message might trigger status message webhooks with status set to delivered, and another webhook with status set to 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 status messages webhook has been delivered to at least one of the user's devices.

Error Code 2 - API Service

When we update the API, you might 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 might 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

MM Lite API

I can't find an admin user at my company to onboard to MM Lite

To use MM Lite API, onboarding must be completed by a user of your business portfolio with "Full control" permissions (formerly the admin role). Read more on the various access permissions available in a business portfolio.

If a business, or a partner working with a business, is unable to locate a user with "Full control", follow the steps below to find users with sufficient permission, or claim access to a business portfolio.

Find or add a user with "Full control" permissions

The simplest path to accepting the MM Lite API terms of service is if a business already knows a user with "Full control" permission. If so, that user can go through the MM Lite API Onboarding flow.

Find admins via Business Manager.

If the business (or their partner) cannot find a user with "Full control", they can log into Business Manager using another user with “basic access” to find the list of admins with "Full control".

• Log into Meta Business Suite, go to “Business Settings” and the "People" tab
• Any user of the Business Portfolio with “basic access” or more can view the full list of users, and find one with "Full control".

Find admins via an API call.

If the business is unable to find the admin of the business portfolio, however if their partner has a business token with business_management permission, they can fetch a list of users with "Full control" permissions with the following API endpoints:

• WhatsApp Business Account endpoint docs
• Business Users endpoint docs

Submit a request for a new user to be added to the business portfolio.

A business can submit a request to have a user added with "Full control" access to a business portfolio. This process takes 24 hrs on average to ensure a thorough security review if all documents are provided and in order, and should be a last resort after all other options have been exhausted.

• A user from the business might request to be added to the business portfolio with “full access”, provided they meet the documentation requirements outlined below.
• Follow instructions to Submit a request to get full control of a business portfolio
• Collect the required documents mentioned in the above link. With the collected assets, fill out the contact support form.

Note: If the desired admin is unable to select a Business from the dropdown list, they can select any random asset from the list and mention the desired BM ID as part of the “description text” in the request. If you are unable to select any asset / do not have any assets to select, reach out to your Partner manager.

I think my delivery rates are lower on MM Lite API than they were on Cloud API

Meta recommends all marketing messages are sent via the next-generation MM Lite API, to benefit from delivery and feature improvements. MM Lite API delivers comparable or a greater number of marketing messages than Cloud API. MM Lite API allows for more dynamic messaging limits, so marketing messages with high engagement (for example, messages that receive more reads) can reach more customers.

In India, MM Lite API marketing messages that receive higher engagement (for example, reads) have been observed to deliver up to 9% more messages compared to Cloud API*.

Steps to take to troubleshoot lower delivery rates after moving to MM Lite API:

Step 1: Ensure your team understands the way that MM Lite API prioritizes relative to Cloud API.

On MM Lite API, high engagement messages can reach more customers. Where Cloud API's per-user message limits might not allow a message to be delivered to a user, MM Lite API can recognize high-engagement message templates (for example, messages that receive more reads), and when a message is sent, allow for dynamic messaging limits.

Step 2: Ensure that you are making an accurate comparison between MM Lite API and Cloud API.

Many delivery rate differences are because of variations, such as using different templates, times, or audiences. Verify that you are making an accurate comparison using the below guidelines before submitting a support request:

• Compare the same time period. To accurately compare message delivery, evaluate campaigns run over the same 4-7 day period. Per-user message limits are dynamic and change in real-time based on message volume, holidays, business activity, and user behavior, making comparisons of results from different timeframes unreliable.
• Compare the same (or extremely similar) templates. Delivery comparisons often mistakenly contrast message templates with different copy, read rates, and user engagement. Use the same template for both API endpoints. Ensure the template is active and follows guidelines for high-quality marketing messages.
• Compare large campaigns with equivalent audience demographics. Compare campaigns with at least 100,000 marketing messages sent to functionally identical audience cohorts. For example, randomly divide user segments to avoid bias (for example, different geographic regions, user filters, or ROI/engagement characteristics). Ensure no recipient receives messages more than once, including from other campaigns.
• Compare the same send time. Send campaigns to both endpoints simultaneously to minimize external impacts like blocks or flags.

Step 3: Ensure that you are not counting retried messages in your “delivery” statistics.

If a message fails to deliver because of per-user marketing message limits, wait 24 hours before retrying (see error code 131049). Repeated retries of the same messages will artificially lower your perceived delivery rate, as the same per-user limit might be still in effect resulting in the same outcome. For example, if 20 of 100 messages fail because of limits and are retried, the true 80% delivery rate could drop to ~67% after just one retry.

Step 4: Follow best practices for creating high-engagement marketing messages

• Quality and Relevance: Prioritize sending messages that offer clear value to customers and avoid non-relevant or impersonal outreach. Relevant messages are more likely to be read, leading to more engaged prospects and customers.
• Message Quality:
  • Expected: Customers have opted-in to receive these types of messages and generally engage with your marketing messages. Provide an opt-out option.
  • Timely: Messages are sent at a logical time (for example, after initial engagement or at a defined cadence) and appropriate frequency.
  • Relevant: Messages are personalized, contain valuable information, and include clear calls to action.
• Use MM Lite API Features, for example:
  • Customizable message validity periods (time-to-live) to ensure messages are timely
  • View your benchmarks recommendations to improve performance

I think my click-through rates are lower on MM Lite API than they were on Cloud API

Because MM Lite API prioritizes higher delivery of high-engagement messages for users, more deliveries of high-engagement messages can lead to higher click-through rates (CTR) or other outcomes on the API.

If you are finding a campaign's click-through rate is lower on MM Lite API vs. Cloud API, check the following:

1. Ensure that you are using an accurate A/B comparison of the same campaigns. See the guidance above for delivery rates to set up a reliable A/B comparison of the same template, at the same time, to a comparable audience of sufficient size, to ensure that other factors are not invalidating the comparison of CTR on MM Lite API vs. Cloud API.
2. Ensure your URL is compatible with Meta's conversion measurement. Broken URLs will lower click-through rate. See directions below.
3. Assess whether automated creative optimizations should be enabled for your campaign. Some businesses are enrolled in a pilot of automated creative optimizations which tests minor variations of marketing message templates, and automatically selects the variant getting the highest click-through rate over time. Work with your partner to determine if your business uses these features and if your campaign is suitable

I'm not seeing website or app conversion metrics for my marketing messages

Ensure your URL is compatible with conversion measurement by sending a test event. Some partners will reformat URLs before sending them to MM Lite API, which breaks Meta's ability to append a Click ID to the URL which enables conversion measurement.

Reach out to your Meta partner if you are working with a platform or partner whose URL reformatting breaks Meta's conversion measurement. If your app is using Meta SDK, you must upgrade your SDK version to Meta Android SDK v17.0.2 or above.

I still need help

If you have followed all troubleshooting steps above and still are experiencing issues please submit a direct support question using the question type "WABiz: Marketing Messages."

• For lower deliveries on MM Lite vs. Cloud API for similar campaigns, select WABiz: Marketing Messages > Message Delivery and include the details of how the campaigns you are comparing are accounting for similar time, audience, template, and retry normalization.

MM Lite API error codes

The MM Lite API uses the same error codes as the Cloud API, with a few additions, listed below.

Syntax

{
  "error": {
    "message": "<MESSAGE>",
    "type": "<TYPE>",
    "code": <CODE>,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "<DETAILS>"
    },
    "fbtrace_id": "<TRACE_ID>"
  }
}

Example

{
  "error": {
    "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Message must be a template message."
    },
    "fbtrace_id": "Ak6nxJSySLEJz32Ps-QiZ1t"
  }
}

Codes

FAQs

General FAQs

Technical implementation FAQs

Reliability FAQs