Meta WhatsApp Access Tokens Access Tokens Guide | Developer Documentation Access Tokens Guide Updated: Mar 1, 2026 The platform supports the following access token types. The type you use depends on who will be using your application, and whether you are a solution provider.If you are a direct developer, meaning only you or your business will be accessing your own data, use a System User access token.If you are a Tech Provider, use a Business Integration System User access token.If you are a solution partner, use System User access tokens to share your line of credit with newly onboarded customers, and Business Integration System User access tokens for everything else. System user access tokens System user access tokens (“system tokens”) represent you, your business, organization, or people within them. The main advantage of these tokens is that they are long-lived and can represent automated services within your business that don’t require any user input. System tokens rely on system users. Most endpoints check if the user identified by the token has access to the queried resource. If the user doesn’t have access to the resource, the system rejects the request with error code 200. System users can be admins or employees. Admin system users By default, admin system users have full access to all WhatsApp Business Accounts (WABAs) and their assets owned by or shared with you or your business portfolio. Admin system users are useful if your app needs access to all of the business portfolio’s assets, without having to manually grant business asset access to each asset whenever it is created, or shared with your business portfolio. You can override an admin system user’s default business asset access by granting partial access on a per-WABA basis. See Business Asset Access to learn how to set and override access. Employee system users Employee system users must be granted access to individual WABAs that are owned by, or shared with, your business portfolio. If your app will only need access to a few WABAs that you own, an employee system user should be sufficient. Once created, you must grant Partial or Fullbusiness asset access to each WABA that the system user needs to access. Generate system user access tokens To generate a system token, access the Business settings⁠ panel and then click System Users: Click the +Add button, and in the Create system user window that appears, enter a system user name and assign it an Admin or Employee role: Once you create the admin system user, it appears in the list of system users. Click the system user’s name to display the asset assignment overlay: Click the Assign assets button to display the Select assets and assign permissions window: Select your app and grant your system user the Manage app permission, then click the Assign assets button to confirm and dismiss the window. Back in the System Users panel, reload the page to confirm that your system user has been granted Full control of your app. It may take a few minutes for the permissions to be granted, so reload the page after a few minutes if your app doesn’t appear as an assigned asset. Once the asset has been assigned, it should look like this: Once you see that your system user has been granted full control of your app, in the asset assignment overlay, click the Generate token button. In the window that appears, select your app, choose a token expiration preference, and assign your app these three Graph API permissions: business_management whatsapp_business_management whatsapp_business_messaging You can search for business to find these permissions quickly: Click the Generate token button and copy the token when it appears. Business Integration System User access tokens Business Integration system user access tokens (“business tokens”) are scoped to individual onboarded customers and should be used by Tech Providers and solution partners when accessing onboarded customer data. These tokens are useful for apps that perform programmatic, automated actions on customer WABAs, without having to rely on input from an app user, or requiring future re-authentication. To generate a Business Integration System User access token, you must implement Embedded Signup (configured with Facebook Login for Businesses) and exchange the code returned to you when a customer completes the flow. See Embedded Signup and Business Integration System User access tokens to learn more about these tokens and how to generate them. User access tokens Although User access tokens are supported and can be used by all app developers, you likely will only use them when you first use the App Dashboard to send your first test message. As you develop your app, however, you most likely will switch to a System User access token (and eventually a Business System User access token, if you are a Tech Provider or a Solution Provider). This is because user access tokens expire quickly, so you will have to keep generating a new one every few hours. There are several ways to generate a User access token:Access the App Dashboard > WhatsApp > API setup panel. This panel always generates a new User access token whenever you visit it. The token is automatically scoped to your user, since you are signed into your developer account when you access the panel.Use Graph API Explorer.Implement Facebook Login. Use tokens in requests When making API requests, include your token in an authorization request header, preceded by Bearer. For example: Business asset access After creating a system user, you must set business asset access levels. Many endpoints require the system user whose token is included in API requests to have either Partial or Full business asset access to the WABA being queried (or its assets). If the system user doesn’t have this access, these endpoints return error code 200. If you set a system user’s business asset access on a WABA to Partial access, you can further restrict access to certain assets or actions on the WABA. For example, if you have a large business and want a certain department to only have read access to a WABA’s template and business phone number data, you could create a system user for that department and set granular access to view only for that data. To set business asset access on a WABA, follow these steps:Sign into Meta Business Suite⁠.Locate your business portfolio in the dropdown menu at the top of the page and click its Settings (gear) icon.Navigate to Accounts > WhatsApp Accounts.Select the appropriate WABA.Select the WhatsApp Account Access tab.Click the +Add people button.Select the appropriate system user and assign appropriate access levels on the WABA. Analytics Analytics | Developer Documentation Analytics Updated: Feb 12, 2026 Starting December 1, 2025, the maximum lookback window for messaging, conversation, and pricing analytics is changing from 10 years to 1 year. The lookback window for template and template group analytics will be unaffected and will continue to be 90 days. This document describes how to get messaging, conversation, template, and group analytics, such as the number of messages sent from a business phone number, the number of conversations and their costs for a WhatsApp Business Account (WABA), or the number of times a given template has been read. Only metrics for business phone numbers and templates associated with your WABA at the time of the request will be included in responses. Get data Request parameters Placeholder Description Example Value Required. Metric. Value can be one of: analytics conversation_analytics pricing_analytics template_analytics template_group_analytics call_analytics group_analytics analytics Required. Metric filtering parameter. Append additional filtering parameters using dots. For possible values, see:Messaging analytics parametersConversation analytics parametersTemplate analytics parametersTemplate group analytics parametersCall analytics parametersGroup analytics parameters .start(1543543200).end(1544148000).granularity(DAY) Pricing analytics The pricing_analytics field allows you to get pricing breakdowns for any messages delivered within a specified date range. Request syntax GET / ?fields=pricing_analytics .start() .end() .granularity() .phone_numbers() .country_codes() .metric_types() .pricing_types() .pricing_categories() .dimensions() Pricing analytics parameters Filter Description Example Value Array of strings Optional. The countries for which you would like to retrieve analytics. Provide an array with 2 letter country codes for the countries you would like to include. If not provided, analytics will be returned for all countries you have communicated with. [ US, BR ] Array of strings Optional. List of breakdowns you would like to apply to your metrics. If you send an empty list, we return results without any breakdowns. Values can be: COUNTRY PHONE PRICING_CATEGORY PRICING_TYPE TIER [ PRICING_CATEGORY, PRICING_TYPE, COUNTRY ] UNIX timestamp Required. UNIX timestamp indicating the end date for the date range you are retrieving analytics for. 1728581152 String Required. The granularity at which you would like to retrieve the analytics. Value can be one of: DAILY HALF_HOUR MONTHLY DAILY Array of strings Optional. Array of metrics you would like to receive. If you send an empty array, we return results for all metric types. Values can be: COST: Approximate charges for messages delivered in that time range, in your WABA's currency. VOLUME: Includes the number of messages delivered for that time range. Note that COST will not be returned for WABAs that share a Solution Partner's credit line. If your WABA shares a Solution Partner's credit line, reach out to your Solution Partner to understand your charges. [COST, VOLUME] Array of strings Optional. An array of phone numbers for which you would like to retrieve analytics. If not provided, data for all business phone numbers associated with your WABA are included. [ 15550783881, 15550783882, 15550783883 ] Array of strings Optional. Array of pricing categories. If you send an empty array, we return results for all pricing categories. Values can be: AUTHENTICATION: Messages charged the authentication rate. AUTHENTICATION_INTERNATIONAL: Messages charged the authentication-international rate. MARKETING: Messages charged the marketing rate. SERVICE: Messages that were not charged. Includes all non-template messages and utility messages sent inside of a customer service window. UTILITY: Messages charged the utility rate. REFERRAL_CONVERSION: Messages that have been received through a free entry point [ AUTHENTICATION, MARKETING, UTILITY ] Array of strings Optional. Array of pricing types. If you send an empty array, we return results for all pricing types. Values can be: FREE_CUSTOMER_SERVICE: Free messages. These are non-template messages and utility messages sent within customer service windows. FREE_ENTRY_POINT: All messages sent within free entry point customer service windows. REGULAR: Billable messages. Includes all authentication and marketing template messages, and any utility template messages sent outside of a customer service window. Excludes all messages sent within free entry point customer service windows. [ REGULAR, FREE_CUSTOMER_SERVICE ] UNIX timestamp Required. UNIX timestamp indicating the start date for the date range you are retrieving analytics for. 1726014453 String Required. WhatsApp Business Account ID. 102290129340398 Volume tier information Include the TIER, PRICING_CATEGORY, and COUNTRY parameters in the dimensions array to get volume tier information. Data points representing messages affected by volume tier pricing will have a tier property in the response. Example response syntax with tier information The tier property value represents a concatenation of the lower and upper bounds for the tier specific to the market-category pair ( country and pricing_category) that that data point represents. - An integer representing the lower bound of the tier (inclusive). - An integer representing the upper bound of the tier (inclusive), or the string MAX. NotesTo determine your current volume tier, read the tier, country, and pricing_category values. The tier value's integer (the integer after the colon) tells you your current tier for the country and pricing_category (for example, (India and utility, respectively).To determine how many messages you need to send to reach the next tier for a given country and pricing_category, subtract the volume integer from the tier value's integer.Volume tiers will only be available for utility and authentication template messages. For marketing template messages (where volume tiers will not apply), tier will be set to 0:MAX.The tier property will be omitted for data points that represent free messages, since free messages don't contribute to tiering counts.Volume tiers will be determined solely by Meta. All insights data is approximate due to small variations in data processing. Undue reliance should not be placed on insights data. Template analytics Template analytics describe the number of times a template has been sent, delivered, and read, and the number of times URL buttons or Quick Reply buttons in the template have been clicked. Additionally, onboarded MM API for WhatsApp businesses can track offsite conversion metrics. Data is returned with a daily granularity in the default timezone of UTC and WABA's timezone, with a lookback window of up to 90 days. To show data in the WABA's configured timezone, pass in the use_waba_timezone param with a value of true. Display data in the WABA's configured timezone by passing in the use_waba_timezone param with a value of true. LimitationsButton click analytics are only available for templates categorized as MARKETING or UTILITY.WABAs owned by or shared with Meta Business Accounts in the European Union, United Kingdom, or Japan, or that have a business phone number with a country calling code from any of those countries or regions, are not supported.Offsite conversion metrics are available exclusively for businesses onboarded to MM API for WhatsApp.Read and click event data for WhatsApp template messages is only available for up to 7 days from the date the message is sent. After this 7-day window, the corresponding read/click counts reset to zero and no further updates are recorded for those messages. Confirming template analytics You must confirm template analytics on your WhatsApp Business Account before you can get template analytics. You can confirm template analytics using the WhatsApp Manager or the API. By confirming access via the API, you direct Meta to add insights to your WhatsApp Business Account. These insights include link tracking to report website clicks. You can turn off link tracking on each message template. You also direct Meta to collect and anonymize data from your chats with customers. Meta will anonymize this data to improve services it provides you and other businesses. To confirm via API, send the following request: Once confirmed, we will begin capturing template analytics for the WhatsApp Business Account. Once confirmed, template analytics cannot be disabled. Upon success, the API will respond with your WhatsApp Business Account ID. For example: Template analytics parameters Name Description Example Value start UNIX Timestamp or date string Required. The start time for the date range you are retrieving analytics for. Can be represented as either a unix timestamp integer or a date string in the format YYYY-MM-DD. As template analytics are being provided with a daily granularity in the UTC timezone, a start unix timestamp that does not correspond to 0:00 UTC will be adjusted back to the current day's 00:00 UTC. If use_waba_timezone param has a value of true, this value must be a date string in the format YYYY-MM-DD. 1543536000 end UNIX Timestamp or date string Required. The end time for the date range you are retrieving analytics for. Can be represented as either a unix timestamp integer or a date string in the format YYYY-MM-DD. As template analytics are being provided with a daily granularity in the UTC timezone, an end unix timestamp that does not correspond to 0:00 UTC will be adjusted back to the current day's 00:00 UTC. If use_waba_timezone param has a value of true, this value must be a date string in the format YYYY-MM-DD. 1543708800 granularity Enum Required. The granularity at which you would like to retrieve the analytics. Value must be DAILY. DAILY template_ids Array of IDs Required. An array of template IDs for which you would like to retrieve analytics for. Maximum 10. [1924084211297547,954638012257287,969725530748535] metric_types Array of enums Optional. The types of metrics which you want to retrieve. If omitted or an empty array, analytics for all metric types will be returned. Possible values: COST CLICKED DELIVERED READ SENT APP_ACTIVATIONS (MM API for WhatsApp only) APP_ADD_TO_CART (MM API for WhatsApp only) APP_CHECKOUTS_INITIATED (MM API for WhatsApp only) APP_PURCHASES (MM API for WhatsApp only) APP_PURCHASES_CONVERSION_VALUE (MM API for WhatsApp only) WEBSITE_ADD_TO_CART (MM API for WhatsApp only) WEBSITE_CHECKOUTS_INITIATED (MM API for WhatsApp only) WEBSITE_PURCHASES (MM API for WhatsApp only) WEBSITE_PURCHASES_CONVERSION_VALUE (MM API for WhatsApp only) You can learn more about cost and click metrics here.. Note that COST will not be returned for WABAs that share a Solution Partner's credit line. If your WABA shares a Solution Partner's credit line, reach out to your Solution Partner to understand your charges. [SENT,DELIVERED,READ] product_type Enum Optional. The product type of the metrics you want to retrieve. If omitted, only analytics for Cloud API will be returned. Possible values: CLOUD_API: Use this product type to filter for template metrics sent via Cloud API MARKETING_MESSAGES_API_FOR_WHATSAPP: Use this product type to filter for template metrics sent via Marketing Messages API for WhatsApp MARKETING_MESSAGES_API_FOR_WHATSAPP Boolean Optional. Whether to show metrics in the WABA's configured timezone. If false or omitted, metrics will be shown in UTC. If true, params start and end must be in the format YYYY-MM-DD. true Template analytics cost and click metrics Cost metrics are returned as an array of cost objects, each with a type and value. Types can be: amount_spent - Total amount spent on conversations opened within the start and end timeframe as a result of sending the template. See Opening Conversations. cost_per_delivered - The amount_spent value divided by the number of times the template was delivered within the start and end timeframe. cost_per_url_button_click - The amount_spent value divided by the number of times the template's URL button was clicked, within the start and end timeframe. Quick reply button clicks are not included. Object omitted if the template does not have a URL button. Click metrics are returned as an array of JSON objects each with a type and value. Clicks are only returned for URL buttons and quick-reply buttons in templates categorized as MARKETING or UTILITY. Types can be: url_button - The total number of clicks on the url button. unique_url_button - Unique clicks track the number of distinct WhatsApp accounts that have clicked on a button. This metric helps you understand how many individual users are engaging with your CTAs, while eliminating duplicate clicks from the same recipient and providing an accurate measurement of engagement. Disabling button click analytics You can disable button click tracking on an individual template by setting its cta_url_link_tracking_opted_out field to true. Once disabled, the API will no longer return the clicked property in template analytics or display button engagement/clicks in the WhatsApp Manager when viewing the template's insights. Request parameters Placeholder Description Example Value Template ID Required. Template ID. 245435364965041 Boolean Required. Indicates if template button click tracking is disabled. Set to true to disable button click tracking on the template, or false to enable. This value is set to false upon template creation. true String Required. Template's current category. If you set the template category to a value other than its current category, the template status will be set to PENDING and the template must undergo template review to be approved. marketing Template group analytics The template_group_analytics field allows you to get the number of times templates within a template group have been sent, delivered, and read, and the number of times their URL buttons or Quick Reply buttons have been clicked. Data is returned with a daily granularity in the default timezone of UTC and WABA's timezone, with a lookback window of up to 90 days. To show data in the WABA's configured timezone, pass in the use_waba_timezone param with a value of true. Limitations Button click analytics are only available for templates categorized as marketing or utility. WABAs owned by or shared with Meta Business Accounts in the European Union, United Kingdom, or Japan, or that have a business phone number with a country calling code from any of those countries or regions, are not supported. Enabling template analytics You must enable template analytics on your WhatsApp Business Account before you can get template group analytics. You can confirm template analytics enablement using the WhatsApp Manager or the API. By confirming access via the API, you direct Meta to add insights to your WhatsApp Business Account. These insights include link tracking to report website clicks. You can turn off link tracking on each message template. You also direct Meta to collect and anonymize data from your chats with customers. Meta will anonymize this data to improve services it provides you and other businesses. To confirm enablement via API, send the following request: Upon success, the API will respond with your WhatsApp Business Account ID and we will begin capturing template group analytics for the WhatsApp Business Account. Once enabled, template analytics cannot be disabled. Template group analytics parameters Placeholder Description Example value String Required. WhatsApp Business Account ID. 102290129340398 UNIX Timestamp or date string Required. The start time for the date range you are retrieving analytics for. Can be represented as either a unix timestamp integer or a date string in the format YYYY-MM-DD. As template group analytics are being provided with a daily granularity in the UTC timezone, a start unix timestamp that does not correspond to 0:00 UTC will be adjusted back to the current day's 00:00 UTC. If use_waba_timezone param has a value of true, this value must be a date string in the format YYYY-MM-DD. 1738465116 UNIX Timestamp or date string Required. The end time for the date range you are retrieving analytics for. Can be represented as either a unix timestamp integer or a date string in the format YYYY-MM-DD. As template group analytics are being provided with a daily granularity in the UTC timezone, an end unix timestamp that does not correspond to 0:00 UTC will be adjusted back to the current day's 00:00 UTC. If use_waba_timezone param has a value of true, this value must be a date string in the format YYYY-MM-DD. 1739559516 Array of strings Optional. Array of metrics you would like to receive. If you send an empty array, the API returns results for all metric types. Values can be: cost clicked delivered read sent Note that COST is not accessible to business customers who are billed through a Solution Partner. See Cost and click metrics to learn more about cost and click metrics. [ sent, delivered, read ] Required. An array of template group IDs for which you wish to get template group metrics. Maximum 10 IDs. 102290129340398 ` Boolean Optional. Whether to show metrics in the WABA's configured timezone. If false or omitted, metrics will be shown in UTC. If true, params start and end must be in the format YYYY-MM-DD. true Template group cost and click metrics Cost metrics are returned as an array of cost objects, each with a type and value. Types can be: amount_spent - Total amount spent on conversations opened within the start and end timeframe as a result of sending the template. See Opening Conversations. cost_per_delivered - The amount_spent value divided by the number of times the template was delivered within the start and end timeframe. cost_per_url_button_click - The amount_spent value divided by the number of times the template's URL button was clicked, within the start and end timeframe. Quick reply button clicks are not included. Object omitted if the template does not have a URL button. Click metrics are returned as an array of JSON objects each with a type and value. Clicks are only returned for URL buttons and quick-reply buttons in templates categorized as marketing or utility. Types can be: url_button - The total number of clicks on the url button. unique_url_button - Unique clicks track the number of distinct WhatsApp accounts that have clicked on a button. This metric helps you understand how many individual users are engaging with your CTAs, while eliminating duplicate clicks from the same recipient and providing an accurate measurement of engagement. Block Users Block Users API guide | Developer Documentation Block Users API guide Updated: Feb 23, 2026 The Block Users API enables your business to block bad actors from contacting you. How it works When you block a WhatsApp user, the following happens:The user cannot contact your business or see that you are online.Your business cannot message the user. If you do, you will encounter an error. Errors on the API occur per-number since blocks might succeed on some numbers and fail on others. The Block Users API is synchronous. LimitationsYou can only block users that have messaged your business in the last 24 hours.You cannot use this API to block another WhatsApp Business account.The blocklist has a 64,000 user limit. Features The API contains three endpoints: Error codes Code Description 139100 Failed to block/unblock some users Bulk blocking failed to block some or all of the users. 139101 Blocklist limit reached The blocklist has reached its 64,000 user limit. 139102 Blocklist concurrent update Occurs when the blocklist is updated while performing a pagination request and version_id does not match. 139103 Internal error Internal error, please try again. 130429 Rate Limit Hit Occurs when either:Too many numbers are in the request itself.Or, too many requests are made over a short period of time. 131021 Self Block Failed to block self phone number. 131047 Re-engagement required Occurs if the business has not received a message from that number in the last 24 hours. This error will also be returned if the number is an invalid WhatsApp user. Business Phone Numbers Business phone numbers | Developer Documentation Business phone numbers Updated: Feb 27, 2026 This document describes WhatsApp business phone numbers, their requirements, management information, and unique features. Registering business phone numbers A valid business phone number must be registered before it can be used to send and receive messages via Cloud API. Registered numbers can still be used for everyday purposes, such as calling and text messages, but cannot be used with WhatsApp Messenger (“WhatsApp”). Numbers already in use with WhatsApp cannot be registered unless they are deleted⁠ first. If your number is banned on WhatsApp and you wish to register it, it must be unbanned via the appeal process⁠ first. Note that when you complete the steps in our Get Started document, a test business phone number will be generated and registered for you automatically. Eligibility requirements Eligible phone numbers must be:owned by youhave a country and area code (short codes are not supported)able to receive voice calls or SMSnumber should have scaled capabilities⁠ If you are registering a 1-800 number, see 1-800 and toll free numbers for additional information. Registration methodsApp Dashboard: Complete the steps in our Get Started document if you haven’t already, then use the App Dashboard > WhatsApp > API Setup panel to add a phone number.Meta Business Suite: You can register a business phone number when using Meta Business Suite to create a WhatsApp Business Account.WhatsApp Manager: See our How to connect your phone number to your WhatsApp Business Account⁠ help center article.Embedded Signup: If you are working with a solution partner, they will provide you with a link to Embedded Signup, which you can use to register a number. Note: The methods above add a phone number to your WhatsApp Business Account and verify your ownership, but they do not register the number for Cloud API use. To complete registration, call the register endpoint. If you are a Solution Partner or Tech Provider using Embedded Signup, see Registering business phone numbers. Business phone number types This table categorizes phone number types and evaluates their suitability for receiving OTPs via SMS, international phone calls, and flash calls. It provides likelihood assessments for successful delivery based on number type and carrier characteristics. Additionally, it offers actionable recommendations for users to improve delivery success without changing their phone number type. Phone type Description SMS OTP Voice OTP Actions Mobile (recommended) Assigned to mobile devices/SIMs Standard Standard Enable International reception of SMS/Calls, ensure device is connected to Cellular Network, Grant App permissions Fixed line Assigned to physical locations (landline) Not Recommended Standard Enable International reception of SMS/Calls, ensure line is ready for incoming calls and disable call forwarding or IVR features Freephone Toll-Free, recipient pays Not Recommended Standard Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features Premium rate Higher charges for special services Not Recommended Standard Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features Shared cost Cost shared between caller and recipient Not Recommended Not Recommended Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features Universal access Reachable globally for customer service Not Recommended Standard Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features Personal number Assigned to individuals, not tied to device Not Recommended Not Recommended Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features VoIP Internet telephony, not tied to physical line Not Recommended Standard Confirm that the VoIP provider supports international SMS/calls for OTPs; check provisioning and account settings; keep app/service running and notifications enabled; ensure device is online and permissions granted Inbound only Only accept incoming calls/messages Not Recommended Standard Ensure with Phone provider that the number is able to receive International SMS/Calls, check that line is ready for incoming calls and disable call forwarding or IVR features Pager Assigned to pagers (rare) Not supported Not supported Not supported M2M/IoT Machine-to-machine, smart devices Not Recommended Not Recommended Ensure device and SIM are allowed for incoming International SMS/calls Status Business phone numbers have a status, which reflects their quality rating and current messaging limit. Business phone numbers must have a status of “connected” in order to send and receive messages via the API. Viewing status via WhatsApp Manager Your business phone number’s current status appears in the Status column in the WhatsApp Manager⁠ > Account tools > Phone numbers panel. See our About your WhatsApp Business phone number’s quality rating⁠ help center article to learn more about quality ratings and statuses as they appear in WhatsApp Manager. Getting status via API Display names You must provide display name information when registering a business phone number. The display name appears in your business phone number’s WhatsApp profile, and can also appear at the top of individual chat threads and the chat list if certain conditions are met. See our Display names document to learn how display names work. Business profiles A business profile provides additional information about your business, such as its address, website, description, and so on. You can supply this information when registering your business phone number. See our Business profiles document to learn how business profiles work. Official Business Account status Business phone numbers can gain Official Business Account (OBA) status. OBA numbers have a blue checkmark beside their name in the contacts view. See our Official Business Account document to learn how to request OBA status for a business phone number. 1-800 and toll free numbers You may want to register a 1-800 or other toll free number on the platform. These numbers are usually behind an Interactive Voice Response (IVR) system. A WhatsApp registration call cannot navigate an IVR. Phone numbers behind an IVR system can be registered, but must be able to accept calls from international numbers and be able to redirect our SMS message or voice call to a real person. To register a phone number that is behind an IVR system:WhatsApp shares with you 1 or 2 phone numbers that the registration call will come from.Create an allow list for these numbers. If you are unable to create an allow list for these numbers, add the phone number to your WABA and open a Direct Support ticket asking for the registration call phone numbers and include the phone number you are trying to register in the ticket.Redirect the registration call to an employee or a mailbox to capture the registration code. Phone numbers behind an IVR system that are unable to receive registration calls are not supported. Registered number cap New business portfolios are initially capped at 2 registered business phone numbers. If your business becomes verified⁠, or if you have reached a messaging limit of 2,000, Meta will automatically increase your cap to 20. Upon increase, a Meta Business Suite notification will be sent, informing you of your new cap, and a business_capability_update webhook will be triggered with max_phone_numbers_per_business set to your new cap. WhatsApp user phone number formats Plus signs ( +), hyphens ( -), parenthesis ( (, )), and spaces are supported in send message requests. We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number’s country calling code is prepended to the customer’s phone number. This can result in undelivered or misdelivered messages. For example, if your business is in India (country calling code 91) and you send a message to the following customer phone number in various formats: Number In Send Message Request Number Message Delivered To Outcome +16315551234 +16315551234 Correct number +1 (631) 555-1234 +16315551234 Correct number (631) 555-1234 +916315551234 Potentially wrong number 1 (631) 555-1234 +9116315551234 Potentially wrong number Note: For Brazil and Mexico, the extra added prefix of the phone number may be modified by the Cloud API. This is a standard behavior of the system and is not considered a bug. Identity change check You may want Meta to verify a customer’s identity before delivering your message to them. You can have us do this by enabling the identity change check setting on your business phone number. If a customer performs an action in WhatsApp that is considered an identity change, Meta generates a new identity hash for the user. To get this hash when messaging a customer, enable the identity change check setting on your business phone number. Once enabled, anytime the customer messages you, or you message the customer without an identity hash, any incoming messages webhooks or status messages webhooks will include their hash. You can then capture and store this hash for future use. To use the hash, include it in a send message request. Meta compares the hash in the request to the customer’s current hash. If the hashes match, the message will be delivered. If there is a mismatch, it means the customer has changed their identity since you last messaged them and the message will not be delivered. Instead, you will receive a status messages webhook with error code 137000, notifying you of the failure and mismatch. When you receive a mismatched hash webhook, assume the customer’s phone number can no longer be trusted. To reestablish trust, verify the customer’s identity again using other, non-WhatsApp channels. Once you have reestablished trust, resend the failed message to the new identity (if any), without a hash. Then store the customer’s new hash included in the message status delivery webhook. Post body Set to true to enable identity check, or false to disable it. Get throughput level Use the WhatsApp Business Phone Number endpoint to get a phone number’s current throughput level: Get a single phone number To get information about a phone number, send a GET request to the WhatsApp Business Phone Number endpoint: Get display name status (beta) Include fields=name_status as a query string parameter to get the status of a display name associated with a specific phone number. This field is currently in beta and not available to all developers. Deleting business phone numbers Only business portfolio admins can delete business phone numbers, and numbers can’t be deleted if they have been used to send paid messages within the last 30 days. Deleting business phone numbers via WhatsApp Manager If your business phone number has a Connected status, you will need your two-step verification PIN to delete your number.Load your business portfolio in the WhatsApp Manager⁠.If it doesn’t automatically load the Phone numbers panel, navigate to Account tools (the toolbox icon) > Phone numbers.Click the phone number’s trash can icon and complete the flow. If the number has been used to send paid messages within the last 30 days, you will be redirected to the Insights panel, showing the date of the last paid message. You can delete the number 30 days from this date. Deleting business phone numbers via API You cannot delete a business phone number via API. Migrating business phone numbers You can migrate phone numbers from one WABA to another. Conversational components You can enable helpful message UI components to make it easier for WhatsApp users to interact with your business. See Conversational components. Register a Business Phone Number | Developer Documentation Register a Business Phone Number Updated: Mar 31, 2026 To use your business phone number with Cloud API you must register it. Registration can only be done via API - you cannot register a number through WhatsApp Manager? (WAM) or the App Dashboard. To get your number ready for Cloud API, complete the following steps:Add your business phone number to your WhatsApp Business account using WhatsApp Manager.Verify ownership of the number using WhatsApp Manager.Register your business phone number by making an API call to the registration endpoint below. Register your business phone number in the following scenarios:Account creation - When you implement this API, register the business phone number you want to use. Meta enforces two-step verification during account creation to add an extra layer of security to your accounts.Name change - If your phone is already registered and you want to change its display name, you can update it via WhatsApp Manager? or via API. Once the name change is approved (confirmed via the phone_number_name_update webhook), re-register your phone number using the endpoint below. Wait for approval before re-registering, as re-registering before approval has no effect. See Display names for the complete workflow. Migration exception If you are migrating a phone number from the On-Premises API to the Cloud API, there are extra steps you need to perform before registering a phone number with the Cloud API. See Migrate From On-Premises API to Cloud API for the full process. Register a business phone number To register your verified business phone number, make a POST call to PHONE_NUMBER_ID/register. Include the parameters listed below. Endpoint Authentication PHONE_NUMBER_ID/register (See Get Phone Number ID) Solution Partners must authenticate themselves with an access token with the whatsapp_business_management and whatsapp_business_messaging permissions. Limitations Requests to the registration endpoint are limited to 10 requests per business number in a 72-hour moving window. When you make a registration request, the API checks how many registration requests you have made to register that number in the last 72 hours. If you have already made 10 requests, the API will return error code 133016, and the number will be prevented from being registered for the next 72 hours. Parameters Name Description messaging_product Required. Messaging service used. Set this to "whatsapp". pin Required. If your verified business phone number already has two-step verification enabled, set this value to your number's 6-digit two-step verification PIN. If you cannot recall your PIN, you can change it. See Two-step verification. If your verified business phone number does not have two-step verification enabled, set this value to a 6-digit number. This will be the newly verified business phone number's two-step verification PIN. data_localization_region Optional. If included, enables local storage on the business phone number. Value must be a 2-letter ISO 3166 country code (for example, IN) indicating the country where you want data-at-rest to be stored. Supported values: APACAustralia: AUIndonesia: IDIndia: INJapan: JPSingapore: SGSouth Korea: KR EuropeEU (Germany): DESwitzerland: CHUnited Kingdom: GB LATAMBrazil: BR MEABahrain: BHSouth Africa: ZAUnited Arab Emirates: AE NORAMCanada: CA Once you enable local storage, you cannot disable or change it directly. Instead, you must deregister the number and register it again without this parameter (to disable), or include the parameter with the new country code (to change). If the number is already registered, deregister it, then register it again with this parameter to enable local storage. Deregister a business phone number Deregistering a business phone number makes it unusable with Cloud API and disables local storage on the number, if it had been enabled. To use the number again, you must re-register it. To deregister a business phone number, make a POST call to PHONE_NUMBER_ID/deregister: Endpoint Authentication PHONE_NUMBER_ID/deregister (See Get Phone Number ID) Solution Partners must authenticate themselves with an access token with the whatsapp_business_management and whatsapp_business_messaging permissions. LimitationsThis endpoint cannot be used to deregister a business phone number that is in use with both Cloud API and the WhatsApp Business app.Deregistration does not delete a number or its message history. To delete a number and its history, see Delete Phone Number from a WABA.Requests to the deregistration endpoint are limited to 10 requests per business number in a 72-hour moving window. If you exceed this amount, the API will return error code 133016, and the business phone number will be prevented from being deregistered for the next 72 hours. See alsoResetting your PINCloud API Local Storage Two-Step Verification | Developer Documentation Two-Step Verification Updated: Nov 5, 2025 Set up two-step verification for your phone number to add an extra layer of security to your business accounts. To set it up, make a POST call to /PHONE_NUMBER_ID and attach the parameters below. There is no endpoint to disable two-step verification. Endpoint Authentication /PHONE_NUMBER_ID (See Get Phone Number ID) Solution Partners must authenticate themselves with an access token with the whatsapp_business_management and whatsapp_business_messaging permissions. Parameters Name Description pin Required. A 6-digit PIN you wish to use for two-step verification. Reset your PIN If you forget or misplace your PIN, you can update it by following these steps in WhatsApp Manager: Go to settings? and log into your Facebook Business. Click the business you use to manage your WABA (WhatsApp Business Account).In the settings screen, click WhatsApp Accounts. Find the WABA you want to update. Click the WABA. A panel with its info displays.In the WABA info panel, click Settings.In the new tab, click WhatsApp Manager.In WhatsApp Manager, find your phone number and click Settings.Click Two-step verification.In the Two-step verification tab, click Change PIN.Enter a new PIN and confirm it to complete the update. Conversational Components | Developer Documentation Conversational Components Updated: Mar 27, 2026 Conversational components are in-chat features that you can enable on business phone numbers. They make it easier for WhatsApp users to interact with your business. You can configure easy-to-use commands and provide pre-written ice breakers that users can tap. Limitations If a WhatsApp user taps a universal link? (that is, wa.me link) configured with pre-filled text, the user interfaces for ice breakers are automatically dismissed. Configure using WhatsApp Manager (WAM) You can configure all of these features in WhatsApp Manager on the specific numbers you choose: Navigate to the My Apps dashboard in the Meta for Developers site.Select your app, then on the left panel select Configuration under WhatsApp.Under Phone Numbers select Manage Phone Numbers.On the far right of the phone number you want to configure, select the Gear Icon under Settings.Select Automations.Access and configure Conversational Components. Solution Partners can configure these features for their customers as well if they have access to their customer's WhatsApp Business Account in WhatsApp Manager. Testing To test conversational components once they have been configured, open the WhatsApp client and open a chat with your business phone number. For ice breakers, if you already have a chat thread going with the business phone number, you must first delete the chat thread: Open the thread in the WhatsApp client.Tap the business phone number's profile.Tap Clear Chat > Clear All Messages.Delete Chat.Start a new chat thread with this business. You can then send a message to the business phone number to test your ice breakers. Media | Developer Documentation Media Updated: Dec 11, 2025 You use 4 different endpoints to manage your media: See Supported Media Types for supported types and size limits. Get media ID Some of the API requests described in this document require a media ID. Media IDs are returned by the API when uploading media, and are included in incoming media messages webhooks (image messages, video messages, etc.) Media IDs returned by the API expire after 30 days. Media IDs in webhooks expire after 7 days. Delete media Download media To download media, make a GET request on the media URL and include your access token. If you omit your token, the request will fail. Note that when retrieving a media from a media ID received via webhook, the media ID will only be available to download for 7 days. Supported media types Audio Audio Type Extension MIME Type Max Size AAC .aac audio/aac 16 MB AMR .amr audio/amr 16 MB MP3 .mp3 audio/mpeg 16 MB MP4 Audio .m4a audio/mp4 16 MB OGG Audio .ogg audio/ogg (OPUS codecs only; base audio/ogg not supported; mono input only) 16 MB Document Document Type Extension MIME Type Max Size Text .txt text/plain 100 MB Microsoft Excel .xls application/vnd.ms-excel 100 MB Microsoft Excel .xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 100 MB Microsoft Word .doc application/msword 100 MB Microsoft Word .docx application/vnd.openxmlformats-officedocument.wordprocessingml.document 100 MB Microsoft PowerPoint .ppt application/vnd.ms-powerpoint 100 MB Microsoft PowerPoint .pptx application/vnd.openxmlformats-officedocument.presentationml.presentation 100 MB PDF .pdf application/pdf 100 MB Image Images must be 8-bit, RGB or RGBA. Image Type Extension MIME Type Max Size JPEG .jpeg image/jpeg 5 MB PNG .png image/png 5 MB Sticker WebP images can only be sent in sticker messages. Sticker Type Extension MIME Type Max Size Animated sticker .webp image/webp 500 KB Static sticker .webp image/webp 100 KB Video Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only. Note that videos encoded with the H.264 “High” profile and B-frames are not supported by Android WhatsApp clients. We recommend that you use H.264 “Main” profile without B-frames, or the H.264 “Baseline” profile when encoding (or re-encoding with a tool like ffmpeg), and place moov boxes before mdat boxes, for broader compatibility. If you are using ffmpeg, you can use the -movflags faststart flag to place moov boxes before mdata boxes. Video Type Extension MIME Type Max Size 3GPP .3gp video/3gpp 16 MB MP4 Video .mp4 video/mp4 16 MB Note that mismatched MIME type ( 131053) is a common error. Inspect your media files to verify their MIME type. Make sure that your file name extensions reflect their types. For example, if you are using UNIX, you can inspect a file via the command line to determine its MIME type: file -I your-image-asset.png Media message download constraints The maximum supported file size for media messages on Cloud API is 100MB. In the event the customer sends a file that is greater than 100MB, you will receive a webhook with error code 131052 and title: “Media file size too big. Max file size we currently support: 100MB. Please communicate with your customer to send a media file that is smaller than 100MB”. Send customers a warning message that their media file exceeds the maximum file size when this webhook event is triggered. Learn more WhatsApp Business Blog – Sending WhatsApp media messages from an app⁠ Business Profiles Business profiles | Developer Documentation Business profiles Updated: Oct 5, 2025 Your business phone number's profile displays additional information such as address, website, and description. You can add this information when registering your phone number or update it later via WhatsApp Manager or API. Viewing or updating your profile via WhatsApp Manager To view or update your business profile via WhatsApp Manager: Navigate to WhatsApp Manager? > Account tools > Phone numbers.Select your business phone number.Click the Profile tab to view your current profile.Use the form to set new profile values. Business Scoped User Ids Business-scoped user IDs | Developer Documentation Business-scoped user IDs Updated: Mar 31, 2026 This document received a major update on March 18, 2026. See the changelog entry for details. WhatsApp is launching usernames later in 2026. Usernames are an optional feature for users and businesses. If a username is adopted by a WhatsApp user, their username will be displayed instead of their phone number in the app. Business usernames are not intended for privacy, however. If you adopt a business username, it will not cause your business phone number to be hidden in the app. To support usernames, Meta will share a new backend user identifier called business-scoped user ID, or BSUID. BSUID uniquely identifies a WhatsApp user and is tied to a specific business. This document describes how the addition of usernames will impact API requests, API responses, and webhook payloads. Additional changes to support usernames before the feature is made available will be recorded here. Any changes described in this document are subject to change. User usernames A user username is a unique, optional name that WhatsApp users can set in order to display their username instead of their phone number in the app. Usernames can be used in lieu of profile names when personalizing message content for individual users. WhatsApp users are limited to 1 username, but are able to change them periodically. Changing a username does not affect the user’s phone number or business-scoped user ID, and does not affect the user’s ability to communicate with other WhatsApp users or businesses on the WhatsApp Business Platform. User usernames have the same format restrictions as business usernames. Usernames are assigned to the username property in API responses and webhooks payloads. Once enabled, a WhatsApp user’s username will appear in all incoming messages webhooks, and all delivered and read status messages webhooks. Business-scoped user ID BSUIDs will begin appearing in webhooks in early April 2026. A BSUID is a unique user identifier that can be used to message a WhatsApp user when you don’t know their phone number. BSUID will be assigned to the user_id parameter and appear in all messages webhooks, regardless of whether or not the user has enabled the username feature. BSUIDs are scoped to individual business portfolios. This means that any business phone number owned by a given portfolio can be used to message a BSUID scoped to the same portfolio, and attempts to message the BSUID using a phone number owned by a different portfolio will fail. BSUIDs will be:generated automaticallyprefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code and a period, followed by up to 128 alphanumeric characters (for example, US.13491208655302741918)unique to each business portfolio-user pair (business portfolios⁠ were formerly known as Business Managers)regenerated if a user changes their phone number (which trigger a system status messages webhook) BSUIDs can be used to send any type of message except for one-tap, zero-tap, and copy code authentication templates, which require user phone numbers. When making API requests with BSUIDs, use the entire BSUID value: country code, period, and all alpha numeric characters. Omitting or changing the country code, period, or alpha numeric characters will cause your request to fail. If you are a managed business with multiple business portfolios, and want to use BSUIDs that will work across all of them, see Parent business-scoped user IDs. Parent business-scoped user IDs If you are a managed business and want to link business portfolios, you can ask your Meta point-of-contact to check if you are eligible. If you are eligible, and your business portfolios become linked, parent BSUIDs will be included in all messages webhooks, assigned to a new parent_user_id property. Parent BSUIDs can be used in place of regular BSUIDS to message users. Functionally, parent BSUIDs have the same properties as regular BSUIDs, but can be used by any business phone number within the set of linked portfolios. Parent BSUIDs follow the same format as regular BSUIDs, but include ENT between the country code and the alphanumeric identifier (for example, US.ENT.11815799212886844830). Note that you can still message users using their regular BSUID scoped to your business portfolio. Phone numbers If a WhatsApp user enables the username feature, their phone number will not be included in webhooks, unless you have interacted with the user before, as explained below. Therefore, regardless of whether or not the user has enabled the feature, the user’s BSUID will be included in any webhooks that would normally include their phone number, assigned to a new user_id property. To reduce the chance of losing conversation context with existing users who enable the usernames feature, user phone numbers will be included in webhooks if any of the following conditions are met:You have messaged or called the user’s phone number within the last 30 days of the webhook being triggeredYou have received a message or call from the user’s phone number within the last 30 days of the webhook being triggeredThe user is in your contact book Note that the 30-day lookback conditions above are evaluated per business phone number. If you message a user from one of your business phone numbers, webhooks associated with a different business phone number in your portfolio will not include the user’s phone number unless that specific number has also sent or received a message or call to or from the user’s phone number within the last 30 days. BSUIDs will begin appearing in webhooks in early April 2026. However, our APIs will not support sending messages targeted to the BSUIDs until May 2026 (exact date pending). Once our APIs support BSUIDs in May, you will be able to message users using either their BSUID, phone number, or both. If you are a solution provider and provide WhatsApp messaging services to your business customers, your customers will be able to use your app to message users, using their portfolio’s business phone numbers and any BSUIDs scoped to their portfolio. If you attempt to use one of your business customer’s BSUIDs with your own business phone number, however, it will fail, since BSUIDs are scoped to portfolios (and essentially, the assets the portfolio owns). If you are unsure of asset ownership:Send a GET request to the Client WhatsApp Business Accounts API to get a list of WABAs that you do not own, but that are shared with you.Send a GET request to the Owned WhatsApp Business Accounts API to get a list of WABAs that you own.Send a GET request to the Phone Numbers API to get a list of phone numbers owned by a given WABA. Contact book In early April 2026, to support messaging thread continuity, a contact book feature that stores WhatsApp user contact information is being released. The contact book is provided and hosted by Meta; no integration work is required. Once the feature is available, if you send a message/call to a user’s phone number, or receive a message/call from a user’s phone number, the user’s phone number and BSUID will be added to your contact book. Once this data has been recorded, it will be used to populate any webhook payloads and API responses that include the user’s phone number or BSUID, regardless of whether or not the user has enabled the usernames feature. The contact book is scoped to the business portfolio level, so any interaction between any business phone number within the business portfolio and a user will trigger the user’s phone number and BSUID to be stored in the contact book. Only interactions that occur after the contact book launches will trigger storage; prior interactions will not be retroactively captured, and contact information from those users will not be included in API responses or webhooks. Contact book data will be retained until you disable the feature, or deactivate your account. If you wish, you can disable this feature anytime after March 16, 2026, in the Meta Business Suite > Business settings > Business info⁠ panel. If you disable your contact book, it will stop storing user information, and any existing user information it has already stored will be deleted. If you re-enable the contact book later, it will start storing user information again, but previously stored information cannot be restored. Limitations:If you are using Local Storage and a user shares their phone number with you by tapping the share contact information button, Meta extracts the user’s phone number from the shared contact card (vCard) and stores it in your contact book on Meta data centers. Only the phone number is extracted and stored; no other vCard data is retained beyond the standard data-at-rest period for local storage.Contact books are scoped to business portfolios. This means that if you have linked portfolios, a user’s phone number and BSUID would have to be recorded to each portfolio’s contact book independently; user contact information is not shared or synced across linked portfolios. Country codes If a WhatsApp user enables the username feature, their phone number (and thus, country dialing code) may not appear in webhooks. In these cases, the user’s BSUID will appear instead, prefixed with the user’s ISO 3166 alpha-2⁠ two-letter country code (e.g., US.13491208655302741918). Business usernames Businesses will also be able to adopt a business username. If you adopt a business username, however, it will not cause your business phone number to be hidden in the WhatsApp or WhatsApp Business client. A business username is mapped to a single business phone number across all of WhatsApp, i.e. a phone number can have only one username at a given time, and no two WhatsApp phone numbers (consumer or business) can have the same username. Business usernames must adhere to the following format:may only contain English letters (a-z), digits (0-9), period (.) and underscore (_) charactersnon-English characters (such as ñ, é, ü) are not supported and will cause the request to failmust be between 3-35 characters in lengthmust contain at least one English letter (a-z, A-Z)must not start or end with a period or have 2 consecutive periodsmust not start with wwwmust not end with a domain (e.g., .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html, and so on)case is ignored when comparing usernames, but period and underscore characters are not; for example, myID and myid are the same username but myid, my.id, and my_id are all distinct Reserved usernames Before the username feature is made available, you will have the option to claim a username that WhatsApp has reserved for you. Alternatively, you can adopt a different username that aligns with your branding requirements. A reserved username can be claimed through WhatsApp Manager, Meta Business Suite, or via API. Claimed usernames that are approved will become active once the username feature is made available. If a reserved username is already in use with your Facebook Page or Instagram account, you must link your business phone number to your Facebook Page or Instagram account before you will be able to claim the username. You can link your phone number when claiming the username in Meta Business Suite or WhatsApp Manager, or by accessing your Facebook Page or Instagram account and adding your phone number directly⁠. To link your phone number, you must have full control of the page or account, or basic partial access with the manage_phone permission. See About business portfolio and business asset permissions⁠ for information about control/access and permissions. Chat window display priority The following priority will be followed (in decreasing order of priority) for displaying business profile information in chat windows in the app. Your business phone numbers will always appear in your business profile.Saved contact nameVerified business name or Official Business Account nameUsernamePhone number SupportYou can contact your Partner Manager with any concerns.You can reach out to any of the standard support channels; for API integrations, please raise a Direct support ticket with question type, WA Usernames API Integration.Use the Report Abuse channel via Direct Support⁠ to report impersonation.Use our WhatsApp Intellectual Property Contact Form⁠ form to report infringement. Get current username username — Current username. Will be omitted if the business phone number has no username. status — Username status. Values can be: approved — The username is approved and visible to WhatsApp users. reserved — The username is reserved for the business phone number but is not visible to WhatsApp users. It will become visible once the usernames feature is made available to everyone. Delete a username success — Boolean. Will be set to true if the username is deleted successfully, otherwise it will be set to false. business_username_updates webhook A new business_username_update webhook will be added. This webhook will be triggered when a business username status changes. Please subscribe each of your apps to this webhook field to be notified of username changes. id — WhatsApp Business Account ID. time — Unix timestamp indicated when the webhook was triggered. display_phone_number — The business phone number’s display number (the number displayed on your profile in the app). username — The username for which the status has changed. Omitted if status is set to deleted. status — Values can be: approved — Indicates the username is approved and visible to WhatsApp users. Triggered when the username’s status changes from reserved to approved, or the username was changed via the WhatsApp Business app. deleted — Indicates the username has been deleted via the WhatsApp Business app. reserved — Indicates the username is reserved for the business phone number but is not visible to WhatsApp users. It will become visible once the usernames feature is made available to everyone. Messages Error codes Adding new error code response to the POST //messages endpoint.Error code — 131062Details — Business-scoped User ID (BSUID) recipients are not supported for this message. Webhook testing You can test webhook payloads that reflect real-world username adoption scenarios using the App Dashboard > Use cases (pencil icon) > Connect with customers through WhatsApp > Customize > Configuration panel (App Dashboard > WhatsApp > Configuration for apps created before December, 2025). Click the Test link alongside the messages webhook to send a test messages webhook to your webhook endpoint. The test tool supports incoming messages webhooks and status messages webhooks for sent messages, with the following scenarios:User has not adopted a username — Webhook payloads will include BSUID fields and phone number fields, but no username. This represents the default state for most users at launch.User has adopted a username and phone number is unavailable — Webhook payloads will include the username and BSUID fields, but phone number fields will be omitted. Your integration should handle this scenario gracefully. See Phone numbers for conditions under which phone numbers are included.User has adopted a username and phone number is available — Webhook payloads will include all fields: username, BSUID, and phone number.Parent BSUID present — For businesses with linked business portfolios, webhook payloads will include a parent BSUID in addition to the portfolio-level BSUID. Webhook identifier quick reference The following tables summarize which user identifiers will be included in messages webhooks, based on the type of webhook and whether the user has adopted a username. Outbound message status webhooks These identifiers apply to sent, delivered, and read status messages webhooks. Identifier Sent to phone number Sent to BSUID wa_id Always included Included if phone number is available per Phone numbers conditions user_id Always included Always included parent_user_id Included if parent BSUIDs enabled Included if parent BSUIDs enabled username Included in delivered/read if user has a username Included in delivered/read if user has a username Incoming messages webhooks These identifiers apply to incoming messages webhooks, including user-initiated messages and user replies. Identifier User has a username User does not have a username wa_id Included if phone number is available per Phone numbers conditions Always included user_id Always included Always included parent_user_id Included if parent BSUIDs enabled Included if parent BSUIDs enabled username Always included Not included Messages webhooks Status messages webhooks These changes will apply to sent, delivered, read, and failed status messages webhooks. contacts — New array. Only included for sent, delivered, and read status messages. Will be omitted entirely for failed status messages webhooks. name — New property. Value will be set to the WhatsApp user’s display name. username — New property. Will be set to the WhatsApp user’s username if the user has enabled the usernames feature.Will be omitted entirely for sent status messages webhooks, or if the user has not enabled the usernames feature. wa_id — New property. Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.Will be omitted if the phone number cannot be included based on those conditions. user_id — New property. Will be set to the WhatsApp user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, the property will be omitted entirely. statuses recipient_id — New behavior (can be omitted). Will be set to the user’s phone number, if you sent the message to the user’s phone number.Will be set to the group ID, if you sent the message to a group.Will be omitted if you sent the message to the user’s BSUID or parent BSUID and we are unable to include their phone number based on the conditions described in the Phone numbers section. recipient_user_id — New property. Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted. parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted entirely. Example delivered status messages webhook describing a message sent from a business that has enabled parent BSUIDS to the phone number of a WhatsApp user who has enabled the usernames feature: Example delivered status messages webhook describing a message sent from a business that has enabled parent BSUIDS, to the BSUID of a WhatsApp user who has enabled the username feature. In this example, we are unable to include their phone number based on the conditions described in the Phone numbers section (so wa_id and recipient_id are omitted). Incoming messages webhooks These changes apply to incoming messages webhooks (text, image, interactive, and so on), including incoming messages sent by users in a Group chat. The example syntax below is for an incoming text message, but the changes are the same for all incoming message types. contacts profile username — New property. Will be set to the user’s username, if the user has enabled the username feature.Will be omitted if the user has not adopted a username. wa_id — New behavior (can be omitted). Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.Will be omitted if the phone number cannot be included based on those conditions. user_id — New property, set to the user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. messages from — New behavior (can be omitted). Will be set to the user’s phone number if the phone number can be included based on the conditions described in the Phone numbers section.Will be omitted if the phone number cannot be included based on those conditions. from_user_id — New property, set to the user’s BSUID. from_parent_user_id — New property, set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. Example incoming text message from a user who has enabled the username feature, to a business that has enabled parent BSUIDs. In this scenario, we are unable to include their phone number based on the conditions described in the Phone numbers section. System status messages webhooks These changes apply to system status messages webhooks. system body — New string. Will be set to User changed from to if the user changed their business phone number. wa_id — New behavior (can be omitted). Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.Will be set to the user’s phone number if the user has not enabled the usernames feature. user_id — New property. Will be set to the user’s new BSUID. parent_user_id — New property. Will be set to the user’s new parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. type — New value ( user_changed_user_id). Will be set to user_changed_user_id if the WhatsApp user changed their phone number. user_preferences webhooks These changes will apply to user_preferences webhooks. contacts profile username — New property. Will be set to the user’s username, if the user has enabled the username feature. Property omitted if the user has disabled the username feature. wa_id — New behavior (can be omitted). Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section.Will be set to the user’s phone number if the user has not enabled the usernames feature. user_id — New property. Will be set to the user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. user_preferences wa_id — New behavior (can be omitted). Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property,. Will be set to the user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. user_id_update webhooks A new user_id_update webhook will be triggered when a WhatsApp user’s BSUID changes. Subscribe your apps to this webhook field to be notified of BSUID changes. contacts wa_id — Will be set to the user’s phone number if available. Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. user_id_update wa_id — Will be set to the user’s phone number if available. Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. detail — A human-readable description of the update. user_id — Object containing the user’s previous and current BSUID. previous — The user’s old BSUID. current — The user’s new BSUID. parent_user_id — Object containing the user’s previous and current parent BSUID, if you have enabled parent BSUIDs. Otherwise, it will be omitted. previous — The user’s old parent BSUID. current — The user’s new parent BSUID. timestamp — Unix timestamp indicating when the webhook was sent. Groups API webhooks Status messages webhooks for groups These changes will apply to delivered and readstatus messages webhooks for messages sent to a group. contacts — New array. Only included for delivered and read status messages. Will be omitted entirely for failed status messages webhooks. name — New property. Value will be set to the WhatsApp user’s display name. username — New property. Will be set to the WhatsApp user’s username if the user has adopted a username. Will be omitted for sent status messages webhooks, or if the user has not enabled the usernames feature. wa_id — New property. Will be omitted if the user has adopted a username and we are unable to include their phone number based on the conditions described in the Phone numbers section.Will be set to the user’s phone number, if you sent the message to the user’s phone number. user_id — New property. Will be set to the WhatsApp user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted. recipient_participant_id — Changed. Will be set to the user’s phone number, if the message was sent to their phone number. Otherwise, it will be omitted. recipient_participant_user_id — Will be set to the user’s BSUID or parent BSUID, if you sent the message to the user’s BSUID or parent BSUID. Otherwise, it will be omitted. recipient_participant_parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted. group_participants_update webhooks These changes apply to the group_participants_update webhook. input — New value (BSUID or parent BSUID). Will be set to the user’s phone number if you removed the user from the group using their phone number.Will be set to the user’s BSUID or parent BSUID if you removed the user from the group using their BSUID or parent BSUID. wa_id — New behavior (can be omitted). Will be omitted if the user has enabled the username feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property. Will be set to the user’s BSUID. parent_user_id — New property. Will be set to the user’s parent BSUID if you have enabled parent BSUIDs. Otherwise, it will be omitted. username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. Coexistence History webhooks These changes will apply to history webhooks that describe an onboarded business customer’s WhatsApp Business app chat history. id — New behavior (can be omitted). Will be omitted if, at the time of the history sync request, the user has already enabled usernames and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. context — New context object. wa_id — New property. Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. messages from — New behavior (can be omitted). Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. from_user_id — New property. Will be set to the user’s BSUID. from_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. These changes will apply to history webhooks that describe a media asset sent from a WhatsApp user to a business customer, or vice-versa. contacts — New object. profile username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. wa_id — New property. Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. messages from — New behavior (can be omitted). Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. from_user_id — New property. Will be set to the user’s BSUID. from_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. message_echoes to — New behavior (can be omitted). Will be omitted if, at the time of the sync request, the user has already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. to_user_id — New property. Will be set to the user’s BSUID. to_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. smb_message_echoes webhooks These changes will apply to smb_message_echoes webhooks. contacts — New array. profile username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. wa_id — New property. Will be omitted if, at the time when the business customer used the WhatsApp Business app to send the message to the user, the user had already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. message_echoes to — New behavior (can be omitted). Will be omitted if, at the time when the business customer used the WhatsApp Business app to send the message to the user, the user had already enabled the usernames feature and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. to_user_id — New property. Will be set to the user’s BSUID. to_parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. smb_app_state_sync webhooks These changes will apply to smb_app_state_sync webhooks. phone_number — New behavior (can be omitted). Will be omitted if, at the time of the sync request, the user has already enabled usernames and we are unable to include their phone number based on the conditions described in the Phone numbers section. Otherwise, it will be set to the user’s phone number. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID, if you enabled parent BSUIDs. Otherwise, it will be omitted. username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. Revoke messages webhooks These changes will apply to revoke messages webhooks. contacts profile username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID if you enabled parent BSUIDs. Otherwise, it will be omitted. Edit messages webhooks These changes will apply to edit messages webhooks. contacts profile username — New property. Will be set to the user’s username, if the user has enabled the username feature. Otherwise, it will be omitted. wa_id — New property. Will be omitted if, at the time when WhatsApp user edits the message, the user has already enabled the usernames feature and the phone number cannot be included based on the conditions described in the Phone numbers section. Otherwise, it will be omitted. user_id — New property. Will be set to the user’s BSUID. parent_user_id — Will be set to the user’s parent BSUID if you enabled parent BSUIDs. Otherwise, it will be omitted. Analytics No changes. Billing and invoicing No changes. FAQs What do I need to do to support usernames? BSUIDs and parent BSUIDs will begin appearing in webhooks payloads in March 2026, before usernames are made available to WhatsApp users. In order to process messages from users who enable the feature once it is available, you will need to support BSUIDs (and parent BSUIDs if you enable them). To do this, you must:Update your webhook integrations to support BSUIDs (and parent BSUID, if using).Build logic to support handling multiple identifiers (phone numbers from non-username adopters; BSUIDs from username adopters if phone number is not present in webhooks), and map relevant fields back to your CRM/database.Update internal and external systems related to these integrations to be able to handle BSUIDs and join with previous identifiers; primarily CRM (either 3P or internal database) and any tools or workflows triggered off of CRM (e.g., triggered campaign messages, campaign management, measurement, billing, and so on).If you still require customer phone numbers, update your messaging bots/journeys (if used) to request phone numbers, handle scenarios where users do not share phone numbers, and iterate on these new conversation journeys. See WhatsApp Business Solution Terms⁠ for general restrictions in AI use cases.If you have multiple business portfolios with Meta, you may want to implement a solution to enable central CRM access across multiple portfolios, to minimize the operational overhead that comes with using and storing BSUIDs (and parent BSUIDs). When will I receive a BSUID or parent BSUID vs. a phone number? When a user adopts a username, they will have phone number privacy meaning their phone number will not be displayed in the app, and their phone number will not be included in webhooks. If the user’s phone number is not present (the wa_id property is missing), you can use their BSUID (or parent BSUID, if using), which will be included and assigned to a new user_id property ( parent_user_id for parent BSUIDs). If a user has not adopted usernames, you will receive both their phone number and their BSUID (and parent BSUID, if enabled). Note that will continue to share the phone number if certain conditions are met. Per our Cloud API Terms of Service, however, phone numbers and related data are retained for a maximum of 30 days to support features like message redelivery. There may be situations where you receive messages from existing users outside of this 30 day window, which may look like a new user thread to you. Therefore, it is essential that you begin supporting BSUIDs as soon as possible, to minimize losing any conversation context. Why do partners and directly-integrated businesses using the Cloud API, including directly integrated ads that click to WhatsApp advertisers, have to adopt BSUID? Partners and businesses must adopt BSUID to continue processing incoming messages from WhatsApp username adopters. Once BSUID is adopted and user messages from username adopters are processed, message webhooks will no longer include phone numbers in some cases as part of the webhook such as wa_id, so anyone using the Cloud API must ensure all connected systems can handle BSUID. They will also be able to ask for a user’s phone number in-thread. If I have not yet adopted BSUIDs and start to receive messages from username adopters which I cannot process, recourse is there? If you have not yet adopted BSUID and are not able to process messages from username adopters, there will not be any recourse or corrective action that you can take. For messages from new customers: the webhook will continue to be sent of an incoming message. Depending on the specifics of the implementation, this may impact your systems that are not equipped to handle incoming messages without user phone numbers, and BSUID assigned to the new user_id field. For messages from your existing customers: the phone number will continue to be included if the conditions described in the Phone numbers section are met. Once you support BSUIDs, request phone numbers from users by implementing a phone number request button. How do business usernames differ from display names? When will a user see a business username vs a display name? Business usernames will provide an ability for the users to reach the business by the business’ username, meaning an end user can search for a business username using their exact username and reach out to the businesses. Since end users cannot search by display names, business usernames offer a clear advantage as a searchable and unique identifier for users to reliably find the correct business. Business usernames must follow specific formatting rules on length and allowed characters, while display names have some more leeway in terms of formatting. Business usernames are unique and are tied 1-1 to phone numbers, meaning @JaspersMarket would be tied to one phone number while @JaspersMarketCustomerSupport would be tied to another phone number. Display names are not tied 1-1 to phone numbers, meaning the display name Jasper’s Market can have 10 phone numbers under this display name. When a business has both a username and display name, display name will be shown first (e.g., in Profile, Chat list, Messages, and so on.), for the businesses to build trust with the users and for users to recognize the business when business reaches out to the user. Document changelog March 31, 2026Updated BSUID webhook rollout date from March 31 to early April 2026.Updated contact book limitations: Local Storage businesses now automatically have phone numbers extracted from shared vCards and stored in the contact book on Meta data centers.Updated requesting phone numbers from users: removed the Local Storage exception that required manually sending a message; replaced with automatic vCard phone number extraction behavior.Updated webhook testing instructions with corrected App Dashboard navigation path.Added availability warning to the adopt or change a business username section. March 23, 2026Corrected send message response and send marketing message response user_id descriptions: when both a phone number and BSUID or parent BSUID are included in the request, the response will not include user_id, since the phone number takes precedence and the response is identical to a phone-number-only request. Updated the example response for the phone number and BSUID case accordingly. March 18, 2026Added webhook identifier quick reference tables summarizing which identifiers appear in messages webhooks.Added webhook testing section describing test scenarios available in the App Dashboard.Added user_id_update webhooks section.Added get blocked users response changes to the Block Users API section.Added parent BSUID format description and updated example payloads to use the ENT prefix (e.g., US.ENT.11815799212886844830).Added availability note for the request contact information button (early May 2026).Clarified that the contact book is provided and hosted by Meta with no integration work required, is scoped to the business portfolio level, and only stores interactions that occur after launch.Clarified that user usernames have the same format restrictions as business usernames.Clarified that non-English characters (such as ñ, é, ü) are not supported in business usernames.Clarified that the 30-day lookback conditions in the Phone numbers section are evaluated per business phone number.Removed “You are in the user’s WhatsApp contacts list” from the phone number inclusion conditions. February 18, 2026Clarified that API requests that accept both a phone number and a BSUID or parent BSUID can include both identifiers simultaneously, with the phone number taking precedence. Updated send message requests, send marketing message requests, business-initiated call requests, and block or unblock user requests. February 6, 2026Changed number of alphanumeric characters that compose BSUIDs from 256 to 128 alphanumeric characters.Changed how to use a BSUID to send a message; BSUIDs must now be assigned to dedicated properties/fields in message send requests (instead of existing properties/fields supporting both BSUIDs and phone numbers).Changed how country codes will appear in webhooks: they will be prefixed to user BSUIDs instead of assigned to a dedicated webhook property.Added parent BSUID information, which can be used across linked business portfolios.Added contact book information, which can automatically store user phone numbers and BSUIDs.Added phone number request button information.Changed syntax examples, payload examples, and descriptions for all webhooks that returned empty strings in cases where a user has enabled the usernames feature. Now, these properties will not be set to an empty string. Instead, they will be omitted (e.g, the wa_id property in incoming messages webhooks).Changed how errors are returned when attempting to adopt or change a business username.Removed ability to cancel pending business username requests.Changed phone_number_username_update webhook to business_username_updates webhook. Calling Cloud API Calling | Developer Documentation Cloud API CallingUpdated: Mar 10, 2026 OverviewThe WhatsApp Business Calling API enables you to initiate and receive calls with users on WhatsApp using Voice over Internet Protocol (VoIP). Value proposition (concise)WhatsApp Business Calling: Trusted, Multi-Modal, Feature-Rich Global Connection. Value Description Unified Communication One Number. Message and call. Worldwide. Branding and Trust Branding that is built-in, trusted, and global. Customer Relationship Increase Stickiness. Deepen Personal Touch. Sales and Support Unify Marketing and Support. Unlock Upsell. Rich Features Video, Screen Share, and Full Call Customization. Call Deflection Call in WhatsApp. Improve deflection rates. Customer Convenience Free, Universal Access for your customers. Record Keeping One Thread. Centralized, Long-Term Record. Benefits for end-users Value Description Universal Access Simple, free, and familiar global connection. Enhanced Safety Safer due to built-in platform trust/verification. Centralized History One unified thread for all voice and text history. Voicemail Integrated A voicemail* playable within the chat context.Disclaimer: * Feature planned or in development. Reach out to your Meta or partner for more details Value proposition (detailed)The WhatsApp Business Calling API allows businesses to integrate voice and video* calling directly into their customer engagement strategy, offering a trusted, unified, and feature-rich communication channel. Feature Benefit for Your Business Unified Communication One Number. All Communication. Multi-modal. Use a single, verified WhatsApp number for all messaging and calling (inbound and outbound), enabling a seamless flow between chat and call, and even chatting while on a call. Branding and Trust Branding that is built-in, trusted, and global. WhatsApp has native support for brand identity with security and verification, which provides instant trust globally, eliminating the need for region-specific third-party trust providers. Customer Relationship Increase Stickiness. Deepen Personal Touch. A single point of contact for both inbound and outbound communication enhances personal touch, increases customer stickiness, and ensures lasting customer loyalty. Sales and Support Unify Marketing and Support. Unlock Upsell. Centralize lead management by unifying support and marketing channels, which streamlines operations and unlocks opportunities for product upsell and cross-sell. Rich Features More Than a Call. Get Video, Screen Sharing, and Advanced Control. Beyond voice, businesses can engage customers with video calls and screen sharing for richer, more detailed support and service. Businesses also control the calling experience by configuring calling hours, managing call icon visibility, sending call buttons with expiry, using call deeplinks. Call Deflection Call in WhatsApp. Improve deflection rates. By moving calls to WhatsApp, businesses can seamlessly guide customers to a richer chat experience, leveraging interactive messaging templates to improve deflection and reduce voice-only support costs. Customer Convenience Always Free, Always Universal Access. Offer your customers a convenient and globally accessible communication method that is free for them to use. Record Keeping One Thread. Centralized, Long-Term Record. Maintain a single, persistent thread of all text and voice communications with the customer, serving as a centralized, long-term record for reference.Disclaimer: * Feature planned or in development. Reach out to your Meta or partner for more details Architecture (Right click image and choose “Open in new tab” for enlarged image) Signaling and media possible configurations Default configuration after enabling calling SIP with WebRTC SIP with SDES media Signaling protocol Graph APIs + Webhooks SIP (needs explicit enablement) SIP (needs explicit enablement) Signaling transport HTTPS TLS TLS Media protocol WebRTC (ICE + DTLS1 + SRTP) WebRTC (ICE + DTLS + SRTP) SDES⁠ SRTP (needs explicit enablement) Audio codec2 OPUS OPUS OPUSNotes You can use SDES instead of ICE+DTLS with Graph API + Webhook signalingAdditional audio codecs supported: PCMA, PCMU Get started Step 1: PrerequisitesBefore you get started with the Calling API, ensure that: Your business number is in use with Cloud API (not the WhatsApp Business app)Subscribe your app to the calls webhook field (unless you plan to use SIP)The same app should also be subscribed to the WhatsApp Business Account of your business phone number.This app should have messaging permissions ( whatsapp_business_messaging) for the business numberThe business must have a daily messaging limit of at least 2,000 unique recipients. More details on scaling your account capabilities⁠.Enable Calling features on your business phone number Step 2: Configure optional calling featuresThe WhatsApp Business Calling API offers a number of features that affect when and how calling features appear to users on your WhatsApp profile Inbound call control allows you to prevent users from placing calls from your business profileBusiness call hours allows you to avoid missed calls and direct users to message when your call center is closedCallback requests offer users the option to request a callback when you don’t pick up a call or if your call center is closedLearn more about call control settings Step 3: Make and receive callsYou can test your WhatsApp Calling integration using public test numbers and Sandbox WhatsApp Business Account.Learn more about testing your WhatsApp Calling API integrationCloud API Calling offers two call initiation paths: User-initiated calls: Calls that are made from a WhatsApp user to your businessBusiness-initiated calls: Calls that are made from your business to a WhatsApp user Testing and Sandbox accountsSandbox accounts are only available to Tech Partners.Sandbox accounts and public test numbers enable you to test you WhatsApp Calling API integration with relaxed calling limitations. Specifically business initiated calling limits are relaxed for Sandbox accounts and public test numbers to help integration and testing efforts. Limits (Per business + WhatsApp user pair) Sandbox accounts can send 25 call permissions per day and 100 per week (compared to 1 per day and 2 per week for production accounts)When business-initiated calls go unanswered or are rejected 5 consecutive unanswered calls result in system message to reconsider an approved permission (compared to 2 consecutive unanswered calls for production accounts)10 consecutive unanswered calls result in an approved permission being automatically revoked. (compared to 4 consecutive unanswered calls for production accounts)You obtain a public test number after completing the Get Started flow.Your business is not required to have a daily messaging limit of 2,000 unique recipients to test Calling API features when using public test numbers and Sandbox accounts.Calling is disabled by default on test numbers. You must configure calling features in phone number call settings before using the Calling API on a test number.Learn more about Sandbox Accounts for Calling Availability User-initiated callingUser-initiated calling is available in every location Cloud API is available. Business-initiated callingBusiness-initiated calling is currently available in every location Cloud API is available, except the following countries: USACanadaEgyptVietnamNigeriaNote: The business phone number’s country code must be in this supported list. The consumer phone number can be from any country where Cloud API is available. Next stepsUse the guides below to integrate calling features in your application: Learn how to receive user-initiated callsLearn how to place business-initiated callsLearn how to drive consumer awareness of calling availability in your business ChangelogUse this table as a centralized place to keep track of feature updates related to WhatsApp Business Calling APIs Date Title Description March 23, 2026 Support for G.711 (PCMA, PCMU) audio codec New section for G.711 (PCMA/PCMU) audio codec configuration in call settings, including guidelines on transcoding, audio quality, and bandwidth considerations. Learn more about audio codec settings. January 27, 2026 Calling restrictions based on user feedback are now in effect Learn more about calling restrictions based on user feedback. December 19, 2025 Update in business initiated call limit The number of business-initiated calls per user has been increased to 100 per day from 10 per day.Learn more about business-initiated call limits December 10, 2025 Introduced restrict_to_user_countries for call icon settings Now you can control in which countries the call icon should be visible. Learn more about call icon country settings. October 13, 2025 Update in business initiated call limitAdded “Testing and Sandbox” section to documentation The number of business-initiated calls per user has been increased to 10 per day from 5 per day.Learn more about business-initiated call limitsA Testing and Sandbox accounts has been added to the documentation September 29, 2025 Asterisk integration guide New guide to integrate with Asterisk September 24, 2025 Context propagation from call buttons and deep links Specify an opaque string in call buttons or call deep links to help with tracking the origin of user-initiated calls. Learn more September 8, 2025 Health status API calling update Health Status API is now extended to include a new can_receive_call_sip field to help you self-diagnose issues related to SIP setup September 5, 2025 Introduced new low call pickup calling restrictions Low call pickup rate restrictions are now in effect. Learn more at Calling Restriction for Low Call Pickup Rates July 21, 2025 Account settings update webhooks Get webhooks when settings are updated. Learn more. Configure Call Settings | Developer Documentation Configure Call Settings Updated: Mar 23, 2026 Calling is not enabled by default on a business phone number Use the endpoint to enable Calling API features on a business phone number. Calling Eligibility To qualify for Calling API features, your business must have a messaging limit of at least 2000 business-initiated conversations in a rolling 24-hour period. Learn more about Quality Ratings and Messaging Limits When you test your WhatsApp Calling integration using public test numbers (PTNs) and sandbox accounts, Calling API restrictions are relaxed. Learn more about testing your WhatsApp Calling API integration Overview Use these endpoints to view and configure call settings for the WhatsApp Business Calling API. You can also configure session initiation protocol (SIP) for call signaling instead of using Graph API endpoint calls and webhooks. Configure/Update business phone number calling settings Use this endpoint to update call settings configuration for an individual business phone number. WhatsApp clients reflecting latest calling config After you update call configuration, WhatsApp users may take up to 7 days to reflect those changes. Most users refresh much sooner. You can force an immediate refresh in WhatsApp by entering the chat window with business and open the chat info page. Regardless of WhatsApp client behavior, the semantics of settings are still honored on the server side. Endpoint parameters Placeholder Description Sample Value Integer Required ID of the business phone number for which you are updating Calling API settings. 106540352242922 Calling status When the status parameter is set to “ENABLED”, calling features are enabled for the business phone number. WhatsApp client applications will render the call button icon in both the business chat and business chat profile. When the status parameter is set to “DISABLED”, calling features are disabled, and both the business chat and business chat profile do not display the call button icon. Updates to status will update the call button icon in existing business chats in near real-time when the business phone number is in the WhatsApp user’s contacts. Otherwise, updates are real-time for a limited number of users in conversation with the business, and are eventual for the rest of the conversations. Call button icon visibility When Calling API features are enabled for a business number, you can still choose whether to show the call button icon or not by using the call_icon_visibility parameter. Note: Disabling call button icon visibility does not disable a WhatsApp user’s ability to make unsolicited calls to your business. The behavior for supported options is as follows: DEFAULT The Call button icon will be displayed in the chat menu bar and the business info page, allowing for unsolicited calls to the business by WhatsApp users. DISABLE_ALL The call button icon is hidden in the chat menu bar and the business info page, and all other entry points external to the chat are also disabled. Consumers cannot make unsolicited calls to the business. Your business can still send interactive messages or template messages with a Calling API CTA button. Callback permissions Calling a WhatsApp user requires explicit permission from the user. One way to obtain calling permissions is to request permission when a WhatsApp user calls your business. You can configure the call permission UI to automatically show in the WhatsApp user’s client app when they call your business number. The user may change their permission selection at any time. Call icons With the call_icons setting, you can specify the countries where these icons should show up. Audio codec Opus is the default audio codec for all WhatsApp calls. You can enable G.711 (PCMA/PCMU) codecs for interoperability with legacy telephony systems or PSTN gateways. Guidelines and considerationsOpus is the recommended codec. Opus delivers higher audio quality with lower bandwidth usage and is the default for all WhatsApp calls. Use Opus unless you have a specific requirement for G.711.G.711 requires transcoding. When a G.711 codec is negotiated, audio is transcoded between Opus (on the WhatsApp user side) and G.711 (on the business side), which can add latency to the call.G.711 has lower audio quality. G.711 encodes audio at a fixed 64 kbps without advanced compression, resulting in lower fidelity compared to Opus.G.711 uses more bandwidth. G.711 requires approximately 64 kbps per direction, while Opus achieves comparable or better quality at significantly lower bitrates.Use G.711 only when necessary. The primary use case is interoperability with legacy telephony infrastructure and PSTN gateways that do not support Opus. Error response Possible errors that can occur:Permissions/Authorization errorsInvalid statusInvalid schedule for call_hoursHoliday given in call_hours is a past dateTimezone is invalid in call_hours weekly_operating_hours in call_hours cannot be emptyDate format in holiday_schedule for call_hours is invalidMore than 2 entries not allowed in weekly_operating_hours schedule in call_hoursOverlapping schedule in call_hours is not allowed View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Get phone number calling settings Use this endpoint to check the configuration of your Calling API feature settings. This endpoint can return information for other Cloud API feature settings. Endpoint parameters Parameter Description Sample Value Integer Required ID of the business phone number for which you are getting Calling API settings. 106540352242922 App permission required whatsapp_business_management: Advanced access is required to use the API for end business clients Error response Possible errors that can occur:Permissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Call settings in WhatsApp Manager You can also control your call settings via WhatsApp Manager⁠. To access calling controls in WhatsApp Manager:Click on Account tools > Phone numbers panelClick the gear icon next to the phone number you are using for callingClick the Calls tab Configure and use call signaling via session initiation protocol (SIP) Session Initiation Protocol (SIP) is a signaling protocol used for initiating, maintaining, modifying, and terminating real-time communication sessions between two or more endpoints. You can send and receive call signals using SIP instead of Graph API endpoints. Learn more about how to use and configure SIP Calling restrictions for user feedback If your calls receive a high negative user feedback, such as blocks and reports, business initiated calling, user initiated calling, or both functionalities on your phone number can be restricted. Early warning You will be notified when the business phone number is close to being paused as an early warning. The early warning notifications will be communicated via below channels Email Enforcement emails are sent to the email addresses of all users and admins associated with the business. If you did not receive an email, confirm which email you have designated as the contact email for your app and make sure that it is active, can receive new email, and does not flag the email as junk or spam mail. Pause in calling functionality Once the negative user feedback reaches a threshold, Cloud API will automatically restrict calling functionality on your phone number for a period of 7 days. While paused the calling phone number will be unable toMake business initiated calls to usersSend call permissions requests Once your phone number has been paused, notifications will be communicated via below channels. Note: Any call permissions approved or declined by the users while paused, will still be valid. Email Enforcement emails are sent to the email addresses of all users and admins associated with the business. If you did not receive an email, confirm which email you have designated as the contact email for your app and make sure that it is active, can receive new email, and does not flag the email as junk or spam mail. Pause in user initiated calling functionality Once the negative user feedback reaches a threshold, Cloud API will automatically restrict user initiated calling functionality on your phone number for a period of 7 days. While paused the calling phone number will be unable toReceive calls from usersHave call icon visible Once your phone number has been paused, notifications will be communicated via below channels. Email Enforcement emails are sent to the email addresses of all users and admins associated with the business. If you did not receive an email, confirm which email you have designated as the contact email for your app and make sure that it is active, can receive new email, and does not flag the email as junk or spam mail. Calling restrictions for low call pickup rates When calling is enabled on your business phone number, you are expected to pick up calls that users place to you. If a significant number of calls placed to your calling-enabled business phone number are not picked up, you will be notified and expected to make a change. What happens if you do not pick up callsWarning via Email: You receive an email notification with options to change how you handle incoming calls.Calling becomes restricted on the business phone number: The calling button will be hidden from users. How to mitigate the situation If you receive a warning Continue allowing users to call: Please identify and address the cause of calls not being picked up and make sure you are properly resourced to handle expected call volumes.Hide call buttons for user-initiated calls: You can do so either by working with your partner or going to WhatsApp Manager⁠ > Account tools > Phone numbers > select Phone number [WA phone number] > Calls > toggle off Display call buttons.Turn off calling altogether: You can do so either by working with your partner or going to WhatsApp Manager⁠ > Account tools > Phone numbers > select Phone number [WA phone number] > Calls > toggle off Allow voice calls. If the call button is hidden for the business phone number Re-display calling buttons: Please identify and address the cause of calls not being picked up and make sure you are properly resourced to handle expected call volumes.Next, display the calling buttons by either working with your partner or going to WhatsApp Manager⁠ > Account tools > Phone numbers > select Phone number [WA phone number] > Calls > toggle on Display call buttons.Turn off calling altogether: You can do so either by working with your partner or going to WhatsApp Manager⁠ > Account tools > Phone numbers > select Phone number [WA phone number] > Calls > toggle off Allow voice calls. Business-Initiated Calls | Developer Documentation Business-Initiated Calls Updated: Nov 13, 2025 Overview The Calling API supports making calls to WhatsApp users from your business. The user dictates when calls can be received by granting call permissions to the business phone number. Call sequence diagram Note: The ACCEPTED call status webhook will typically arrive after the call has been established. The Cloud API primarily sends it for call event auditing. Prerequisites Before you get started with business-initiated calling, ensure that:Subscribe to the “calls” webhook fieldCalling APIs are enabled on your business phone number Lastly, before you can call a WhatsApp user, you must obtain their permission to do so. Learn how to obtain WhatsApp user calling permissions here Business-initiated calling flow Part 1: Obtain permission to call the WhatsApp user You can obtain call permissions from the WhatsApp user in one of the following ways: Send a call permission request message You can request call permissions by sending the WhatsApp user a permission request. Send it as a free form message during an open customer service window, or use a template message.Learn how to send a free form call permission requestLearn how to send a template call permission request Enable callback_permission_status in call settings When callback_permission_status is enabled, the user automatically provides call permission to your business when they place a call to you. Learn how to enable callback_permission_status WhatsApp user grants permanent permissions The user can also grant permanent permissions to the business at any time through their business profile. Part 2: Your business initiates a new call to the WhatsApp user Now that you have user permission, you can initiate a new call to the WhatsApp user in question. If there are no errors, you will receive a successful response: Note: Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user. Part 3: You establish the call connection using webhook signaling After you successfully initiate a new call, you receive a Call Connect webhook response containing an SDP Answer from Cloud API. Your business will then apply the SDP Answer from this webhook to your WebRTC stack to initiate the media connection. You then receive an appropriate status webhook, indicating that the call is RINGING, ACCEPTED, or REJECTED: Endpoints for business-initiated calling Initiate call Use this endpoint to initiate a call to a WhatsApp user by providing a phone number and a WebRTC call offer. There is a rate limit of 10000 per 24 hours for initiating new calls per business phone number. Body parameters Error response Possible errors that can occur:Invalid phone-number-idPermissions/Authorization errorsRequest format validation errors, for example connection info, sdp, iceSDP validation errorsCalling restriction errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Terminate call Use this endpoint to terminate an active call. This must be done even if there is an RTCP BYE packet in the media path. Ending the call this way also ensures pricing is more accurate. When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, you will receive a Call Terminate Webhook. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Required The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “terminate” Error response Possible errors that can occur:Invalid call idInvalid phone-number-idThe WhatsApp user has already terminated the callReject call is already in progressPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Webhooks for business-initiated calling With all Calling API webhooks, there is a ”calls” object inside the ”value” object of the webhook response. The ”calls” object contains metadata about the call that is used to action on each call placed or received by your business. To receive Calling API webhooks, subscribe to the “calls” webhook field. Learn more about Cloud API webhooks here Call status webhook This webhook is sent during the following calling events:Ringing: When the WhatsApp user’s client device begins ringingAccepted: When the WhatsApp user accepts the callRejected: When the WhatsApp user rejects the call. You also receive the call terminate webhook in this case The webhook structure here is similar to the Status webhooks used for the Cloud API messages. Learn more about Cloud API status webhooks Webhook values for "statuses" Placeholder Description id String A unique ID for the call timestamp Integer The UNIX timestamp of the webhook event recipient_id Integer The phone number of the WhatsApp user receiving the call status Integer The current call status. Possible values: RINGING: Business initiated call is ringing the user ACCEPTED: Business initiated call is accepted by the user REJECTED: Business initiated call is rejected by the user biz_opaque_callback_data String Arbitrary string your business passes into the call for tracking and logging purposes. Will only be returned if provided through Initiate New Call API requests Call terminate webhook A webhook notification is sent whenever the call has been terminated for any reason, such as when the WhatsApp user hangs up, or when the business calls the endpoint with an action of terminate or reject. Webhook values for "calls" Placeholder Description id String A unique ID for the call to Integer The number being called (callee) from Integer The number of the caller event Integer The calling event that this webhook is notifying the subscriber of timestamp Integer The UNIX timestamp of the webhook event direction String The direction of the call being made. Can contain either: BUSINESS_INITIATED, for calls initiated by your business. USER_INITIATED, for calls initiated by a WhatsApp user. start_time Integer The UNIX timestamp of when the call started. Only present when the call was picked up by the other party. end_time Integer The UNIX timestamp of when the call ended. Only present when the call was picked up by the other party. duration Integer Duration of the call in seconds. Only present when the call was picked up by the other party. biz_opaque_callback_data String Arbitrary string your business passes into the call for tracking and logging purposes. Will only be returned if provided through an Initiate Call API request or Accept Call request errors.code Integer The errors object is present only for failed calls when there is error information available. Code is one of the calling error codes SDP overview and sample structures Session Description Protocol (SDP) is a text-based format used to describe the characteristics of multimedia sessions, such as voice and video calls, in real-time communication applications. SDP provides a standardized way to describe the session’s media streams. This includes media type, codecs, protocols, and parameters for establishing and managing the session. In the context of WebRTC, SDP is used to negotiate the media parameters between the sender and receiver, enabling them to agree on the specifics of the media exchange. View SDP sample structures for business-initiated calls Obtain User Call Permissions | Developer Documentation Obtain User Call Permissions Updated: Nov 13, 2025 As of November 3, 2025, permanent permissions is now available. Users can now grant a business ongoing permission to call. Users can review and change calling permission for a business at any time in the business profile. Call permission related features are available only in regions where business initiated calling is available. Overview If you want to place a call to a WhatsApp user, your business must receive user permission first. When a WhatsApp user grants call permissions, they can be either temporary or permanent. Business does not have control over this permission as it is only granted by the user and can only be revoked by the user, at any time. Permanent permission data will be stored until it is revoked. You can obtain calling permission from a WhatsApp user in any of the following ways:Send a call permission request to the user — Send a free-form or templated message requesting calling permission from the user. User has the option to choose between temporary or permanent.Callback permission is provided by the WhatsApp user — The WhatsApp user automatically provides temporary call permissions by placing a call to the business. The callback setting must be enabled on the business phone number.WhatsApp user provides call permission via Business Profile — The WhatsApp user provides call permissions to the business through their business profile. Limits (Per business + WhatsApp user pair)Temporary permissions are granted for 7 calendar days (168 hours) Calculated as the number of seconds in a day multiplied by 7, from time of user’s approval.Permanent permissions do not expire, but they have the same connected calls limit.Your business can make a maximum of 100 connected calls every 24 hoursThese limits are on the business phone number These limits are in place to protect WhatsApp users from unwanted calls. When you test your WhatsApp Calling integration using public test numbers (PTNs) and sandbox accounts, Calling API restrictions are relaxed. Learn more about testing your WhatsApp Calling API integration Call permission request basics You may proactively request a calling permission from a WhatsApp user by sending a permission request message, either as a:Free form interactive messageTemplate message The WhatsApp user may approve (temporary or permanent), decline, or simply not respond to a call permission request. With permissions, the WhatsApp user is in control. Even if the user provides calling permission, they can revoke that granted permission request at any time. Conversely, if the user declines a permission request, they can still grant calling permission, up until the permission request expires. A call permission request expires when any of the following occurs:The WhatsApp user interacts with a subsequent new call permission request from the business7 days after the permission was accepted or declined by the consumer7 days after the permission was delivered if the consumer does not respond to the request View client UI behavior for expired permission requests To ensure an optimal user experience around business initiated calling, the following limits are enforced:When sending a calling permission request message Maximum of 1 permission request in 24hMaximum 2 permission requests within 7 days. These limits reset when any connected call (business-initiated/user-initiated) is made between the business and WhatsApp user.These limits apply toward permissions requests sent either as free form or template messages.When business-initiated calls go unanswered or are rejected 2 consecutive unanswered calls result in a system message to reconsider an approved permission4 consecutive unanswered calls result in an approved permission being automatically revoked. The user may again update this if they so choose. View client UI behavior for consecutive unanswered calls Free form vs template call permission request message Call permission request messages are subject to messaging charges A call permission request message can be sent to users in one of the following ways: Send a free form messageWhen you are within a customer service window with a WhatsApp user, you can send a free form message with a call permission request.Although a text body will be optional, you should send one to build context with the user. In the case of free form calling permission request messages, header and footer sections are not supported.Since the customer service window is open, there is no need to create a conversation window. Create and send a template messageSending a template message allows you to initiate a user conversation with a call permission request.Context (that is, a text body) is required when sending a template message with a call permission request.With template messages, you can further customize your permission request by adding a message header and footer. Client application UI experience Call permission request flow and sample messages Allow calls Temporarily allow calls Template message With header, footer and body With body only With no text body Free form message types With no text body With text body only Updating call permission on business profile Users always have the option to change the permission using a new option on the business profile. Update call permission on business profile Consecutive unanswered calls Consecutive unanswered calls 2 consecutive unanswered calls — System message for user to update permission 4 consecutive unanswered calls — Permissions automatically revoked Call permission request expiration scenarios Permission request expires after 7 days — User interacts with request Permission request expires after 7 days — User does not interact Previous permission request expires immediately — User does not interact / New call permission request is received Previous permission request expires immediately — User allows / Interacts with the new request Send free form call permission request message Call permission request messages are subject to messaging charges Use this endpoint to send a free form interactive message with a call permission request during a customer service window. A standard message status webhook will be sent in response to this message send. Note: The call permission request interactive object cannot be edited by the business. Only the message body can be customized. See how this message is rendered on the WhatsApp client Body parameters Parameter Description Sample Value to Integer Required The phone number of the WhatsApp user you are messaging Learn more about formatting phone numbers in Cloud API +17863476655 type String Required The type of interactive message you are sending. In this case, you are sending a call_permission_request. Learn more about interactive messages “call_permission_request” action String Required The action of your interactive message. Must be call_permission_request. “call_permission_request” body String Optional The body of your message. Although this field is optional, it is highly recommended you give context to the WhatsApp user when you request permission to call them. "Allow us to call you so we can support you with your order." Success response Learn more about messaging success responses Error response Possible errors that can occur:Invalid phone-number-idPermissions/Authorization errorsRate limit reachedSending this message to users on older app versions will result in error webhook with error code 131026Calling not enabledCalling restriction errors View general Cloud API Error Codes here Create and send call permission request template messages Call permission request messages are subject to messaging charges Use these endpoints to create and send a call permission request message template. Once your permission request template message is created, your business can send the template message to the user as a call permission request outside of a customer service window. Learn more about creating and managing message templates Create message template Use this endpoint to create a call permission request message template. Body parameters Creating and managing template messages can be done both through Cloud API and the WhatsApp Business Manager interface. When creating your call permission request template, ensure you configure type as call_permission_request. Learn more about creating and managing message templates Parameter Description Sample Value type String Required The type of template message you are creating. In this case, you are creating a call_permission_request. “call_permission_request” Template status response Learn more about template status response Error response Possible errors that can occur:Invalid WABA idPermissions/Authorization errorsTemplate structure/component validation alerts View general Cloud API Error Codes here Get current call permission state Use this endpoint to get the call permission state for a business phone number with a single WhatsApp user phone number. Request parameters Parameter Description Sample Value String Required The business phone number you are fetching permissions against. Learn more about formatting phone numbers in Cloud API +18762639988 Integer Required The phone number of the WhatsApp user who you are requesting call permissions from. Learn more about formatting phone numbers in Cloud API +13057765456 Error response Possible errors that can occur:Invalid phone-number-idIf the consumer phone number is uncallable, the api response will be no_permission.Permissions/Authorization errors.Rate limit reached. A maximum of 100 requests in a 1 second window can be made to the API.Calling is not enabled for the business phone number. View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here User call permission reply webhook This webhook is delivered whenever a user selects or updates their calling permissions. It could be in response to a call permission request sent by the business or it could be the user proactively making a decision. The webhook fields values change depending on the circumstances of the user permission decision:the user accepts or rejects the requestthe user approves permission by responding to a request or by calling the businessthe user permission is an automatic callback permission in response to a user-initiated callthe user permission is automatically revoked in response to 4 consecutive unanswered business-initiated calls Lastly, the user can grant permanent calling permission to the business, which is represented in the is_permanent parameter. No webhook is sent when a temporary permission expires. The expiration_timestamp field included in the accepted permission webhook indicates the time this permission will expire. Alternatively the current permission state can be queried from the get current call permission state endpoint. Webhook sample Webhook values Placeholder Description customer_phone_number String The phone number of the customer context.id String Can be either of two valuesMessage ID of the permission request message sent by the business to the customer number. Shows when a permission decision is made by the user in response to a call permission request.Call ID of the missed call placed by the business to the customer number. Shows when callback permission is enabled in settings and the user calls the business. response String The WhatsApp users response to the call permission request message Can be accept or reject is_permanent Boolean Indicates if the permission is permanent or not. For temporary permission this will always be false. expiration_timestamp Integer Time in seconds when this call permission expires if the WhatsApp user approved it response_source String The source of this permission Possible values for accepted call permissions are: user_action: User approved or rejected the permission automatic: An automatic permission approval due to the WhatsApp user initiating the call Webhook sample scenarios Scenario Webhook sample The WhatsApp user approves a temporary call permission from a call permission request message The WhatsApp users approves a permanent call permission from a call permission request message The WhatsApp users approves a permanent call permission from the business profile The WhatsApp users rejects a call permission after receiving a call permission request message An automatic temporary callback permission is granted to the business when the WhatsApp user calls the business A call permission is automatically revoked when a business makes 4 consecutive unanswered calls to the WhatsApp user User-initiated calls | Developer Documentation User-initiated calls Updated: Nov 13, 2025 Overview The Calling API supports receiving calls made by WhatsApp users to your business. Your business dictates when calls can be received by configuring business calling hours and holiday unavailability. Consumer device eligibility Currently, the WhatsApp Business Calling API can accept calls from a consumer’s primary and companion iPhone or Android phones. A primary device is the consumer’s main device, typically a mobile phone, which holds the authoritative state for the user’s account. It has full access to messaging history and core functionalities. There is exactly one primary device per user account at any given time. Companion devices are additional devices registered to the user’s account that can operate alongside the primary device. Examples include web clients, desktop apps, tablets, and smart glasses. Companion devices have access to some or all messaging history and core features but are limited compared to the primary device. For Cloud API Calling, only iPhone and Android phone companion devices are supported for user-initiated calls. Callback permission functionality on companion devices For businesses that have the callback setting enabled, this functionality is not supported on companion devices yet. Prerequisites Before you get started with user-initiated calling, ensure that:Subscribe to the calls webhook fieldEnable Calling API features on your business phone number Call sequence diagram Endpoints for user-initiated calling Pre-accept call When you pre-accept an inbound call, you allow the calling media connection to be established before attempting to send call media through the connection. When you then call the accept call endpoint, media begins flowing immediately since the connection has already been established. Pre-accepting calls is recommended because it facilitates faster connection times and avoids audio clipping issues. There is about 30 to 60 seconds after the Call Connect webhook is sent for the business to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Note: Since the WebRTC connection is established before calling the Accept Call endpoint, make sure to flow the call media only after you receive a 200 OK response back. If call media flows too early, the caller will miss the first few words of the call. If call media flows too late, callers will hear silence. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Optional The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “pre_accept” session JSON object Optional Contains the session description protocol (SDP) type and description language. Requires two values: sdp_type — (String) Required “offer”, to indicate SDP offer sdp — (String) Required The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866⁠. Learn more about Session Description Protocol (SDP)⁠ View example SDP structures Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, SDP or ICEAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Accept call Use this endpoint to connect to a call by providing a call agent’s SDP. You have about 30 to 60 seconds after the Call Connect Webhook is sent to accept the phone call. If your business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Body parameters Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, SDP or ICEAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errorsSDP answer provided in accept does not match the SDP answer given in the Pre-Accept endpoint for the same call-id View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Reject call Use this endpoint to reject a call. You have about 30 to 60 seconds after the Call Connect webhook is sent to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Optional The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “reject” Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Terminate call Use this endpoint to terminate an active call. This must be done even if there is an RTCP BYE packet in the media path. Ending the call this way also ensures pricing is more accurate. When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, a Call Terminate Webhook will be sent to you. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Optional The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “terminate” Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idAccept/Reject an already In Progress/Completed/Failed callReject call is already in progressPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Webhooks for user-initiated calling With all Calling API webhooks, there is a ”calls” object inside the ”value” object of the webhook response. The ”calls” object contains metadata about the call that is used to action on each call received by your business. To receive Calling API webhooks, subscribe to the calls webhook field. Learn more about Cloud API webhooks here Call Terminate webhook A webhook notification is sent whenever the call has been terminated for any reason, such as when the WhatsApp user hangs up, or when the business calls the endpoint with an action of terminate or reject. Webhook values for "calls" Placeholder Description id String A unique ID for the call to Integer The number being called (callee) from Integer The number of the caller event Integer The calling event that this webhook is notifying the subscriber of timestamp Integer The UNIX timestamp of the webhook event direction String The direction of the call being made. Can contain either: BUSINESS_INITIATED, for calls initiated by your business. USER_INITIATED, for calls initiated by a WhatsApp user. deeplink_payload String Arbitrary string specified in biz_payload query param on a call deeplink. Will only be returned if call was initiated from a deeplink with such param. See Call Button Messages and Deep Links for more details. cta_payload String Arbitrary string specified in payload field on a call button. Will only be returned if call was initiated from a call button with payload. See Call Button Messages and Deep Links for more details. start_time Integer The UNIX timestamp of when the call started. Only present when the call was picked up by the other party. end_time Integer The UNIX timestamp of when the call ended. Only present when the call was picked up by the other party. duration Integer Duration of the call in seconds. Only present when the call was picked up by the other party. biz_opaque_callback_date String Arbitrary string your business passes into the call for tracking and logging purposes. Will only be returned if provided through an Initiate Call request or Accept Call request errors.code Integer The errors object is present only for failed calls when there is error information available. Code is one of the calling error codes Dual tone multi frequency (DTMF) support The dialpad provided by the Calling API only supports DTMF use cases. It does not support consumer-to-consumer calls and does not change any other calling behaviors. For example, the dialpad cannot be used to dial a number and initiate a call or message on WhatsApp. WhatsApp Business Calling API supports DTMF tones, with the intention to enable BSP applications to support IVR-based systems. WhatsApp users can press tone buttons on their client app and these DTMF tones are injected into the WebRTC RTP stream established as a part of the VoIP connection. Our WebRTC stream conforms to RFC 4733⁠ for the transfer of DTMF Digits via RTP Payload. There is no webhook for conveying DTMF digits. DTMF clock rate Only 8000 clock rate is supported in our SDPs. For user-initiated calls, our SDP offer includes only 8000 clock rate. For business-initiated calls, your SDP offer should have 8000 clock rate. Even if it is absent, the API still proceeds with 8000 clock rate against payload type 126. The RTP packets representing DTMF events will use the same timestamp base and sequence number base as the regular audio packets. So you don’t have to worry about differing clock rates between audio packets and DTMF packets. The duration field⁠ of the DTMF packet is calculated using 8000 clock units. The API does not support 48000 clock rate for DTMF. Sending DTMF digits on consumer WhatsApp client WhatsApp client applications are enhanced to have a dialpad for calls with CloudAPI business phone numbers. The WhatsApp user can press the buttons on the dialpad and send DTMF tones. SDP overview and sample SDP structures Session Description Protocol (SDP) is a text-based format used to describe the characteristics of multimedia sessions, such as voice and video calls, in real-time communication applications. SDP provides a standardized way to convey information about the session’s media streams, including the type of media, codecs, protocols, and other parameters necessary for establishing and managing the session. In the context of WebRTC, SDP is used to negotiate the media parameters between the sender and receiver, enabling them to agree on the specifics of the media exchange. View SDP sample structures for user-initiated calls SIP Configuration Guide - WhatsApp Business Calling | Developer Documentation SIP Configuration Guide - WhatsApp Business Calling Updated: Dec 15, 2025 When SIP is enabled, you cannot use calling related Graph API endpoints and calling related webhooks are not sent. Overview Session Initiation Protocol (SIP⁠) is a signaling protocol used for initiating, maintaining, modifying, and terminating real-time communication sessions between two or more endpoints. WhatsApp Business Calling API supports use of SIP as the signaling protocol instead of our Graph API endpoints and Webhooks. Before you get started Before you get started with SIP call signaling, confirm the following:You meet overall calling pre-requisitesYour app has messaging permissions for the business phone number you want to enable SIP for. Test this by sending and receiving messages using Graph API messaging endpoints, then use the same app to configure your SIP server on the business phone number for calling.Double confirm this by using health status API with PHONE_NUMBER_IDYour app mode is “Live”, not “Development”.You have a standards compliant third party SIP server that supports TLS transport and digest authentication See Signaling and media possible configurations for more info Calling flows using SIP Before you start, make sure you have enabled and configured SIP on the business phone number. Meta generates a unique SIP user password for each business phone number + app combination. You will need this information and can retrieve it by using the get Call Settings endpoint. SecurityTLS transport is mandatory for SIP. Meta will present a valid server cert with subject name that covers our SIP domain wa.meta.vc. Your SIP server should do the same as Meta ensures your cert is valid and subject name covers SIP domain you configured on the business phone number Meta does NOT support mutual TLS (aka mTLS). This means, when Meta takes the role of a TLS client, your TLS server should not request Client certificate. If you still request client cert, Meta will present a client cert but the cert subject name would refer to a random dynamic host which will not pass certificate validation.Meta adds transport=TLS to request URI as part of its SIP requests to your SIP serverFor business initiated calls, SIP invite from your SIP server will be challenged using digest auth. See business-initiated calls for more detailsFor user initiated calls, it is highly recommended that you challenge SIP INVITE request from Meta, to use digest auth for more security. See user-initiated calls for more details How to test if you have a valid TLS certificate When a WhatsApp user calls a business, a common reason for your SIP server to not receive the SIP INVITE from Meta is the certificate validation error. You can use information here to confirm valid setup. Run the command openssl s_client -quiet -verify_hostname {hostname} -connect {hostname}:{port} by properly substituting hostname and port with your values Example of valid server cert $ openssl s_client -quiet -verify_hostname meta-voip.example.com -connect meta-voip.example.com:5061Connecting to 64:ff9b::68f8:b0b8 depth=2 C=US, ST=NewJersey, L=JerseyCity, O=The USERTRUST Network, CN=USERTrust RSA CertificationAuthority verify return:1 depth=1 C=AT, O=ZeroSSL, CN=ZeroSSL RSA DomainSecureSite CA verify return:1 depth=0 CN=example.com verify return:1 Example of hostname:port not listening on TLS openssl s_client -quiet -verify_hostname lb01.voice.usw2.pure.cloud -connect lb01.voice.usw2.pure.cloud:5060Connecting to 34.211.206.63009F0DFB01000000:error:0A000126:SSL routines::unexpected eof while reading:ssl/record/rec_layer_s3.c:693: Example of invalid cert $ openssl s_client -quiet -verify_hostname meta-inb.byoc.mypurecloud.com -connect meta-inb.byoc.mypurecloud.com:5061Connecting to 64:ff9b::3652:f1c0 depth=0 jurisdictionC=US, jurisdictionST=California, businessCategory=PrivateOrganization, serialNumber=1515861, C=US, ST=Indiana, L=Indianapolis, O=GenesysCloudServices,Inc., CN=voice.mypurecloud.com verify error:num=62:hostname mismatch verify return:1 depth=2 C=US, O=DigiCertInc, OU=www.digicert.com, CN=DigiCertHighAssurance EV Root CA verify return:1 depth=1 C=US, O=DigiCertInc, OU=www.digicert.com, CN=DigiCert SHA2 ExtendedValidationServer CA verify return:1 depth=0 jurisdictionC=US, jurisdictionST=California, businessCategory=PrivateOrganization, serialNumber=1515861, C=US, ST=Indiana, L=Indianapolis, O=GenesysCloudServices,Inc., CN=voice.mypurecloud.com verify return:1 In this case, you can alter the certificate to match your hostname or change your configured SIP server hostname to match your certificate Business-initiated calls PrerequisitesYou have the required call permission approval from the WhatsApp user Learn how to obtain user calling permissionsRetrieve Meta generated SIP password and configure it on your SIP server, so it can respond to digest authentication challenge from Meta SIP servers Calling flowSend an initial SIP INVITE to our servers. Our SIP domain is wa.meta.vc. To initiate a call to WhatsApp user with phone number 11234567890, the SIP request URI should be ‘sip:+11234567890@wa.meta.vc;transport=tls’ This request will fail with an “SIP 407 Proxy Authentication required” message.Send a 2nd SIP INVITE with proper Authorization header as per RFC 3261⁠. The Authorization field’s username attribute must match the from header’s user name which is the business phone numberThe password is generated by Meta and you can retrieve it using get Call Settings endpointThe username portion of the from header must be the fully normalized business phone numberThe domain name of the from header must match the SIP server you configured on the business phone numberThe SDP Offer you include supports ICE, DTLS-SRTP and OPUS (essentially WebRTC media)Send the SIP INVITE to the WhatsApp user number you want to call. User-initiated calls PrerequisitesIf you plan to use SIP Digest Auth, retrieve Meta generated SIP password and configure it on your SIP server, so it can respond to digest authentication challenge from Meta SIP servers Calling flowThe WhatsApp user calls business phone number and is unaware of whether the business is using SIP or Graph API. In other words, the user experience is identicalIf the business phone number is SIP enabled, Meta will send an SIP INVITE to the SIP server configured on the business phone numberYou respond with SIP digest auth challenge (recommended) or SIP OK and pass in an SDP answer If you are not receiving SIP INVITE from Meta, refer to SIP specific FAQ to troubleshoot further View sample SIP requests Learn more about Session Description Protocol (SDP)⁠ View example SDP structures Custom SIP headers The following custom SIP headers are common to both business and user initiated calls Header name Metadata Description x-wa-meta-call-duration Optional; String Call duration in seconds. This is present on SIP BYE requests from Meta for termination of an established call. x-wa-meta-wacid Optional; String WhatsApp call ID. This is present on SIP INVITE request from Meta for a user-initiated call and SIP BYE requests from Meta for termination of an established call. The following custom SIP headers are specific to user-initiated calls Header name Metadata Description x-wa-meta-cta-payload Optional; String Present when user-initiates a call from call button that has business specified payload. Learn more x-wa-meta-deeplink-payload Optional; String Present when user-initiates a call from call deeplink that has business specified payload. Learn more Configure or update SIP settings on business phone number Use this endpoint to update call settings configuration for an individual business phone number. Endpoint parameters Placeholder Description Sample Value Integer Required The business phone number for which you are updating Calling API settings. Learn more about formatting phone numbers in Cloud API +12784358810 Body parameters Parameter Description status String Optional Enable or disable SIP call signaling for the given business phone number. Default is DISABLED. When status is ENABLED, this phone number will exclusively use SIP for call signaling and will not work with Graph APIs. No webhooks are sent. When status is set to DISABLED, the SIP servers values are not reset. If you enable SIP on the same phone number again, the previously configured servers values will take effect. You can configure both status and SIP servers in the same request servers String Optional The SIP server routing configuration. Each phone number can have only one SIP server configured. The servers is an array to be futureproof. Previously we allowed multiple apps each with their own SIP server but this setup will not work because Meta will terminate the call after receiving BYE from any of the SIP servers. In the GET payload, if you see multiple SIP servers, it means you’ve used the POST API with different access tokens that belong to different apps. The associated app is extracted from the access token used to make the API call. To delete a previously configured SIP server, pass an empty array to this field. If you still see some servers remaining after you clear, those servers may belong to different apps, so you need to use the corresponding access tokens to clear them. Note that at-least 1 SIP server of any app must exist when SIP status is ENABLED. To clear servers for all applications being used with a business phone number, the SIP status should be DISABLED. hostname — (String) Required The host name of the SIP server. Requests must use TLS. port — (String) Required The port within your SIP server that will accept requests. Requests must use TLS. Default port is 5061 request_uri_user_params — (String) Optional An optional field for passing any parameters you want included in the user portion of the request URI used in our SIP INVITE to your SIP server. Max key/value size is 128 characters. An example use case would be Trunk Groups (RFC 4904⁠)sip:+1234567890@sip.example.comtgrp=wacalltrunk-context=byoc.example.com This example has two user parameters for tgrp, and trunk-context. The effective SIP request URI line for this would be sip:+1234567890;tgrp=wacall;trunk-context=byoc.example.com@sip.example.com Error response View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Get phone number calling settings (SIP) Use this endpoint to check the configuration of your Calling API feature settings, including SIP values. This endpoint can return information for other Cloud API feature settings. Endpoint parameters Placeholder Description Sample Value Integer Required The business phone number for which you are retrieving Calling API settings. Learn more about formatting phone numbers in Cloud API +12784358810 App permission required whatsapp_business_management: Advanced access is required to update use the API for end business clients Error response View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Sample SIP requests Business-initiated calls (with WebRTC media) Initial SIP INVITE request INVITE sip:+12195550714@wa.meta.vc;transport=tls SIP/2.0Record-Route:Via: SIP/2.0/TLS 159.65.244.171:5061;received=2803:6081:798c:93f8:5f9b:bfe8:300:0;branch=z9hG4bK0da2.36614b8977461b486ceabc004c723476.0;i=617261Via: SIP/2.0/TLS 137.184.87.1:35181;rport=56533;received=137.184.87.1;branch=z9hG4bKQNa6meey5Dj2g Max-Forwards:69From:;tag=Kc9QZg4496maQTo:Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba CSeq:96743476 INVITE Contact:User-Agent:SignalWireAllow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY Supported: timer, path, replaces Allow-Events: talk, hold, conference, refer Session-Expires:600;refresher=uac Min-SE:90Content-Type: application/sdp Content-Disposition: session Content-Length:2427 X-Relay-Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba Remote-Party-ID:;party=calling;screen=yes;privacy=off Content-Type: application/sdp Content-Length:2427<> 407 response from Meta SIP/2.0407ProxyAuthenticationRequiredVia: SIP/2.0/TLS 159.65.244.171:5061;received=2803:6081:798c:93f8:5f9b:bfe8:300:0;branch=z9hG4bK0da2.36614b8977461b486ceabc004c723476.0;i=617261Via: SIP/2.0/TLS 137.184.87.1:35181;rport=56533;received=137.184.87.1;branch=z9hG4bKQNa6meey5Dj2g Record-Route:Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba From:;tag=Kc9QZg4496maQTo:;tag=z9hG4bK0da2.36614b8977461b486ceabc004c723476.0CSeq:96743476 INVITE Proxy-Authenticate:Digest realm="wa.meta.vc",nonce="419ac2415577f8e1",opaque="440badfc05072367",algorithm=MD5,qop="auth" Second SIP INVITE sent with authorization INVITE sip:+12195550714@wa.meta.vc;transport=tls SIP/2.0Record-Route:Via: SIP/2.0/TLS 159.65.244.171:5061;received=2803:6081:798c:93f8:5f9b:bfe8:300:0;branch=z9hG4bK1da2.ed8900012befced853927008d619d374.0;i=617261Via: SIP/2.0/TLS 137.184.87.1:35181;rport=56533;received=137.184.87.1;branch=z9hG4bKry3yp9y12p8mc Max-Forwards:69From:;tag=Kc9QZg4496maQTo:Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba CSeq:96743477 INVITE Contact:User-Agent:SignalWireAllow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY Supported: timer, path, replaces Allow-Events: talk, hold, conference, refer Proxy-Authorization:Digest username="17125550259", realm="wa.meta.vc", nonce="419ac2415577f8e1", uri="sip:+12195550714@wa.meta.vc;transport=tls", response="blah", algorithm=MD5, cnonce="/mVZtYFCEj65YQJCrBEAAg", opaque="440badfc05072367", qop=auth, nc=00000001Session-Expires:600;refresher=uac Min-SE:90Content-Type: application/sdp Content-Disposition: session Content-Length:2427 X-Relay-Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba Remote-Party-ID:;party=calling;screen=yes;privacy=off Content-Type: application/sdp Content-Length:2427<> Example error response SIP/2.0403 SIP server wa.meta.vc from INVITE does not match any SIP server configured for phone number id {ID}Via: SIP/2.0/TLS [2803:6080:c954:b533:ecfb:5cec:300:0]:39459;rport=39459;received=2803:6080:c954:b533:ecfb:5cec:300:0;branch=z9hG4bKPjf9f3d0bddb3dbe0c9b1e3b486f39784a;aliasVia: SIP/2.0/TLS 148.72.155.236:5061;rport=30498;received=2803:6080:d014:8e40:ddbb:4ed7:300:0;branch=z9hG4bKPjfd270ec8-7aaf-4a65-b290-4bef3b50b7b7;aliasRecord-Route:Record-Route:Call-ID:91578781-44f1-4268-9a7f-d7efec1abf72 From:;tag=3a63b370-a697-4a5a-82b4-e8105e23f176 To:;tag=e0d30a05-657b-47ec-a668-e05ca79f9f05 CSeq:15659 INVITE Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS X-FB-External-Domain: wa.meta.vc Warning:399 wa.meta.vc "SIP server wa.meta.vc from INVITE does not match any SIP server configured for phone number id {ID}"Content-Length:0Content-Length:0 SIP BYE BYE sip:+5559800000693@wa.meta.vc;transport=tls;ob SIP/2.0Via: SIP/2.0/TLS 137.184.4.155:5061;received=2803:6080:c074:cac:10ed:4b05:400:0;i=8d2dc2Via: SIP/2.0/TLS 143.198.136.243:35181;rport=38087;received=143.198.136.243Route:Route:Max-Forwards:69From:;tag=NcKQ6mtDKSDQBTo:"5559800000693";tag=92a01092-ee78-4870-865f-bc176203a6bd Call-ID: outgoing:wacid.HBgPMjAwNzU2OTA0ODY5OTY1FRIAEhggMjQ4QzUwOUQ1REQ0NDUwNENEQzRFMTgwRTNGQjAwNjEcGAsxMjE0NTU1MTg2ORUCAAACSeq:98734935 BYE User-Agent:SignalWireAllow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY Supported: timer, path, replaces Reason: Q.850;cause=16;text="NORMAL_CLEARING"Content-Length:0 X-Relay-Call-ID: b72c0c65-e319-41b3-afb7-19ebcca05d38Content-Length:0 SIP INVITE (with SDES) INVITE sip:+12195550714@wa.meta.vc;transport=tls SIP/2.0Record-Route:Record-Route:CSeq:2 INVITE From:"12145551869";tag=28460006_c3356d0b_5cdada8c-cbf0-4369-b02d-cc97d3c36f2b To:Max-Forwards:66 P-Asserted-Identity:Min-SE:120Call-ID: f304a1d2cafb8139c1f9ff93a7733586@0.0.0.0Contact:"12145551869"Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY Via: SIP/2.0/TLS 54.172.60.1:5061;received=2803:6080:f934:8894:7eb5:24f9:300:0;branch=z9hG4bK1e5a.0da2ace9cc912d9e5f2595ca4acb9847.0Via: SIP/2.0/UDP 172.25.10.217:5060;rport=5060;branch=z9hG4bK5cdada8c-cbf0-4369-b02d-cc97d3c36f2b_c3356d0b_54-457463274351249162Supported: timer User-Agent:TwilioGatewayProxy-Authorization:Digest username="12145551869", realm="wa.meta.vc", nonce="2a487cb01d4ed43b", uri="sip:+12195550714@wa.meta.vc;transport=tls", response="3f58df7af575b948625aeffd51bf9060", algorithm=MD5, cnonce="b338deb7f0e004e66353e26d34ad62b7", opaque="725a06fb2cd89a32", qop=auth, nc=00000002Content-Type: application/sdp X-Twilio-CallSid: CA93eac6be615da5e6836c7059e9555348 Content-Length:422Content-Type: application/sdp Content-Length:422 v=0 o=root 11854148721185414872 IN IP4 172.18.155.180 s=TwilioMediaGateway c=IN IP4 168.86.138.232 t=00 m=audio 19534 RTP/SAVP 10708101 a=crypto:************************************************************************** a=rtpmap:0 PCMU/8000 a=rtpmap:107 opus/48000/2 a=fmtp:107 useinbandfec=1 a=rtpmap:8 PCMA/8000 a=rtpmap:101 telephone-event/8000 a=fmtp:1010-16 a=ptime:20 a=maxptime:20 a=sendrecv SIP OK (with SDES) SIP/2.0200 OK Via: SIP/2.0/TLS 54.172.60.1:5061;received=2803:6080:f934:8894:7eb5:24f9:300:0;branch=z9hG4bK1e5a.0da2ace9cc912d9e5f2595ca4acb9847.0Via: SIP/2.0/UDP 172.25.10.217:5060;rport=5060;branch=z9hG4bK5cdada8c-cbf0-4369-b02d-cc97d3c36f2b_c3356d0b_54-457463274351249162Record-Route:Record-Route:Record-Route:Record-Route:Call-ID: f304a1d2cafb8139c1f9ff93a7733586@0.0.0.0From:"12145551869";tag=28460006_c3356d0b_5cdada8c-cbf0-4369-b02d-cc97d3c36f2b To:;tag=0d185053-2615-46c7-8ff2-250bda494cf1CSeq:2 INVITE Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS Supported: timer X-FB-External-Domain: wa.meta.vc Contact:;isfocus Content-Type: application/sdp Content-Length:645 v=0 o=-17466572865952 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 42da9643-cb50-4eca-95d3-ca41b3f1f4bb m=audio 3480 RTP/SAVP 107101 c=IN IP4 157.240.19.130 a=rtcp:9 IN IP4 0.0.0.0 a=mid:audio a=sendrecv a=msid:42da9643-cb50-4eca-95d3-ca41b3f1f4bb WhatsAppTrack1 a=rtcp-mux a=crypto:************************************************************************** a=rtpmap:107 opus/48000/2 a=fmtp:107 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1 a=rtpmap:101 telephone-event/8000 a=maxptime:20 a=ptime:20 a=ssrc:1238967757 cname:WhatsAppAudioStream1 User-initiated calls (with WebRTC media) SIP INVITE INVITE sip:+17015558857@meta-voip.example.com;transport=tls SIP/2.0Via: SIP/2.0/TLS [2803:6080:e888:51aa:d4a4:c5e0:300:0]:33819;rport=33819;received=2803:6080:e888:51aa:d4a4:c5e0:300:0;branch=z9hG4bKPjNvs.IZBnUa1W4l8oHPpk3SUMmcx3MMcE;aliasMax-Forwards:70From:"12195550714";tag=bbf1ad6e-79bb-4d9c-8a2c-094168a10beaTo:Contact:;isfocus Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCAzODg1NTE5NEU1NTBEMTc1RTFFQUY5NjNCQ0FCRkEzRhwYCzE3MDE1NTU4ODU3FQIAAA==CSeq:2824 INVITE Route: X-FB-External-Domain: wa.meta.vc Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS User-Agent:FacebookSipGatewayContent-Type: application/sdp Content-Length:1028 v=0 o=-17411131863672 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 632a909f-1060-4369-96a4-7bd03e291ee7 a=ice-lite m=audio 3480 UDP/TLS/RTP/SAVPF 111126 c=IN IP4 57.144.135.35 a=rtcp:9 IN IP4 0.0.0.0 a=candidate:17754698871 udp 212226022357.144.135.353480 typ host generation 0 network-cost 50 a=candidate:33557151111 udp 21222627832a03:2880:f343:131:face:b00c:0:699c3480 typ host generation 0 network-cost 50 a=ice-ufrag:RmDDkfzkwbexPfbC a=ice-pwd:************************* a=fingerprint:******************************************************************************************************** a=setup:actpass a=mid:audio a=sendrecv a=msid:632a909f-1060-4369-96a4-7bd03e291ee7WhatsAppTrack1 a=rtcp-mux a=rtpmap:111 opus/48000/2 a=rtcp-fb:111 transport-cc a=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=maxptime:20 a=ptime:20 a=ssrc:849255537 cname:WhatsAppAudioStream1 SIP BYE BYE sip:+5559800000693@wa.meta.vc;transport=tls;ob SIP/2.0Via: SIP/2.0/TLS 137.184.4.155:5061;received=2803:6080:c074:cac:10ed:4b05:400:0;i=8d2dc2Via: SIP/2.0/TLS 143.198.136.243:35181;rport=38087;received=143.198.136.243Route:Route:Max-Forwards:69From:;tag=NcKQ6mtDKSDQBTo:"5559800000693";tag=92a01092-ee78-4870-865f-bc176203a6bd Call-ID: outgoing:wacid.HBgPMjAwNzU2OTA0ODY5OTY1FRIAEhggMjQ4QzUwOUQ1REQ0NDUwNENEQzRFMTgwRTNGQjAwNjEcGAsxMjE0NTU1MTg2ORUCAAACSeq:98734935 BYE User-Agent:SignalWireAllow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY Supported: timer, path, replaces Reason: Q.850;cause=16;text="NORMAL_CLEARING"Content-Length:0 X-Relay-Call-ID: b72c0c65-e319-41b3-afb7-19ebcca05d38Content-Length:0 SIP INVITE (with SDES) INVITE sip:+12145551869@meta-voip.example.com;transport=tls SIP/2.0Via: SIP/2.0/TLS [2803:6080:f948:9597::]:57363;rport;branch=z9hG4bKPj3a9f2ad89e4a3df61408aa84f7d9a63e;aliasRecord-Route:Record-Route:Via: SIP/2.0/TLS [2803:6080:f948:9597:d33c:e00:400:0]:5061;branch=z9hG4bKPj3a9f2ad89e4a3df61408aa84f7d9a63e Via: SIP/2.0/TLS [2803:6080:f948:9597:1ac5:cdf8:300:0]:63057;rport=63057;received=2803:6080:f948:9597:1ac5:cdf8:300:0;branch=z9hG4bKPj-phic0sbns27DiP0OlrxRxgLtNg4mio7;aliasMax-Forwards:69From:"12195550714";tag=8a0f7e65-6e9e-4801-bf92-85c3ef2485d9To:Contact:;isfocus Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA4QkY1MTJCQkNFNTgxMEVFRERFRTUzNTFERkE1MDU0MhwYCzEyMTQ1NTUxODY5FQIAAACSeq:31159 INVITE X-FB-External-Domain: wa.meta.vc Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS User-Agent:FacebookSipGatewayContent-Type: application/sdp Content-Length:645 v=0 o=-17466599669802 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 07092115-d151-427e-8722-26c70936b104 m=audio 3480 RTP/SAVP 111126 c=IN IP4 157.240.19.130 a=rtcp:9 IN IP4 0.0.0.0 a=mid:audio a=sendrecv a=msid:07092115-d151-427e-8722-26c70936b104WhatsAppTrack1 a=rtcp-mux a=crypto:************************************************************************** a=rtpmap:111 opus/48000/2 a=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=maxptime:20 a=ptime:20 a=ssrc:1615009994 cname:WhatsAppAudioStream1 SIP OK (with SDES) SIP/2.0200 OK CSeq:31159 INVITE Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA4QkY1MTJCQkNFNTgxMEVFRERFRTUzNTFERkE1MDU0MhwYCzEyMTQ1NTUxODY5FQIAAAFrom:"12195550714";tag=8a0f7e65-6e9e-4801-bf92-85c3ef2485d9To:;tag=66596922_c3356d0b_fee164be-566a-4679-a80d-5bfdf1d0aa9eVia: SIP/2.0/TLS 157.240.229.209:5061;rport=51830;received=69.171.251.115;branch=z9hG4bKPj3a9f2ad89e4a3df61408aa84f7d9a63e;aliasVia: SIP/2.0/TLS [2803:6080:f948:9597:d33c:e00:400:0]:5061;branch=z9hG4bKPj3a9f2ad89e4a3df61408aa84f7d9a63e Via: SIP/2.0/TLS [2803:6080:f948:9597:1ac5:cdf8:300:0]:63057;rport=63057;received=2803:6080:f948:9597:1ac5:cdf8:300:0;branch=z9hG4bKPj-phic0sbns27DiP0OlrxRxgLtNg4mio7;aliasRecord-Route:Record-Route:Record-Route:Record-Route:Server:TwilioContact:Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY Content-Type: application/sdp X-Twilio-CallSid:CAb0d74508fe5fcdf6ec70ea3cf4e9b90bContent-Length:446Content-Type: application/sdp Content-Length:446 v=0 o=root 13536703851353670385 IN IP4 172.18.164.24 s=TwilioMediaGateway c=IN IP4 168.86.138.176 t=00 m=audio 15822 RTP/SAVP 111126 a=rtpmap:111 opus/48000/2 a=fmtp:111 maxplaybackrate=16000;sprop-maxcapturerate=16000;maxaveragebitrate=20000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=fmtp:1260-16 a=crypto:************************************************************************** a=ptime:20 a=maxptime:20 a=sendrecv User-initiated calls with digest auth (with SDES media) Meta SIP server supports digest auth for user initiated calls. Your SIP server should respond with digest auth challenge and Meta will resend the SIP INVITE with challenge response. The username used for digest auth is the (normalized) business phone number and the password is generated by Meta and retrievable using the get Call settings endpoint. First INVITE request from Meta INVITE sip:+12145551869@meta-voip.example.com;transport=tls SIP/2.0Via: SIP/2.0/TLS [2803:6080:f948:9597::]:47237;rport;branch=z9hG4bKPj1e6c665db16b3ecacf32cadb4497fe77;aliasRecord-Route:Record-Route:Via: SIP/2.0/TLS [2803:6080:f948:9597:7253:922a:400:0]:5061;branch=z9hG4bKPj1e6c665db16b3ecacf32cadb4497fe77 Via: SIP/2.0/TLS [2803:6080:f8bc:9272:e488:9927:400:0]:58279;rport=58279;received=2803:6080:f8bc:9272:e488:9927:400:0;branch=z9hG4bKPjr33j97A1mx5J8HWHEy2zIgqZYCCIb4Fb;aliasMax-Forwards:69From:"12195550714";tag=ece2da15-39e7-4983-ac65-e312f325d94a To:Contact:;isfocus Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA2MUI2QUY0MDRCMTUyOTM4QkE5ODEwN0ZGQTAwODkxORwYCzEyMTQ1NTUxODY5FQIAFRoACSeq:9989 INVITE X-FB-External-Domain: wa.meta.vc Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS User-Agent:FacebookSipGatewayContent-Type: application/sdp Content-Length:643 v=0 o=-17507168679132 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 4e37b099-8aef-45d0-be4f-1cde2ca5a37d m=audio 3480 RTP/SAVP 111126 c=IN IP4 57.144.219.49 a=rtcp:9 IN IP4 0.0.0.0 a=mid:audio a=sendrecv a=msid:4e37b099-8aef-45d0-be4f-1cde2ca5a37dWhatsAppTrack1 a=rtcp-mux a=crypto:************************************************************************** a=rtpmap:111 opus/48000/2 a=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=maxptime:20 a=ptime:20 a=ssrc:215879358 cname:WhatsAppAudioStream1 407 Response from partner SIP server SIP/2.0407ProxyAuthentication required CSeq:9989 INVITE Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA2MUI2QUY0MDRCMTUyOTM4QkE5ODEwN0ZGQTAwODkxORwYCzEyMTQ1NTUxODY5FQIAFRoAFrom:"12195550714";tag=ece2da15-39e7-4983-ac65-e312f325d94a To:;tag=45065608_c3356d0b_16001fd8-76d2-45f0-bb35-e0441d6dc4a2 Via: SIP/2.0/TLS 31.13.66.215:5061;rport=62080;received=69.171.251.112;branch=z9hG4bKPj1e6c665db16b3ecacf32cadb4497fe77;aliasVia: SIP/2.0/TLS [2803:6080:f948:9597:7253:922a:400:0]:5061;branch=z9hG4bKPj1e6c665db16b3ecacf32cadb4497fe77 Via: SIP/2.0/TLS [2803:6080:f8bc:9272:e488:9927:400:0]:58279;rport=58279;received=2803:6080:f8bc:9272:e488:9927:400:0;branch=z9hG4bKPjr33j97A1mx5J8HWHEy2zIgqZYCCIb4Fb;aliasContact:Proxy-Authenticate:Digest realm="sip.twilio.com",nonce="eyOam_8-l5FVugxsyxFRjnlxq9vy1TjQIMB3mBfJuAvB5gV4",opaque="4a6a068be2ca2032a57912b9a2a6adf7",qop="auth"Content-Length:0Content-Length:0 Second INVITE with authorization from Meta INVITE sip:+12145551869@meta-voip.example.com;transport=tls SIP/2.0Via: SIP/2.0/TLS 31.13.66.215:5061;rport;branch=z9hG4bKPj16be0694dc6763eb66de5ec5f262db03;aliasRecord-Route:Record-Route:Via: SIP/2.0/TLS [2803:6080:f948:9597:7253:922a:400:0]:5061;branch=z9hG4bKPj16be0694dc6763eb66de5ec5f262db03 Via: SIP/2.0/TLS [2803:6080:f8bc:9272:e488:9927:400:0]:58279;rport=58279;received=2803:6080:f8bc:9272:e488:9927:400:0;branch=z9hG4bKPjYp9LqI0D8zJ.wly5wyMyVaH9fUwIU921;aliasMax-Forwards:69From:"12195550714";tag=ece2da15-39e7-4983-ac65-e312f325d94a To:Contact:;isfocus Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA2MUI2QUY0MDRCMTUyOTM4QkE5ODEwN0ZGQTAwODkxORwYCzEyMTQ1NTUxODY5FQIAFRoACSeq:9990 INVITE X-FB-External-Domain: wa.meta.vc Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS User-Agent:FacebookSipGatewayProxy-Authorization:Digest username="12145551869", realm="sip.twilio.com", nonce="eyOam_8-l5FVugxsyxFRjnlxq9vy1TjQIMB3mBfJuAvB5gV4", uri="sip:+12145551869@meta-voip.example.com", response="b28ed6b8bf1418e3c6eca05ef8c7a0b1", cnonce="TY2SszvYCKitUCBlVLpGiPKMQfmBbj", opaque="4a6a068be2ca2032a57912b9a2a6adf7", qop=auth, nc=00000001Content-Type: application/sdp Content-Length:643 v=0 o=-17507168679132 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 4e37b099-8aef-45d0-be4f-1cde2ca5a37d m=audio 3480 RTP/SAVP 111126 c=IN IP4 57.144.219.49 a=rtcp:9 IN IP4 0.0.0.0 a=mid:audio a=sendrecv a=msid:4e37b099-8aef-45d0-be4f-1cde2ca5a37dWhatsAppTrack1 a=rtcp-mux a=crypto:************************************************************************** a=rtpmap:111 opus/48000/2 a=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=maxptime:20 a=ptime:20 a=ssrc:215879358 cname:WhatsAppAudioStream1 SIP OK from partner SIP server SIP/2.0200 OK CSeq:9990 INVITE Call-ID: outgoing:wacid.HBgLMTIxOTU1NTA3MTQVAgASGCA2MUI2QUY0MDRCMTUyOTM4QkE5ODEwN0ZGQTAwODkxORwYCzEyMTQ1NTUxODY5FQIAFRoAFrom:"12195550714";tag=ece2da15-39e7-4983-ac65-e312f325d94a To:;tag=29360930_c3356d0b_4933dc58-f035-4597-b075-04b19e552329Via: SIP/2.0/TLS 31.13.66.215:5061;rport=62080;received=69.171.251.112;branch=z9hG4bKPj16be0694dc6763eb66de5ec5f262db03;aliasVia: SIP/2.0/TLS [2803:6080:f948:9597:7253:922a:400:0]:5061;branch=z9hG4bKPj16be0694dc6763eb66de5ec5f262db03 Via: SIP/2.0/TLS [2803:6080:f8bc:9272:e488:9927:400:0]:58279;rport=58279;received=2803:6080:f8bc:9272:e488:9927:400:0;branch=z9hG4bKPjYp9LqI0D8zJ.wly5wyMyVaH9fUwIU921;aliasRecord-Route:Record-Route:Record-Route:Record-Route:Contact:Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY Content-Type: application/sdp X-Twilio-CallSid:CAd4d6e59a356c4d1b0ee85323b2d9dab5Content-Length:444Content-Type: application/sdp Content-Length:444 v=0 o=root 477560318477560318 IN IP4 172.18.156.61 s=TwilioMediaGateway c=IN IP4 168.86.137.174 t=00 m=audio 12710 RTP/SAVP 111126 a=rtpmap:111 opus/48000/2 a=fmtp:111 maxplaybackrate=16000;sprop-maxcapturerate=16000;maxaveragebitrate=20000;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=fmtp:1260-16 a=crypto:************************************************************************** a=ptime:20 a=maxptime:20 a=sendrecv Configure SDES for SRTP key exchange The Secure Real-time Transport Protocol (SRTP) key exchange is a cryptographic protocol used to securely exchange encryption keys between two parties over an insecure communication channel. You can configure SRTP key exchange to one of two options:DTLS (default) — Industry-standard encrypted key exchange. Recommended.SDES — Plain text key is included in the SDP which is sent over secure signaling protocol like SIP or Graph API. When SDES is used, there is no need for STUN, ICE and DTLS which could help shorten the call setup time. Error response View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Get SRTP key exchange protocol Endpoint parameters Placeholder Description Sample Value Integer Required The business phone number for which you are updating Calling API settings. Learn more about formatting phone numbers in Cloud API +12784358810 Response parameters Parameter Description Sample Value srtp_key_exchange_protocol String The type of SRTP key exchange protocol configured for the business phone number queried Possible values are SDES and DTLS. Default is DTLS. Note: If this field has not been explicitly set, it will not be returned. “SDES” Error response View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here IP addresses The IP addresses used for SIP configuration are the same as those listed for the Webhooks in the Cloud API Webhooks IP Addresses section. This reference is solely to indicate the IP addresses to allow-list for SIP traffic. When SIP is enabled, calling related webhooks are not sent. Troubleshooting Refer to SIP FAQ for additional SIP specific questions and answers and SIP Errors for SIP specific errors and solutions Send WhatsApp Call Button Messages and Deep Links | Developer Documentation Send WhatsApp Call Button Messages and Deep Links Updated: Feb 25, 2026 Overview After you adopt Cloud API Calling features, you can raise awareness with your customers in two core ways: Send them a message with a WhatsApp call buttonEmbed a calling deep link into your brand surfaces (website, application, and so on) Send interactive message with a WhatsApp call button Use this endpoint to send a free-form interactive message with a WhatsApp call button during a customer service window or an open conversation window. When a WhatsApp user clicks the call button, it initiates a WhatsApp call to the business number that sent the message. A standard message status webhook will be sent in response to this message send. Body parameters Learn more about sending interactive free form messages Parameter Description Sample Value to Integer Required The phone number of the WhatsApp user you are messaging. Learn more about formatting phone numbers in Cloud API "17863476655" type String Required The type of interactive message you are sending. In this case, you are sending a voice_call. Learn more about interactive messages "voice_call" action String Required The action of your interactive message. Must be voice_call. "voice_call" parameters JSON Object Optional Optional parameters for the WhatsApp calling button sent to the user. Contains three values: display_text, ttl_minutes, and payload display_text — (String) Optional The display text on the WhatsApp calling button sent to the user. Default is “Call Now” Max length: 20 characters ttl_minutes — (Integer) Optional Time to live for the call-to-action (CTA) button in minutes. Must be between 1 and 43200 (30 days) Default value is 10080 (7 days) payload — (String) Optional An arbitrary string, useful for tracking. Any app subscribed to the calls webhook field on the WhatsApp Business Account can get this string, as it is included in the connect and terminate webhook payloads under the cta_payload field. Cloud API does not process this field, it just returns it as part of the webhooks. Maximum 512 characters. Payload is only available to WhatsApp client starting on version 2.25.27. Success response Learn more about messaging success responses Error response Possible errors that can occur: Sending this message to users on older app versions results in an error webhook with error code 131026. View general Cloud API error codes Create and send WhatsApp call button template message Use these endpoints to create and send a WhatsApp call button template message. Once your call button template message is created, you can send a message to a WhatsApp user, inviting them to call your business. Learn more about creating and managing message templates Create call button message template Use this endpoint to create a call button message template. Body parameters You can create and manage template messages through both Cloud API and the WhatsApp Business Manager interface. When creating your call button template, ensure you configure type as voice_call. Learn more about creating and managing message templates Parameter Description Sample Value type String Required The type of template message you are creating. In this case, you are creating a voice_call. "voice_call" text String Optional The display text on the WhatsApp calling button sent to the user. Default is “Call Now” Max length: 20 characters "Call Now" ttl_minutes Integer Optional Time to live for the CTA button in minutes. Must be between 1440 (1 day) and 43200 (30 days). You can override this value when sending the message. 1440 Success response Learn more about messaging success responses Error response Possible errors that can occur: Invalid whatsapp-business-account-idPermissions/Authorization errorsTemplate structure/component validation alerts View general Cloud API error codes Calling deep links Calling deep links are hyperlinks that route WhatsApp users to call your business. The process to create a calling deep link is similar to a chat deep link⁠, except the format for the call deep link is wa.me/call/ Note that deep links are not supported on WhatsApp desktop clients. Embed calling deep links You can use calling deep links to advertise WhatsApp calling for your business. Use these links anywhere where calling can be useful, like your website, primary application, or even as a QR code to be shared. Send calling deep links You can also send messages to WhatsApp users with a calling deep link. Since deep links can be made per business phone number, you can use calling deep links to prompt WhatsApp users to contact a different phone number with voice enabled. The wa.me/call/ format is easy to copy, paste, and send, and does not require you to make a template in Business Manager. Send payload data in call deep link You can also send a payload with the deep link. You can use the biz_payload query string when sending the call deep link to any user ( wa.me/call/?biz_payload=payload). When a user calls using the provided deep link with the biz_payload any app subscribed to the calls webhook field on the WhatsApp Business Account can get this string, as it is included in the connect and terminate webhook payloads under the deeplink_payload field. Payload in call deep link is only available to WhatsApp client starting on version 2.25.27. Integration Patterns | Developer Documentation Integration Patterns Updated: Feb 25, 2026 Possible high-level approaches Approach Number setup Business Solution Provider responsibilities Calling Tech Provider responsibilities End business responsibilities Message BSP capable of Calling Existing messaging number extended for calling or new number Messaging BSP reuses their app and subscribes it to calls webhooks. Creation of new calling specific app also works but not recommendedProcess calls webhooks and coordinate with real-time media infraMake calls related Graph API calls similar to messaging Graph API calls Not applicable because there is only a single partner involved. Enable and use callingContinue paying the bill from BSP which now has calls related usage line items Multi-solution Conversation Single number independently operated by both messaging BSP and Calling BSP/TP Messaging BSP does no changes Calling BSP/TP hosts ES on their own website pointing to their own appGets end-biz to go through their ES Onboard using calling partner’s ESPay the bills to Messaging BSP like beforeFor Calling partner incurred activity, pay the bill to calling partner if they are a BSP or to Meta if they are not a BSP Exclusive Calling ISV New number for calling Not applicable because there is no messaging BSP Calling ISV hosts Embedded Signup (ES) on their website pointing to their own appGets end-biz to go through their ESIf ISV is a tech provider or partner, Meta bills end-biz directly. ISV and end-biz figure out their own billingIf ISV is a BSP, they can extend their credit line to end-biz Onboard using ES on TPIf ISV is Tech Provider or Partner, pay Meta directly This requires end-biz to have a direct payment relation with Meta. Setting up this relation may take several weeksIf ISV is BSP, pay the bill from BSP Multi-platform solution using Calling ISV registered as Tech Provider (TP) New calling exclusive number serviced (only) by Calling TP BSP and TP work together to create / approve a multi-partner solution. BSP and TP have their own appsWork out Messaging BSP <> Calling ISV commercial relationExtend credit line to end businessCan receive messages or calls but cannot send messages or calls because you can select only one of the two partners to send messages/calls in a multi-platform solution BSP and TP work together to create / approve a multi-partner solution. BSP and TP have their own appsWork out Messaging BSP <> Calling ISV commercial relationOnboard end clients using ES pointing to created solutionSend/receive messages or calls Onboard using ES on TPBiz is informed about TP in ESPay the bill from BSP Multi-solution conversations (MSC) Multi-solution Conversations allow multiple solutions on the same phone number, localizing messaging and calling in a single chat thread. Learn more about Multi-Solution Conversations Integrating using a third party calling provider detailed design The following logical architecture illustrates how to integrate WhatsApp Business Calling using a third party (3p) calling provider. In this scenario, you would use the 3p vendor behind the scenes, and that 3p vendor would not be visible to Meta. This pattern is similar to any other SaaS service you may be using. The diagram also illustrates how this architecture can be optionally extended to integrate with the SIP infrastructure on your side. Our terms disallow use of PSTN on any leg of the WhatsApp call in the overall call flow. Even if you bridge WA call into the SIP world, you must ensure it still stays exclusively on VoIP and never touches the PSTN. SIP trunk by itself is not disallowed because technically a SIP trunk can be used without any PSTN at all. (Right click image and choose “Open in new tab” for enlarged image) Single app vs. multiple apps This section covers guidelines and considerations for reusing your existing messaging app for calling vs. creating a new app specifically for Calling API features. To integrate with the WhatsApp Calling API, you need to call Graph API endpoints and process Webhooks from Meta. This requires you to have an app, and almost always, you should already have an app that is used for messaging. In short, you can reuse an existing app which is used for Embedded Signup and for a messaging use case. Reusing the same app offers the following benefits:Reduced operational overhead (for example, app review, ongoing maintenance)Simplified footprint on MetaEquality between the app used for embedded signup and the one used for invoking Graph APIs and receiving webhooksThere would be no impact to existing functionality by reusing that app for calling. You just need to make sure the Webhook server is able to gracefully handle ‘calls’ related webhooks. Having separate apps is still supported, see the Get Started FAQ for details. Guidelines for Media path integration The WhatsApp Business Calling VoIP stack is designed to be compatible with WebRTC. However, to ensure smooth integration with the WhatsApp protocol, Meta restricts the supported functionalities. As a result, the following requirements and recommendations apply. Mandatory requirements If any mandatory requirement is unmet, the call will fail. This failure can occur either during the call signaling phase, leading to a rejected call, or during the media packet decoding phase.Use only the Opus audio codec.Set the media clock rate to 48 kHz.Set the DTMF clock rate to 8 kHz.Use a ptime of 20ms.Audio must use a single SSRC. The Meta relay server overwrites the SSRC of all business audio packets to a fixed SSRC before these packets reach the WA client. WA clients handle only one audio source from their peers. Using multiple SSRCs causes undefined behavior. This includes severe media corruption, audio glitches, and likely total media failure. Recommendations While the following aspects are not mandatory, they are recommended to achieve high call quality and reliability.ICE ProcessOur VoIP stack is ICE-LITE, so it is recommended that BSPs’ VoIP stack is ICE-FULL. (RFC 5245 Section 2.7⁠)BSPs’ VoIP stack should initiate the ICE process by sending STUN connectivity checks.BSPs’ VoIP stack should assume the ICE CONTROLLING role, as Meta will only assume the CONTROLLED role.Use regular nomination instead of aggressive nomination. (RFC 5245 Section 8.1.1.2⁠)Wait for the ICE process to complete before nominating the candidate and starting DTLS.Do not switch the candidate in the middle of the call.DTLSUse ECDH keys for the DTLS certificates to prevent packet fragmentation during transmission.BSP should act as a DTLS client. (RFC 6347 Section 4.2⁠)Addressing Audio ClippingDelay the audio from the SIP leg until the media connection with Meta is established.Integrate with the pre-accept API to help mitigate audio clipping in user-initiated calls. Integration Examples | Developer Documentation Integration ExamplesUpdated: Feb 25, 2026This guide explains integration of common VoIP platforms with WhatsApp Business Calling API.This guide is for information purposes only with no support or warranties of any kind from Meta or any vendor. There are many ways to integrate and the guide explains just one way exclusively for illustrative purposes. Asterisk using SIP OverviewThis guide explains how to set up WhatsApp Business Calling API using SIP signaling with Asterisk⁠, an open-source PBX (Private Branch Exchange). You’ll learn how to configure your Asterisk server, connect SIP phones, and handle both incoming and outgoing WhatsApp calls. User-initiated calls The WhatsApp user dials the business number.The call is received by Asterisk and routed through an IVR, prompting the user to enter an extension, registered to the same Asterisk server.The call is then connected to the specified extension. Business-initiated calls The business agent/user registers with Asterisk using SIP credentials (see “Configuring a VoIP Phone” section).The business user dials the b2c-sip (business to consumer) extension, which is handled by an IVR. The IVR prompts for the WhatsApp number to call.The call is then connected to the WhatsApp user.The WA to Asterisk leg uses SDES for media encryption key exchange and opus for audio codecThe Asterisk to SIP UA leg uses SDES for media encryption key exchange and opus or G711 for audio codec Prerequisites Asterisk Deployment: Asterisk is deployed (for example, on a public cloud instance)Operating System: Any OS compatible for Asterisk. For example, CentOS 9Domain: Asterisk server is reachable via a public domain with valid certificateWhatsApp Business API: A WhatsApp business phone number is registered and calling is enabled.SIP Support: SIP is enabled on the WhatsApp Business NumberSDES: SDES is enabled on the WhatsApp Business Number Building and installing AsteriskRefer to https://docs.asterisk.org/Getting-Started/Installing-Asterisk/Installing-Asterisk-From-Source/Building-and-Installing-Asterisk/⁠This guide was tested using Asterisk version 22.5.2 Asterisk configurationThese configuration files are placed under /etc/asterisk/ extensions.confReplace the following placeholders with actual values {wa-business-phone-number}: WhatsApp Business Phone Number{asterisk-sip-server-dns}: DNS name of your Asterisk SIP serverincoming_welcome: incoming_welcome.wav (not provided) place this file under /var/lib/asterisk/soundsoutgoing_welcome: outgoing_welcome.wav (not provided) place this file under /var/lib/asterisk/sounds [c2b-sub-dial] exten => s,1,NoOp() same => n,Read(Digits,incoming_welcome,0,,5,500) same => n,Dial(PJSIP/${Digits}) same => n,Hangup()[whatsapp] exten => _10XX,1,NoOp() same => n,Dial(PJSIP/${EXTEN}) same => n,Hangup();Extensionfor B2C business call through Meta SIP gateway exten => b2c-sip,1,NoOp() same => n,Read(Digits,outgoing_welcome,0,,5,500) same => n,Dial(PJSIP/whatsapp/sip:${Digits}@wa.meta.vc);Extension to handle incoming invite requests fromMeta SIP gateway to @ exten => _+,1,Goto(c2b-sub-dial,s,1) Pjsip.confReplace the following placeholders with actual values {wa-business-phone-number} : the business phone number{local-net}: local network of the Asterisk server{external-media-address}: Public IP of the Asterisk server media{external-signaling-address}: Public IP of the Asterisk server signaling{sip-ua-password}: Chosen SIP User Agent password{domain-name}: domain name assigned to the Asterisk serverCertificate files should be placed under /var/lib/asterisk/certs/fullchain.cer /var/lib/asterisk/certs/cer.key [transport-tls] type=transport protocol=tls bind=0.0.0.0:5061 cert_file=/var/lib/asterisk/certs/fullchain.cer priv_key_file=/var/lib/asterisk/certs/cer.key method=sslv23 allow_wildcard_certs=yes external_media_address={external-media-address};External address for SIP signalling external_signaling_address={external-signaling-address};Network to consider local used for NAT purposes local_net={local-net}[sdes_endpointtemplate](!) type=endpoint context=whatsapp disallow=all allow=OPUS direct_media=no rtp_symmetric=yes force_rport=yes rewrite_contact=no media_use_received_transport=yes media_encryption=sdes [authtemplate](!) type=auth auth_type=userpass password={sip-ua-password}[aortemplate](!) type=aor max_contacts=1 remove_existing=yes [aoridentitytemplate](!) type=identify match_header=X-FB-External-Domain: wa.meta.vc ;SDES users [1000](sdes_endpointtemplate) auth=1000_auth aors=1000[1000_auth](authtemplate) username=1000[1000](aortemplate)[1000](aoridentitytemplate) endpoint=1000[1001](sdes_endpointtemplate) auth=1001_auth aors=1001[1001_auth](authtemplate) username=1001[1001](aortemplate)[1001](aoridentitytemplate) endpoint=1001[1002](sdes_endpointtemplate) auth=1002_auth aors=1002[1002_auth](authtemplate) username=1002[1002](aortemplate)[1002](aoridentitytemplate) endpoint=1002[1003](sdes_endpointtemplate) auth=1003_auth aors=1003[1003_auth](authtemplate) username=1003[1003](aortemplate)[1003](aoridentitytemplate) endpoint=1003[1004](sdes_endpointtemplate) auth=1004_auth aors=1004[1004_auth](authtemplate) username=1004[1004](aortemplate)[1004](aoridentitytemplate) endpoint=1004[1005](sdes_endpointtemplate) auth=1005_auth aors=1005[1005_auth](authtemplate) username=1005[1005](aortemplate)[1005](aoridentitytemplate) endpoint=1005;This endpoint maps to an IVR for C2B calls [c2b-sip](sdes_endpointtemplate)[c2b-sip](aortemplate)[c2b-sip] type=identify endpoint=c2b-sip match_header=X-FB-External-Domain: wa.meta.vc ;special endpoint forMeta SIP Gateway integration ;This endpoint maps to an IVR for B2C calls [b2c-sip](sdes_endpointtemplate)[b2c-sip](aortemplate)[whatsapp](sdes_endpointtemplate) type=endpoint transport=transport-tls disallow=all allow=opus,ulaw,alaw aors=whatsapp from_user={wa-business-phone-number} from_domain={domain-name} outbound_auth=whatsapp [whatsapp] type=aor contact=sip:wa.meta.vc [whatsapp] type=identify endpoint=whatsapp [whatsapp] type=auth auth_type=digest password={meta-sip-user-password} username={wa-business-phone-number} realm=* rtp.conf [general];Hostnameor address for the STUN server used for determining the external ; IP address and port an RTP session can be reached at.The port number is; optional.If omitted default value of 3478 will be used.This option is; disabled bydefault.Name resolution occurs at load time,andif DNS is; used, name resolution will occur repeatedly after the TTL expires.;;for example stundaddr=mystun.server.com:3478; stunaddr=stun.l.google.com:19302 rtpstart=10000 rtpend=60000 Configuring a VoIP phoneDownload and install a softphone client (for example, Linphone⁠) for testing both business-initiated and user-initiated calls. Account setup Select an extension to register as a SIP UA (extensions 1001–1005).Open Preferences.Under “SIP Accounts,” click “Add account.”Enter the following details: SIP Address: for example, sip:1001@{asterisk-sip-server-dns}SIP Server Address: for example, sip:{asterisk-sip-server-dns};transport=tlsTransport: TLSDisable ICEEnable AVPFDisable “Publish presence information”Confirm and save the account.Enter the password when prompted (viz. {sip-ua-password})Once connected, return to Preferences and select the “Audio” tab. Enable all audio codecs.In the “Calls and Chat” tab: Select “Encryption”Choose “SRTP-SDES”Enable “Encryption is mandatory”Confirm settings Final checklist Double-check all configuration files for correct numbers, passwords, and domain names.Make sure your firewall allows SIP (5061/TLS) and RTP (10000-20000) ports.For more details on SIP password setup, see the WhatsApp Cloud API documentation. Troubleshooting Cannot register SIP UAConfirm that the SIP URL is correct and the domain is pointing to the Asterisk server. Run host {domain-name} to verify that the IP address points to the Asterisk server. Not receiving ACK from Meta OR Business audio stops around 30s OR Meta returns 404 response to BYEFor a user initiated call, Meta sends a SIP INVITE to your SIP server which then responds with 200 OK. Meta acks your 200 OK with an ACK but you never receive this ACK. So your SIP server keeps resending the 200 OK and ultimately the SIP dialog is terminated due to ACK timeout (typically 32s).The most likely cause for this problem is incorrect Record-Route headers in your 200 OK to Meta. The 200 OK response is supposed to not modify the Record-Route headers included in the original Meta’s INVITE. Your SIP server can add new Record-Route headers but cannot modify those present in our INVITEThe solution to this problem is to change rewrite_contact=yes to rewrite_contact=no on the WhatsApp endpoint configuration in pjsip.conf file. After this make sure your 200 OK has following headers as the last 2 in the list of Record-Route headersThis problem is hard to detect or diagnose. Even with this bug, the call will get connected and media will flow both sides but around 32s later, your SIP server will terminate the call which won’t be propagated to WhatsApp client because your BYE request has incorrect Route headers. So WA user stops hearing business audio around 32s. Record-Route:Record-Route: FreeSWITCH using SIP OverviewThis guide explains how to set up WhatsApp Business Calling API using SIP signaling with FreeSWITCH⁠, an open-source communication framework. You’ll learn how to configure your FreeSWITCH server, connect SIP phones, and handle both user-initiated and business-initiated WhatsApp calls. User-initiated calls The WhatsApp user dials the business number.The call is received by FreeSWITCH and routed through an IVR, which prompts the user to enter an agent’s extension registered on the same FreeSWITCH server.Once the extension is entered, the call is connected to the specified recipient agent. Business-initiated calls The business agent or user registers with FreeSWITCH using SIP credentials (see the Configuring a VoIP Phone section for details).The business user dials the b2c-sip (business-to-consumer) extension, which is managed by an IVR. The IVR then prompts for the WhatsApp number to call.After the number is entered, the call is connected to the WhatsApp user via SIP.The WA to FreeSWITCH leg uses SDES for media encryption key exchange with Opus as the audio codec. FreeSWITCH - SIP UA leg uses SDES for media encryption key exchange with Opus or G.711 audio codecs Prerequisites FreeSWITCH Deployment: FreeSWITCH is deployed (for example, on a public cloud instance)Operating System: Any OS compatible with FreeSWITCH. For example, CentOS 9Domain: FreeSWITCH server is reachable via a public domain with a valid certificateWhatsApp Business API: A WhatsApp business phone number is registered and calling is enabled.SIP Support: SIP is enabled on the WhatsApp Business Number Note: FreeSWITCH is configured to listen on 5081 for TLSSDES: SDES is enabled on the WhatsApp Business Number Building and installing FreeSWITCHRefer to https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/⁠This guide was tested using FreeSWITCH version 1.10.12. FreeSWITCH uses sofia (an open-source SIP user agent library). Sofia v1.13.17 was used for this guide FreeSWITCH configurationThese configuration files are placed under /usr/share/freeswitch/etc/freeswitchwa-biz-api-dialplan.xmlPlace the dial plan under /usr/share/freeswitch/etc/freeswitch/dialplan/default/wa-biz-api-dialplan.xml Audio files should be placed under /usr/share/freeswitch/sounds (not provided) incoming_welcome.wavIncoming_invalid.wavoutgoing_welcome.wavoutgoing_invalid.wavwhatsapp.xmlThis file configures the WhatsApp gateway, copy the file to /usr/share/freeswitch/etc/freeswitch/sip_profiles/external/whatsapp.xml Replace the following placeholders with actual values {phone-number}: WhatsApp Business Phone Number{meta-sip-password}: SIP password issued by Meta. For more details on SIP password setup, see the WhatsApp Cloud API documentation.{domain-name}: DNS name of your FreeSWITCH SIP serveracl.conf.xmlOpen /usr/share/freeswitch/etc/freeswitch/autoload_configs/acl.conf.xmlAdd the following list under network-lists element vars.xmlModify /usr/share/freeswitch/etc/freeswitch/vars.xml Add line under Replacewith(substitute {sip_ua_password}with your password)Replacewith(substitute {domain-name}with your FreeSWITCH SIP server DNS) with (substitute {external-ip} with your FreeSWITCH public ip) Replace with (substitute {external-ip} with your FreeSWITCH public ip) internal.xmlModify /usr/share/freeswitch/etc/freeswitch/sip_profiles/internal.xml Look for: Replace it with external.xml Modify /usr/share/freeswitch/etc/freeswitch/sip_profiles/external.xml ReplacewithReplacewithReplacewithMake sure certificates are placed under /usr/share/freeswitch/etc/freeswitch/certs Final checklist Double-check all configuration files for correct numbers, passwords, and domain names.Make sure your firewall allows SIP (5081/TLS) and RTP (10000-20000) ports.For more details on SIP password setup, see the WhatsApp Cloud API documentation. Troubleshooting Cannot register SIP UAConfirm that the SIP URL is correct and the domain is pointing to the FreeSWITCH server. Run host {domain-name} to verify that the IP address points to the FreeSWITCH server. Trace SIP messagesStart CLI (/usr/share/freeswitch/bin/fs_cli) to view SIP messages FreeSWITCH using Graph API with Janus OverviewThis guide explains how to set up WhatsApp Business Calling API using WhatsApp Cloud API signaling with FreeSWITCH⁠, an open-source communication framework and Janus⁠, a general purpose WebRTC server. You’ll learn how to configure your FreeSWITCH server, connect SIP phones, and handle both incoming and outgoing WhatsApp calls. User-initiated calls The WhatsApp user dials the business number.The call is received by Webhook server which forwards it to FreeSWITCH server via Janus SIP plugin.The call is received by FreeSWITCH and routed through an IVR, prompting the user to enter an extension, registered to the same FreeSWITCH server.The call is then connected to the specified extension. Business-initiated calls The business agent/user registers with FreeSWITCH using SIP credentials (see “Configuring a VoIP Phone” section).The business user dials the b2c-sip (business to consumer) extension, which is handled by an IVR. The IVR prompts for the WhatsApp number to call.FreeSWITCH bridges the call to extension registered to Janus SIP plugin which translates it to an API request to MetaThe call is then connected to the WhatsApp user.The Janus server sits between WA and FreeSWITCH and converts media from WA (WebRTC complaint with DTLS key exchange) to FreeSWITCH negotiated media (SDES key exchange).FreeSWITCH - Sip UA will be using SDES for media encryption key exchange and opus or G711 for audio codec Prerequisites FreeSWITCH Deployment: FreeSWITCH is deployed (for example, on a public cloud instance)Janus Deployment: Can be deployed on the same machine as FreeSWITCHOperating System: Any OS compatible with FreeSWITCH. For example, CentOS 9Domain: FreeSWITCH server and Webhook server are reachable via a public domain with valid certificateWhatsApp Business API: A WhatsApp business phone number is registered and calling is enabled.Webhooks: Configure Webhook callback URL pointing to domain name of the Webhook server Integration with Cloud API signalingYou will need to implement an integration module which sits between WA and Janus and translates Cloud API Signalling messages to Janus SIP plugin messages and vice versa.You will need A webhook server to receive calls webhook events from MetaA Graph API module to send call messages to MetaAn implementation of Janus SIP plugin⁠ to connect to Janus. The Janus plugin implementation will connect to FreeSWITCH using extension 1000 which is reserved for bridgingBusiness initiated calls The module will receive a SIP INVITE via Janus SIP plugin on extension 1000. The SIP INVITE is converted to a Graph API request. The SDP received in the SIP INVITE is sent verbatim as the SDP offer to WA via the Graph API callWhen the call is accepted by the WA user, an accepted webhook is received. On receiving the webhook, the Janus SIP Plugin accepts the SIP INVITE passing the answer SDP in the connect webhookUser Initiated calls The webhook server receives an incoming call via a webhook message containing the offer SDP. On receiving the call invite, the Janus SIP plugin sends an invite to FreeSWITCH via extension 1000. The destination extension is c2b-sip.When the Janus SIP plugin receives the SIP 200 OK, a Graph API accept call request is sent to Meta to accept the incoming call by passing the SDP received as part of SIP answer Building and installing JanusRefer to https://github.com/meetecho/janus-gateway⁠ This guide was tested using version 1.2.3 Janus configurationjanus.jcfgModify janus.jcfg which can be found at /usr/share/janus/etc/janus/janus.jcfg Set nat_1_1_mapping to the public IP of the Janus ServerTo start Janus /usr/share/janus/bin/janus --debug-level=6--libnice-debug=on -S stun.l.google.com:19302--log-file=/var/log/janus.log --config=/usr/share/janus/etc/janus/janus.jcfg Building and installing FreeSWITCHRefer to https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/⁠This guide was tested using FreeSWITCH version 1.10.12. FreeSWITCH uses sofia (an open-source SIP user agent library). Sofia v1.13.17 was used for this guideFreeSWITCH Configuration These configuration files are placed under /usr/share/freeswitch/etc/freeswitchwa-biz-api-dialplan.xmlPlace the dial plan under /usr/share/freeswitch/etc/freeswitch/dialplan/default/wa-biz-api-dialplan.xml Audio files should be placed under /usr/share/freeswitch/sounds (not provided) incoming_welcome.wavIncoming_invalid.wavoutgoing_welcome.wavoutgoing_invalid.wavinternal.xmlModify /usr/share/freeswitch/etc/freeswitch/sip_profiles/internal.xml Look for: Replace it with Configuring a VoIP phoneRefer to the earlier section Final checklist Double-check all configuration files for correct numbers, passwords, and domain names.Make sure your firewall allows SIP (5061/TLS) and RTP (10000-20000) ports.For more details on SIP password setup, see the WhatsApp Cloud API documentation. Troubleshooting Cannot register SIP UAConfirm that the SIP URL is correct and the domain is pointing to the FreeSWITCH server. Run host {domain-name} to verify that the IP address points to the FreeSWITCH server. Trace SIP messagesStart CLI (/usr/share/freeswitch/bin/fs_cli) to view SIP messages Asterisk using Graph API with RtpEngine OverviewThis guide explains how to set up WhatsApp Business Calling API using WhatsApp Cloud API signaling with Asterisk⁠, an open-source PBX (Private Branch Exchange) and RtpEngine⁠, an open-source proxy used for relaying, manipulating, and controlling RTP streams. You’ll learn how to configure your Asterisk server, connect SIP phones, and handle both incoming and outgoing WhatsApp calls. User-initiated calls The WhatsApp user dials the business number.The call is received by the Webhook server which after bridging media using RtpEngine, forwards it to Asterisk using SIP.The call is received by Asterisk and routed through an IVR, prompting the user to enter an extension, registered to the same Asterisk server.The call is then connected to the specified extension. Business-initiated calls The business agent/user registers with Asterisk using SIP credentials (see “Configuring a VoIP Phone” section).The business user dials the b2c-sip (business to consumer) extension, which is handled by an IVR. The IVR prompts for the WhatsApp number to call.Asterisk bridges the call to extension registered by the integration module (see “Integration with Cloud API Signalling”)On receiving the call, the integration module bridges the media using RtpEngine and then translates it to an API request to MetaThe call is then connected to the WhatsApp user.RtpEngine acts as a media proxy and sits between the media stream of WA (WebRTC complaint with DTLS key exchange) and Asterisk (SDES key exchange) Prerequisites Asterisk Deployment: Asterisk is deployed (for example, on a public cloud instance)RtpEngine Deployment: Can be deployed on the same machine as AsteriskOperating System: Any OS compatible with Asterisk and RtpEngine. For example, CentOS 9Domain: Asterisk server and Webhook server are reachable via a public domain with valid certificateWhatsApp Business API: A WhatsApp business phone number is registered and calling is enabled.Webhooks: Configure Webhook callback URL pointing to domain name of the Webhook server Integration with Cloud API signalingYou will need to implement an integration module that acts as a bridge between WhatsApp and Asterisk. This module will: Translate Cloud API Signaling messages from WhatsApp to SIP for Asterisk, and vice versaUse SIP signaling for communication between the SIP UA inside the module and AsteriskBridge the media between WhatsApp and Asterisk via RtpEngineYou will need following components, which are part of the integration module for the purpose of this setup Webhook Server: Receives call webhook events from Meta (WhatsApp Cloud API)Graph API client: Sends call-related requests to Meta using the Graph APISIP User Agent (UA) such as PJSIP: Connects to Asterisk using extension 1000, which is reserved for bridging calls between WhatsApp and Asterisk.RtpEngineClient: To control RtpEngine via ng control protocol⁠ for bridging media Business initiated calls Business agent registered to the same Asterisk server dials b2c-sip extension to initiate a call to WhatsApp userThe extension prompts the business agent to enter WA user’s phone numberAsterisk sends a SIP INVITE request to extension 1000 with a custom header containing the dialed WA user phone numberThe SIP UA inside the module would’ve registered at extension 1000 and hence receives the SIP INVITE from AsteriskThe SDP included in the SIP INVITE is sent to RtpEngine which returns a new SDPThe new SDP is included in the Graph API request to initiate a new callWhen the WhatsApp user accepts the call, an “accepted” webhook is receivedUpon receiving this webhook, the answer SDP received in the webhook is sent to RtpEngine which returns a new SDPThe SIP UA accepts the original SIP INVITE (step 3), passing along the new SDP received from RtpEngineThe call is now bridged between WA user, RtpEngine, and AsteriskUser Initiated calls The webhook server inside the module receives an incoming call webhook from Meta, which includes the offer SDPUpon receiving this call invite, the SDP included in the offer is sent to RtpEngine which returns a new SDPThe SIP UA inside the module sends a SIP INVITE to Asterisk using extension 1000 passing the new SDP from RtpEngine in the SIP INVITE. The destination extension is c2b-sip.The extension prompts WA user to dial the extension of the business agent to connect toAsterisk dials the specified extension and waits for an answerAfter the agent answers the call, Asterisk sends SIP 200 OK to the SIP UA extension 1000 inside the module. The SDP in SIP 200 OK is sent to RtpEngine which returns a new SDPA Graph API request is sent to Meta to accept the incoming call, with the new SDP received from RtpEngine Building and installing AsteriskRefer to https://docs.asterisk.org/Getting-Started/Installing-Asterisk/Installing-Asterisk-From-Source/Building-and-Installing-Asterisk/This guide was tested using Asterisk version 22.5.2 Building and installing RtpEngineRefer to https://github.com/sipwise/rtpengine⁠ to build and install RtpEngine This guide was tested using RtpEngine version 13.3.1.4Refer to https://rtpengine.readthedocs.io/en/latest/ng_control_protocol.html for details on ng control protocolTo start RtpEngine run /usr/bin/rtpengine --listen-ng={local-ip}:22222--interface={local-ip}\!{public-ip}-f -EReplace {local-ip} with the local IP of the RtpEngine server{public-ip} with the public IP of the RtpEngine serverAsterisk Configuration These configuration files are placed under /etc/asterisk/extensions.confReplace the following placeholders with actual values incoming_welcome: incoming_welcome.wav (not provided) place this file under /var/lib/asterisk/soundsoutgoing_welcome: outgoing_welcome.wav (not provided) place this file under /var/lib/asterisk/sounds [handler];Set headers on callee channel exten => addheader,1,Set(PJSIP_HEADER(add,X-WhatsApp-Number)=${DIGITS}) same => n,Return()[default] exten => _10XX,1,NoOp() same => n,Dial(PJSIP/${EXTEN}) same => n,Hangup() exten => b2c-sip,1,NoOp() same => n,Read(Digits,outgoing_welcome,0,,5,500) same => n,Set(GLOBAL(DIGITS)=${Digits});Before starting a business initiated call, add customer WA header to store the WA user number captured from agent entered digits (DTMF) same => n,Dial(PJSIP/1000,,b(handler^addheader^1)) same => n,Hangup() exten => c2b-sip,1,NoOp() same => n,Read(Digits,incoming_welcome,0,,5,500) same => n,Dial(PJSIP/${Digits}) same => n,Hangup()pjsip.confReplace the following placeholders with actual values {external-media-address}: Public IP of the Asterisk server for media{external-signaling-address}: Public IP of the Asterisk server for signaling{local-net}: local network of the Asterisk server{sip-ua-password}: Chosen SIP User Agent passwordNote:Extension 1000 is used to bridge WA calls with Asterisk see section Integration with Cloud API Signaling [global] type=global debug=yes ;Enable/Disable SIP debug logging.Valid options include yes|no[transport-tcp] type=transport protocol=tcp bind=0.0.0.0;External IP address to usein RTP handling external_media_address={external-media-address};External address for SIP signalling external_signaling_address={external-signaling-address};Network to consider local used for NAT purposes local_net={local-net}[endpointtemplate](!) type=endpoint context=default disallow=all allow=OPUS,g722,g729,ulaw ;No audio if direct_media isset to yes direct_media=no rtp_symmetric=yes use_avpf=yes media_encryption=sdes media_use_received_transport=yes rtcp_mux=yes [authtemplate](!) type=auth auth_type=userpass password={sip-ua-password}[aortemplate](!) type=aor max_contacts=1 remove_existing=yes [1000](endpointtemplate) disallow=all ;extension 1000is used byRtpEngine to bridge whatsapp calls ;WhatsApp only support OPUS allow=OPUS auth=1000_auth aors=1000[1000_auth](authtemplate) username=1000[1000](aortemplate)[1001](endpointtemplate) auth=1001_auth aors=1001[1001_auth](authtemplate) username=1001[1001](aortemplate)[1002](endpointtemplate) auth=1002_auth aors=1002[1002_auth](authtemplate) username=1002[1002](aortemplate)[1003](endpointtemplate) auth=1003_auth aors=1003[1003_auth](authtemplate) username=1003[1003](aortemplate)[1004](endpointtemplate) auth=1004_auth aors=1004[1004_auth](authtemplate) username=1004[1004](aortemplate)[1005](endpointtemplate) auth=1005_auth aors=1005[1005_auth](authtemplate) username=1005[1005](aortemplate) Configuring a VoIP phoneRefer to the earlier section Final checklist Double-check all configuration files for correct numbers, passwords, and domain names.Make sure your firewall allows SIP (5060/TCP) and RTP (10000-20000) ports.For more details on SIP password setup, see the WhatsApp Cloud API documentation. Troubleshooting Cannot register SIP UAConfirm that the SIP URL is correct and the domain is pointing to the Asterisk server. Run host {domain-name} to verify that the IP address points to the Asterisk server. Asterisk with built-in WebRTC using Graph APIThis approach is similar to Asterisk using Graph API with RtpEngine except that it uses the built-in WebRTC support in Asterisk and hence does not require RtpEngine.The RtpEngineClient component is hence not required in this approachIn terms of configuration and setup, only difference is the configuration of extension 1000 which is given below ...;Rest of content omitted for brevity [1000](endpointtemplate) disallow=all ;extension 1000is used by SIP UA of the integration module to bridge WhatsApp calls ;WhatsApp only support OPUS allow=OPUS auth=1000_auth aors=1000 dtls_auto_generate_cert=yes webrtc=yes ;Setting webrtc=yes is a shortcut for setting the following options:; use_avpf=yes ; media_encryption=dtls ; dtls_verify=fingerprint ; dtls_setup=actpass ; ice_support=yes ; media_use_received_transport=yes ; rtcp_mux=yes API and Webhook Reference | Developer Documentation API and Webhook Reference Updated: Nov 25, 2025 Calling API endpoints Configure or update calling settings Endpoint parameters Placeholder Description Sample Value Integer Required The business phone number for which you are updating Calling API settings. +12784358810 Parameter details: Calling status When the status parameter is set to “ENABLED”, calling features are enabled for the business phone number. WhatsApp client applications will render the call button icon in both the business chat and business chat profile. When the status parameter is set to “DISABLED”, calling features are disabled, and both the business chat and business chat profile do not display the call button icon. Updates to status will update the call button icon in existing business chats in near real-time when the business phone number is in the WhatsApp user’s contacts. Otherwise, updates are real-time for a limited number of users in conversation with the business, and are eventually updated for the rest of conversations. Parameter details: Call button icon visibility When Calling API features are enabled for a business number, you can still choose whether to show the call button icon or not by using the call_icon_visibility parameter. Note: Disabling call button icon visibility does not disable a WhatsApp user’s ability to make unsolicited calls to your business. The behavior for supported options is as follows: DEFAULT The Call button icon will be displayed in the chat menu bar and the business info page, allowing for unsolicited calls to the business by WhatsApp users. DISABLE ALL The call button icon is hidden in the chat menu bar and the business info page, and all other entry points external to the chat are also disabled. Consumers cannot make unsolicited calls to the business. Your business can still send interactive messages or template messages with a Calling API CTA button. Callback permissions Calling a WhatsApp user requires explicit permission from the user. One way to obtain calling permissions is to request permission when a WhatsApp user calls your business. You can configure the call permission UI to automatically show in the WhatsApp user’s client app when they call your business number. The user may change their permission selection at any time. Error response Possible errors that can occur:Permissions/Authorization errorsInvalid statusInvalid schedule for call_hoursHoliday given in call_hours is a past dateTimezone is invalid in call_hours weekly_operating_hours in call_hours cannot be emptyDate format in holiday_schedule for call_hours is invalidMore than 2 entries not allowed in weekly_operating_hours schedule in call_hoursOverlapping schedule in call_hours is not allowed View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Get phone number calling settings This endpoint can return information for other Cloud API feature settings. Endpoint parameters Parameter Description Sample Value Integer Required The business phone number for which you are getting Calling API settings. Learn more about formatting phone numbers in Cloud API +12784358810 App permission required whatsapp_business_management: Advanced access is required to use the API for end business clients Response details The endpoint returns Calling API settings, along with other configuration information for your WhatsApp business phone number. Learn more about Calling API settings and their values Error response Possible errors that can occur:Permissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here Pre-accept call When you pre-accept an inbound call, you allow the calling media connection to be established before attempting to send call media through the connection. When you then call the accept call endpoint, media begins flowing immediately since the connection has already been established. Pre-accepting calls is recommended because it facilitates faster connection times and avoids audio clipping issues. There is about 30 to 60 seconds after the Call Connect webhook is sent for the business to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Note: Since the WebRTC connection is established before calling the Accept Call endpoint, make sure to flow the call media only after you receive a 200 OK response back. If call media flows too early, the caller will miss the first few words of the call. If call media flows too late, callers will hear silence. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Optional The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “pre_accept” session JSON object Optional Contains the session description protocol (SDP) type and description language. Requires two values: sdp_type — (String) Required “offer”, to indicate SDP offer sdp — (String) Required The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866⁠. Learn more about Session Description Protocol (SDP)⁠ View example SDP structures Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, sdp, iceAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Accept call Use this endpoint to connect to a call by providing a call agent’s SDP. You have about 30 to 60 seconds after the Call Connect Webhook is sent to accept the phone call. If your business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Body parameters Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idError related to your payment methodInvalid Connection info, for example, sdp, ice, or other connection parametersAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errorsSDP answer provided in accept does not match the SDP answer given in the Pre-Accept endpoint for the same call-id View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Reject call Use this endpoint to reject a call. You have about 30 to 60 seconds after the Call Connect webhook is sent to accept the phone call. If the business does not respond, the call is terminated on the WhatsApp user side with a “Not Answered” notification and a Terminate Webhook is delivered back to you. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Optional The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “reject” Error response Possible errors that can occur:Invalid call-idInvalid phone-number-idAccept/Reject an already In Progress/Completed/Failed callPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Initiate call Use this endpoint to initiate a call to a WhatsApp user by providing a phone number and a WebRTC call offer. Body parameters Error response Possible errors that can occur:Invalid phone-number-idPermissions/Authorization errorsRequest format validation errors, for example connection info, sdp, iceSDP validation errors View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Terminate call Use this endpoint to terminate an active call. This must be done even if there is an RTCP BYE packet in the media path. Ending the call this way also ensures pricing is more accurate. When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, a Call Terminate Webhook will be sent to you. Body parameters Parameter Description Sample Value call_id String Required The ID of the phone call. For inbound calls, you receive a call ID from the Call Connect webhook when a WhatsApp user initiates the call. “wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh” action String Required The action being taken on the given call ID. Values can be connect | pre_accept | accept | reject | terminate “terminate” Error response Possible errors that can occur:Invalid call idInvalid phone-number-idThe WhatsApp user has already terminated the callReject call is already in progressPermissions/Authorization errors View Calling API Error Codes and Troubleshooting for more information. View general Cloud API Error Codes here. Get current call permission state Use this endpoint to get the call permission state for a business phone number with a single WhatsApp user phone number. Request parameters Parameter Description Sample Value String Required The business phone number you are fetching permissions against. Learn more about formatting phone numbers in Cloud API +18762639988 Integer Required The phone number of the WhatsApp user who you are requesting call permissions from. Learn more about formatting phone numbers in Cloud API +13057765456 Error response Possible errors that can occur:Invalid phone-number-idIf the consumer phone number is uncallable, the api response will be no_permission.Permissions/Authorization errors.Rate limit reached. A maximum of 5 requests in a 1 second window can be made to the API.Calling is not enabled for the business phone number. View Calling API Error Codes and Troubleshooting for more information View general Cloud API Error Codes here SDP overview and sample SDP structures Session Description Protocol (SDP) is a text-based format that describes multimedia session characteristics, such as voice and video calls, in real-time communication applications. SDP provides a standardized way to convey information about the session’s media streams, including the type of media, codecs, protocols, and other parameters necessary for establishing and managing the session. In the context of WebRTC, SDP is used to negotiate the media parameters between the sender and receiver, enabling them to agree on the specifics of the media exchange. Business-initiated sample SDP structures Sample SDP offer structure v=0 o=-36261663187458529552 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE 0 a=extmap-allow-mixed a=msid-semantic: WMS d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e m=audio 9 UDP/TLS/RTP/SAVPF 11163908110126 c=IN IP4 0.0.0.0 a=rtcp:9 IN IP4 0.0.0.0 a=ice-ufrag:4g1c a=ice-pwd:qY/Bb+jQzg5ICn6X4fhJQetk a=ice-options:trickle a=fingerprint:sha-25635:47:24:24:9F:93:C4:3E:DB:37:7F:BB:ED:F8:20:B5:AD:AC:DC:35:C2:7D:67:EE:6C:35:54:DF:A6:00:5C:4A a=setup:actpass a=mid:0 a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01 a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid a=sendrecv a=msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc a=rtcp-mux a=rtpmap:111 opus/48000/2 a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1 a=rtpmap:63 red/48000/2 a=fmtp:63111/111 a=rtpmap:9 G722/8000 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:110 telephone-event/48000 a=rtpmap:126 telephone-event/8000 a=ssrc:2220762577 cname:w/zwpg3jXNiTFTdZ a=ssrc:2220762577 msid:d8b26053-4474-4eb7-b3c3-c93d6c8c9b2e 5b4d3d96-ea9b-44a8-87e6-11a1ad21a3bc Sample SDP answer structure v=0 o=-7418078391020537252 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE 0 a=extmap-allow-mixed a=msid-semantic: WMS 798a9670-c0d6-47a8-925e-5f082ef4d8a0 a=ice-lite m=audio 3482 UDP/TLS/RTP/SAVPF 111908110126 c=IN IP4 31.13.65.130 a=rtcp:9 IN IP4 0.0.0.0 a=candidate:27549362801 udp 211393715131.13.65.1303482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8 a=candidate:15814963991 udp 21139397112a03:2880:f211:d1:face:b00c:0:699c3482 typ host generation 0 network-cost 50 ufrag JHqAXFH4HcAY/8 a=ice-ufrag:JHqAXFH4HcAY/8 a=ice-pwd:dNNMmR8wUcGezvfBZOO0Qgcwl2m86GP/ a=ice-options:trickle a=fingerprint:sha-2569C:97:5C:4C:A9:BE:9E:2F:06:94:F5:BB:38:2C:A1:29:B5:69:B8:FA:94:10:56:1D:0B:5D:80:28:C1:FD:F0:F6 a=setup:active a=mid:0 a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01 a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2 a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1 a=rtpmap:9 G722/8000 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:110 telephone-event/48000 a=rtpmap:126 telephone-event/8000 a=ssrc:3407645770 cname:bg8KQDoIk2UJa6sf a=ssrc:3407645770 msid:798a9670-c0d6-47a8-925e-5f082ef4d8a0 audio#nuxVMf9EAJX a=ssrc:3407645770 mslabel:798a9670-c0d6-47a8-925e-5f082ef4d8a0 a=ssrc:3407645770 label:audio#nuxVMf9EAJX User-initiated sample SDP structures Sample SDP offer structure v=0 o=-76025637897899450802 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS 6932bc1c-db1a-4abe-b437-0c4168be8a13 a=ice-lite m=audio 40012 UDP/TLS/RTP/SAVPF 111126 c=IN IP4 31.13.65.60 a=rtcp:9 IN IP4 0.0.0.0 a=candidate:19726373201 udp 211393715131.13.65.6040012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2 a=candidate:16522627911 udp 21139397112a03:2880:f211:cf:face:b00c:0:644340012 typ host generation 0 network-cost 50 ufrag 6k2qP1R6kBfI/2 a=ice-ufrag:6k2qP1R6kBfI/2 a=ice-pwd:UApvJw3NcwFRDvIMKdM0vWCdlXah25E9 a=fingerprint:sha-2561B:B6:6B:40:A5:0B:8C:75:0D:8C:CB:90:2F:99:74:1E:26:45:AE:AF:45:C1:51:60:8F:73:C9:2D:10:6D:8A:88 a=setup:actpass a=mid:audio a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01 a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2 a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=ssrc:4208138518 cname:gAXq2V9TKltrnapv a=ssrc:4208138518 msid:6932bc1c-db1a-4abe-b437-0c4168be8a13 audio#R5wfXFcdmT6 a=ssrc:4208138518 mslabel:6932bc1c-db1a-4abe-b437-0c4168be8a13 a=ssrc:4208138518 label:audio#R5wfXFcdmT6 Sample SDP answer structure v=0 o=-28226442481446439332 IN IP4 127.0.0.1 s=- t=00 a=group:BUNDLE audio a=msid-semantic: WMS eb909cf0-87f0-4358-a4c9-7861680d9431 m=audio 9 UDP/TLS/RTP/SAVPF 111126 c=IN IP4 0.0.0.0 a=rtcp:9 IN IP4 0.0.0.0 a=ice-ufrag:X1ho a=ice-pwd:7fJSbV2N5qWiA5QiDKwK3vuh a=fingerprint:sha-2562E:35:9F:21:9E:63:72:E5:42:74:76:2D:B3:70:F7:CB:24:14:9B:14:52:71:05:48:DA:4D:67:31:09:58:2A:ED a=setup:active a=mid:audio a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01 a=sendrecv a=rtcp-mux a=rtpmap:111 opus/48000/2 a=rtcp-fb:111 transport-cc a=fmtp:111 minptime=10;useinbandfec=1 a=rtpmap:126 telephone-event/8000 a=ssrc:330833028 cname:EDc1JutBl8rwHQc2 a=ssrc:330833028 msid:eb909cf0-87f0-4358-a4c9-7861680d9431 ea478c16-d9f7-493c-8cec-19bfac750a36 Sample call connect webhook Call connect webhook Troubleshoot WhatsApp Calling Errors - Reference Guide | Developer Documentation Troubleshoot WhatsApp Calling Errors - Reference Guide Updated: Dec 3, 2025 Standard error response When you receive an error, in the majority of cases the error shape will look like this: Use the Calling API error codes list below to identify and resolve calling errors. Calling logs The Call Logs tab in WhatsApp Manager⁠ provides businesses and partners with a detailed, self-service view of call events to aid in call troubleshooting. The tab displays a table of recent call logs for your business phone numbers. Each call has a log. Each log can have multiple events representing a Graph API request made by the business or a webhook sent by Meta. Each row represents a call, with different columns highlighted to provide information about each call log. How to view call logs Navigate to WhatsApp Manager > Account tools > Phone numbers⁠Select the desired phone number to view the call logs Call logs and events Field Description Timestamp Timestamp of when the call occurred. Call Direction Outbound (Business-initiated) or Inbound (User-initiated). Signaling Signaling Protocol used to establish the call (SIP, GRAPH_API). Call ID WhatsApp call identifier. Note: Please provide this ID when requesting support. Request ID Identifier for the request that initiated the call. Call Details Additional information containing a log of events during the lifecycle of the call. Calling error codes Code Description Possible Solutions HTTP Status Code 100 Invalid Parameter The Graph API call you are making has an invalid parameter. Exact error details will be listed in the error_data section of the response payload. If it’s an SDP validation related error then the exact issue will be included in the details. 400 Bad request 613 Fetch Call Permission For Consumer Phone Number API Limit Hit Limit reached for requests to the fetch call permission status API. Try again later or reduce the frequency or amount of requests to the API the app is making. 429 Too many requests 131009 Interactive Message type, voice_call not supported. Supported types [ button, list] Ensure the sender is in one of the supported countries. 400 Bad request 131030 Recipient phone number is not in allowed list. The error is thrown for both attempted calls and call permission requests. Only occurs when using public test numbers (PTNs). Add a recipient phone number to recipient list and try again. 400 Bad request 138000 Calling not enabled Calling APIs are not enabled for this phone number Calling is not enabled on the business phone number. Configure call settings to enable Calling API features 401 Unauthorized 138001 Receiver Uncallable Receiver is unable to receive calls Reasons can include: The recipient phone number is not a WhatsApp phone number.The recipient has not accepted our new Terms of Service and Privacy Policy.Recipient using an unsupported client. The currently supported clients are Android, iOS, SMB Android and SMB iOS Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp. 400 Bad Request 138002 Concurrent Calls limit Limit reached for maximum concurrent calls (1000) for the given number Try again later or reduce the frequency or amount of API calls the app is making. 429 Too many requests 138003 Duplicate call A call is already ongoing with the receiver Try again later when the current call ends. 400 Bad request 138004 Connection error Error while connecting the call Try again later or investigate the connection params provided to the API. 500 Server error 138005 Call rate limit exceeded Limit reached for maximum calls that can be initiated by the business phone number Try again later or reduce the frequency or amount of API calls the app is making. 429 Too many requests 138006 No approved call permission found No approved call permission from the recipient Ensure a call permission has been accepted by the consumer 401 Unauthorized 138007 Connect Timeout error Call was unable to connect due to a timeout Business did not apply the offer/answer SDP from Cloud API in time. Connect API was not invoked with the answer SDP in time 500 Server error 138009 Call Permission Request Limit Hit Limit reached for call permission request sends for the given business and consumer pair When a business sends more than the limit of call permission requests per time period, Call Permission Requests are rate limited. A connected call with a consumer will reset the limits. 400 Bad request 138012 Business Initiated Calls Limit Hit Limit reached for maximum business initiated calls allowed in 24 hours. Currently 100 connected business initiated calls are allowed within 24 hours. Exact error details will be listed in the error_data section of the response payload. Details will include a timestamp when the next call is allowed. 400 Bad request 138013 Business-initiated calling is not available Business-initiated calling is not available for this business account phone number. Confirm that Business Initiated calling is available for this business account phone number in the availability section here. 400 Bad request 138014 Calling is temporarily disabled Calling APIs for this WhatsApp Business Number have been temporarily disabled for having low quality. Ensure that your outreach to users is valuable and not spam. Retry the action after the account restrictions are lifted. 400 Bad request 138015 Calling cannot be enabled Calling APIs cannot be enabled for this phone number. Check and make sure messaging limit on your phone number is 2000 or more 400 Bad request 138017 Call permission request can’t be sent because a permanent permission already exists. Call permission request cannot be sent because a permanent permission has already been approved by the user for this business account phone number. No need to send call permission requests. 400 Bad request 138018 WhatsApp Business calling cannot be enabled because technical pre-requisites are not met. See prerequisites for more details Configure SIP or ensure there is at-least one app subscribed to the WhatsApp Business Account that also has subscription to the calls webhook field. 400 Bad request 138019 Call setup failed The WhatsApp client failed to set up the call. This error is sent in the call terminate webhook. Try again later. 400 Bad request 138020 Relay connection failed The WhatsApp client failed to establish a connection with the relay server. This error is sent in the call terminate webhook. Try again later. 400 Bad request 138021 Media receive timeout The WhatsApp client terminated the call due to not receiving any media for a long time. This error is sent in the call terminate webhook. Confirm that call media is being sent to the relay and try again. 400 Bad request 138022 Media transmit timeout The WhatsApp client terminated the call due to not transmitting any media for a long time. This error is sent in the call terminate webhook. Try again later. 400 Bad request 138023 Call accepted but terminated with no media signals The call was accepted but terminated with no media connection signals. Cloud API could not determine if the call was connected. This error is sent in the call terminate webhook. Try again later. 400 Bad request 131044 An error webhook is sent on user initiated calls when there is no valid payment method attached This is similar to the “Business eligibility payment issue” error in messaging. 400 Bad request 131055 Method not allowed. Graph API calls are not allowed for SIP enabled numbers Use SIP for SIP enabled business numbers. 400 Bad request SIP errors Also refer to SIP specific FAQ for additional troubleshooting info Business initiated calls SIP status and message Description Possible Solutions 400 Asset not found, invalid business phone number The phone number in the From header of the INVITE is invalid and does not correspond to a registered account on WhatsApp Business Platform Check the phone number and resend the INVITE with the correct From header value. See examples 403 SIP server foo.com from INVITE does not match any SIP server configured for phone number id [ID] Your SIP INVITE to Meta has ‘foo.com’ in the From header (for example, 15555551234@foo.com). But there is no SIP server with that hostname configured on the business phone number. Check your SIP configuration and ensure it matches the domain used in the From header. The hostname in the SIP configuration should match the domain in the From header of your SIP INVITE. It is also valid for the SIP configuration hostname to be a sub-domain of the domain in From header. For example, SIP server configured is bar.foo.com and the From header is 15555551234@foo.com 403 No Approved Call Permission Found: No approved call permission from the recipient There is no WhatsApp user with specified number or user has not accepted our new Terms of Service or there is no permission from user to call the business. Meta can’t reveal if a phone number is on WhatsApp with certainty, due to privacy reasons. So this is the same error you’ll receive for multiple reasons. Double check the user phone number and make sure you obtain the user permission. See Obtain User Call Permissions for more information 403 The app [APP_ID] configured for SIP server example.com is not authorized for phone number id [ID] When you configure SIP server on a business phone, Meta extracts the app id from the access token and stores a mapping from the SIP server to that app id. When you send a SIP INVITE, Meta consults that mapping to know which app is making the SIP request. This error means that app does not have whatsapp_business_messaging permission on the business phone. Check that you are using the right app and make sure it has permissions on the business phone. If you’re able to send message using the app’s access token, that means the app has the right permission. Otherwise you may need to delete and add your SIP server with the correct app and retry your SIP INVITE. See Configuring SIP settings. 403 Business Initiated Connected Call Per Day Limit Hit Limit reached for maximum business initiated calls allowed in 24 hours. Currently 5 connected business initiated calls are allowed within 24 hours. See more info about the limits and adjust your calling rate accordingly 403 Additional reasons for 403 include Duplicate call because there can be only one active between a given business and user accountInvalid digest auth responseBusiness eligibility payment issueSDP Validation Error Read each error for details Consult earlier sections in this page like Calling error codes 404 Not found SIP INVITEs using IP in request URI are not allowed Use the correct request URI. See examples 407 Proxy Authentication Required Meta mandates digest authentication for your SIP INVITEs and this is the standard challenge response from Meta Resend the SIP INVITE with digest response. See examples 408 RTP Timeout The WhatsApp client terminated the call due to not receiving any media for a long time. See Media related issues 480 Temporarily Unavailable WhatsApp user is not reachable or did not answer the call Try messaging or calling later. Unanswered calls impact call permissions. Learn more 486 User declined the call WhatsApp user declined your call Try messaging or calling later. Rejected calls impact call permissions. Learn more 487 Request Terminated Business canceled their SIP INVITE using SIP CANCEL Expected return for your SIP INVITE when you CANCEL the INVITE before Meta response to your INVITE 503 Service Unavailable Generic internal error. Retry your request after some time or consult Meta support Media related issues Issue Description Possible Solutions Call disconnects after 20 seconds into the call At the start of the call, if there is no media flowing from business to WhatsApp user for 20 seconds, WhatsApp client will disconnect the call due to no media Check your media server to make sure it’s initiating the media session and sending media packetsCheck your firewall to rule out any packet drops at your edgeCapture network traffic using pcap or a similar tool and attach it to the support ticket for further troubleshooting by Meta Can’t hear audio and call disconnects after 30 seconds After the call is connected and established, if there is no media packet from business to WhatsApp user for 30 seconds, WhatsApp client will disconnect the call due to no media reception Make sure you’re at-least sending RTCP packets even when there is silence or when you are waiting for user input (for example, IVR)Check your media server to understand why it stops sending media packets to MetaCapture network traffic using pcap or a similar tool and attach it to the support ticket for further troubleshooting by Meta Audio clipping issue and solution When bridging the WhatsApp Consumer media leg via WebRTC to another media leg, such as SIP⁠, it’s important to be aware of potential audio clipping issues and how to prevent them. A common symptom of this issue is that the WhatsApp consumer may miss approximately one second of audio from the business. For instance, if an IVR system is playing a sequence like “1-2-3,” the consumer might only hear “2” or “3.” The extent of audio loss varies based on the specific integration and the severity of the issue. The sequence diagram below illustrates this problem using an example where the WebRTC leg from the Cloud API is bridged with a SIP media leg. Depending on the SIP vendor and implementation, the media from the SIP User Agent might start playing at step 11, but it won’t reach the WhatsApp consumer until step 18. Sequence diagram (Right click image and choose “Open in new tab” for enlarged image) Components of the sequence diagram WAConsumer is a WhatsApp user calling the business phone number using WhatsApp mobile appMeta is the Cloud API productMetaWebrtcEndpoint is the WebRTC agent on the Meta infrastructureBizIntegration is the webhook server receiving calls related webhooks and the app server with business logic to invoke Cloud API Graph APIsBizWebrtcEndpoint is the WebRTC termination point as well as the SIP UAC typically in a media server on your side.BizSipEndpoint is the SIP User Agent (UA) often representing IVR or Business Agent. Key points to note Upon receiving the connect webhook (step 5 above), initialize your WebRTC agent, prepare the SDP answer, and make the Pre-accept Graph API call with the SDP answer. This pre-establishes the WebRTC connection in anticipation of an ‘accept/ok’ response from the SIP User Agent (UA). In most cases, the consumer’s call is answered, such as by an automated recording or IVR system.At step 11 above, wait for the ICE process to complete the creation of valid lists, indicating the near completion of ICE connection establishment (RFC reference).If the SIP UA rejects the call instead of returning a 200 OK, use the terminate Graph API to end the call.If the consumer connection is ready before the SIP connection, the consumer may experience a few milliseconds of silence, which is preferable to losing some initial audio from the business. Root cause When bridging two media legs, it’s crucial for the media server to synchronize their readiness to prevent audio clipping. In this scenario, the BizWebrtcEndpoint is allowing the SIP User Agent (UA) to transmit media significantly earlier than the WebRTC leg is prepared to receive it. As a result, packets are being dropped at the media server, leading to audio clipping issues. Suggested solutions Below is a high-level summary of alternative approaches to address audio clipping, intended to stimulate discussion and consideration. While each option has its drawbacks, you can assess their feasibility in the context of your specific requirements. Use SDES: Configure SDES on your business number instead of DTLS. A common reason for delayed setup of the media leg between your infrastructure and Meta is DTLS handshake completion. Meta cannot complete DTLS handshake until it receives your SDP. You may not be able share your SDP with Meta until your internal endpoint responds to your with their SDP. Common DTLS implementations have a retry interval of 1s, 2s, 4s, and so on. After you send Meta the SDP, there is often a ~3 second delay before we receive your DTLS client hello packet and this is when your internal endpoint is sending media but it is dropped. When you switch to SDES you can directly send SRTP after you send us your SDP.Delayed Audio Playback: Instruct the SIP User Agent (UA) to wait for an ACK from BizWebrtcEndpoint before playing audio. The ACK would be sent only after receiving a successful response from the Accept API, followed by an artificial delay. This approach ensures that the WebRTC connection is established before audio playback begins.Connection State-Based Delay: Direct the SIP UA to wait until the WebRTC connection state is ‘connected’ before playing audio. This method relies on the WebRTC connection being fully established before audio playback starts.Buffered Media Packets: Buffer SIP media packets and send them only after the WebRTC connection is established. This approach ensures that no audio packets are lost due to premature playback.Silence Insertion: Insert a brief period of silence into the IVR audio before the actual audio content. This method allows the WebRTC connection to establish itself while the IVR is playing silence, reducing the likelihood of audio clipping.Pre-accept: According to the RFC recommendation⁠, a WebRTC agent, such as BizWebrtcEndpoint, should not transmit media until the ICE process is nearly complete. In our context, this means adopting an ‘optimistic accept’ strategy by invoking the pre-accept API call even before sending the SIP INVITE. According to SIP RFCs, a User Agent Client (UAC) should be prepared to receive media immediately after sending the INVITE. Therefore, it’s advisable to initiate the WebRTC connection setup process prior to sending the SIP INVITE. These solutions may have varying degrees of complexity and impact on your system. It’s essential to evaluate their feasibility and potential trade-offs in the context of your specific use case. Support For support concerning WhatsApp Business Calling API, choose the WaBiz: Calling API topic when opening a Direct Support⁠ ticket. Set Up a Sandbox Account for Calling | Developer Documentation Set Up a Sandbox Account for Calling Updated: Oct 31, 2025 Sandbox accounts are only available to you if you are a Tech Partner. Overview A WhatsApp sandbox account is a mock WhatsApp Business Account that you can use to test your Calling API integration. Use a calling sandbox account to test the following features:Initiate and receive calls using the Calling APIValidate calling webhook eventsSimulate onboarding flows without creating real business assets Sandbox account calling limits The following table outlines the calling limits for sandbox accounts. These limits are subject to change. Limit Description Production number limit Public test number limit Connected call limit Number of calls a business is allowed to make on approved permissions. 100 connected calls per 24 hrs No change Call Permission Request message limits Limits the number of call permission request messages that can be sent to the same consumer 1 request per day 2 requests per week 25 requests per day 100 requests per week Unanswered call limits When a business initiated call goes unanswered (In essence, is rejected by the user or missed by the user). Nudge on 2 consecutive unanswered calls Revoke permission on 4 consecutive unanswered calls Nudge on 5 consecutive unanswered calls Revoke on 10 consecutive unanswered calls Temporary call duration Duration a business can call the user after permission is approved. 7 days No change Set up a sandbox account Step 1. Access the WhatsApp developer sandboxNavigate to the App Dashboard.Click the app you are using with WhatsApp.Select Use cases (pencil icon) from the sidebar.Under Connect with customers through WhatsApp, click Customize.In the left menu, select Partner tools.In the Claim a sandbox account section, under Features, click the dropdown. Select Cloud API and Calling.Click Claim sandbox account.Under Enable calling functionality click the dropdown, then click Manage phone number list.Add your phone number as a recipient. Step 2. Obtain credentials and identifiers for your sandbox accountOn the same page, under Customize a new onboarding flow, click Get started to open the Embedded Signup experience. Note: Keep this tab open and available as you will use it multiple times throughout this process.In the Embedded Signup Launch section, ensure that the Features dropdown is empty, then click Login with Facebook.A popup with the embedded signup experience will show. Under Business portfolio select Sandbox Business.Fill in the rest of the required information, then click Next.On the next screen, in the Create or Select a WhatsApp Business Profile dropdown, select Test Number.Once the login flow is complete, in the Exchange Token section, click Get Token. Note: Retain this token for future sandbox account API use.In the Fetch Shared WhatsApp Business Account section, click Fetch WABA details.Under WhatsApp business account field, copy the Value for the id row. Note: Retain this ID since it is the WhatsApp Business Account ID for the sandbox WABA.In the Fetch phone numbers section, click Fetch phone numbers.Under ID, copy the value. Note: Retain this ID since it is the phone number ID for your sandbox account test phone number. Step 3. Register your test phone number and subscribe to your WABA Prerequisites Ensure that you have the following information from the previous steps:Your sandbox account token stringYour sandbox account WABA IDYour test phone number ID To complete these next steps, you will use the Graph API Explorer tool.Note: Keep this window open as you will use the configuration you created again in later steps in this guide. Navigate to the Graph API Explorer tool.Ensure you are on the latest version of the API.Click Generate Access Token and follow the prompts.Under Permissions, add the whatsapp_business_management and whatsapp_business_messaging permissionsIn the endpoint builder, enter //subscribed_apps, then click Submit. Next, register your test phone number by entering //register in the endpoint builder.In the left sidebar, click JSON, then enter the following JSON body, then click Submit: You should receive a standard success response: Step 5. Configure webhooks and permissionsNavigate to the App Dashboard.Click the app you are using with WhatsApp.Select Use cases (pencil icon) from the sidebar.Under Connect with customers through WhatsApp, click Customize.In the left sidebar, click Configuration.Under Callback URL, add the callback URL for your webhook server. If you do not have a webhook server, you can follow our instructions to create a test webhook server.Under Verify token, add an arbitrary verification string.Click Verify and save.On the next page, in the Select product dropdown, click WhatsApp Business Account.Under Webhook fields, in the calls row, click the toggle button to subscribe to the calls webhook field. Test business-initiated calling Before you can test business-initiated calls (BIC), you must provide user calling permissions to your sandbox account. You can do this on the client device you are using for testing:On your client device, open WhatsApp.Navigate to the message thread you have with your sandbox business phone number.At the top of the screen, tap the sandbox business phone number.Scroll down and tap Business Calling Permission.Tap Allow calls. You can now use your Calling API integration to call the client device and test your integration. Learn more about how to make business-initiated calls. Test user-initiated calling You can test user-initiated calls (UIC) on the client device you are using for testing:On your client device, open WhatsApp.Navigate to the message thread you have with your sandbox business phone number.Tap the phone icon at the top of the screen to call the sandbox business phone number.Confirm a successful call connection. Learn more about how to handle user-initiated calls. Calling API App Review Guidelines | Developer Documentation Calling API App Review Guidelines Updated: Nov 21, 2025 Overview The official page referenced by reviewers is /docs/permissions#w. Use this guide as complementary to that page but treat that page as the official source when in doubt. This page provides details to improve your chances of a successful App Review specifically for WhatsApp Business Calling API features. Guidelines For the WhatsApp business management permission You should clearly show that your application can enable and disable calling features by displaying whether the Call Button icon is visible. Do this by enabling and disabling calling features, not simply toggling Call Button icon visibility.Learn how to enable and disable Calling API features via APILearn how to enable and disable Calling API features in WhatsApp Manager For the WhatsApp business messaging permission You should clearly demonstrate your application can support either of the following use cases: Use case 1: Place a business-initiated call Share a video of you using your application to place a business-initiated call. Then display a user accepting the call on a WhatsApp mobile client. Use case 2: Receive a user-initiated call Share a video of a user placing a call to your business phone number. Then show your application receiving the incoming call. Show either:The incoming call in the WhatsApp client application UI.The calling webhook as delivered to your application. Calling API Pricing | Developer Documentation Calling API Pricing Updated: Mar 30, 2026 All user-initiated calls are free. Overview Businesses are charged for calls based on:Duration of the call (calculated in six-second pulses)Country code of the phone number being calledVolume tier (based on minutes called within the calendar month) using same tiering accrual as messaging Note: Our systems count fractional pulses as one pulse. For example, a 56-second call (9.33 pulses) would be counted as 10 pulses. For calls that cross pricing tiers (for example from the 0 - 50,000 tier to the 50,001 - 250,000 tier), the entire call is priced at the lower rate (that is, the rate of the higher volume tier). A valid payment method is required to place calls. Note: Call permission request messages are subject to per-messaging pricing. Rate cards and volume tiers These rate cards represent the current rates and volume tiers for the WhatsApp Business Calling API, effective April 1, 2026, based on WhatsApp Business Account timezone. Currency Rates USD USD rates AED AED rates ARS ARS rates AUD AUD rates CLP CLP rates COP COP rates EUR EUR rates GBP GBP rates IDR IDR rates INR INR rates MXN MXN rates MYR MYR rates PEN PEN rates SAR SAR rates SGD SGD rates Updates to rate cards Previous updatesEffective April 1, 2026 – 8 new billing currencies introduced: AED (United Arab Emirates), ARS (Argentina), CLP (Chile), COP (Colombia), MYR (Malaysia), PEN (Peru), SAR (Saudi Arabia), SGD (Singapore).Effective January 1, 2026 – MXN (Mexico) rates introduced. How calling changes the 24 hour customer service window Currently, when a WhatsApp user messages you, a 24-hour timer called a customer service window begins, or refreshes. When you are within the window, your business can send any type of message to the WhatsApp user, which is otherwise not allowed. With the introduction of the Calling API, the customer service window now also starts or refreshes for calls:When a WhatsApp user calls you, regardless of if you accept the call or notWhen a WhatsApp user accepts your call. Get cost and call analytics You can call the endpoint with a ?fields=call_analytics query parameter to obtain call analytics for your WhatsApp Business Account (WABA). The endpoints can provide useful information like cost, counts of completed calls, and average call duration. Learn more about call analytics. FAQs | Developer Documentation FAQs Updated: Nov 13, 2025 Product FAQ Will calls show up in the insights page on Meta WhatsApp Manager UI? Call insights will be available in both WhatsApp Manager and the analytics API. Are International calls supported like WhatsApp consumer to consumer calls? Yes. What are the countries supported for calling? See Calling Availability for more info. Can I use toll-free numbers for calling? Yes, as long as the country code for the toll-free number is in the list of supported countries. See 1-800 and toll free numbers for details on how to register toll-free numbers on Cloud API. What is the max number of concurrent calls that a single Cloud API account phone number can receive? Max concurrent calls is 1000. When the rate limit is exceeded, the caller (the WhatsApp user) will get a generic message saying call cannot be placed. No message is played and there is no webhook. This limit is expected to increase and hence chances of this happening are low. Note that the rate limits for messaging API and template creation/update API are separate and unrelated to calling limits. What is the role of BSP vs. end business in overall call flow?The BSP offers value-added services (for example contact center, voice recording, transcription, and so on) on top of the raw audio stream provided by Cloud API Calling.The webhook is sent to apps subscribed for the new calls subscription field. In typical cases, a BSP uses their own app and receives the call webhook followed by call establishment.How the end-business participates in the call is determined by the BSP. Is the voice infrastructure/API for WhatsApp the same for Facebook Messenger? WhatsApp Calling API is the first public voice API by Meta. Meta may reuse the same API and integration model for other Meta products when and if they offer voice solutions. What is the maximum call duration supported? There is no call duration limit. Is SIP supported? Yes, see “Configure and use call signalling via session initiation protocol (SIP)” Can I send/receive text/media messages while a call is in progress? Yes. The regular send-message API can be used while a call is in progress. Does Meta offer services such as voice recording, transcript, voice-mail? No. Can I add metadata (for example context) as part of accepting the call? Yes. See biz_opaque_callback_data field in the main API spec. Also the existing conversation state provides important context to the business human agent. The call routing subsystem should directly connect the call from WhatsApp consumer to the right agent on the business side. This gives the best customer experience and avoids going through standard IVR How can I raise awareness of the calling feature to WhatsApp users?Send messages with voice call buttons. See send interactive message and send template message sections for detailsSend a message with a voice call button automatically when a WhatsApp consumer opens a chat with the business account for the first time. See welcome message for more details.Link to a WhatsApp call from a website using deeplinks. Is it possible for an AI (for example voicebot) to have a conversation with a customer directly via a WhatsApp call? Yes. Meta only provides the raw media stream and how it is processed is entirely flexible. Many businesses use automated voicebots including AI bots to answer calls from WhatsApp users. Many AI products in the market offer RTC / Speech APIs and some even have native WebRTC support. The integration approach is similar to integrating WhatsApp Business Calling with call centers for IVR or human agents. See WhatsApp Business Solution Terms⁠ for restrictions in AI use cases. Why is pre-accepting user initiated call starting the timer on WhatsApp user side? Likely because media is being sent before the call is accepted. WhatsApp clients treat a call as accepted by peer if they receive a media packet or an accept signal whichever comes first. If the timing of media start cannot be controlled, directly accept the call and do not use pre-accept. The pre-accept is meant to frontload media connection establishment but it does require controlling the timing of media transmission. Is there a status page to track overall health of Calling APIs and view any outages or service incidents? Yes. See ‘Cloud API Calling’ section at https://metastatus.com/whatsapp-business-api and https://metastatus.com/whatsapp-business-api/history Getting Started FAQ What is the minimum Graph API version for the Calling APIs? It is v17.0. See here for general version history Can I use the same user access token for messaging, for calling? Yes. Whatever works for messaging should work for calling in general. Does the WABA need to have an attached credit line for using Calling APIs? Yes, a credit line attached to the WABA is required in order to use the Calling API. Does the WABA need to be a verified business for calling? No. Business verification⁠ is not a requirement for calling, nor is it required for messaging How does usage of Calling APIs affect my rate limits? Calling API usage does not count towards messaging rate limits at the moment. The only limit enforced for calling right now is the 1000 concurrent calls limit, but this may change in near future. Is it possible for a WhatsApp Business account be connected to Provider A for Chat and to Provider B for Voice (i.e., two different apps subscribed to the same WhatsApp business Webhook account/phone)? Yes, it is possible for two partners to operate a single WhatsApp Business API phone number with two separate solutions, like chat and calling. See Multi-Solution Conversations for more details. Another option is for the voice provider used by another BSP. In this case a Meta app or being a tech provider on Meta is not needed. This architecture is depicted in detail in the section “Integrating using a third party voice provider”. Graph API Call Signaling FAQ Does Meta provide any stun/turn servers or WebRTC infra for use by BSP? No. Meta uses ICE-lite⁠ and the Meta SDP offer always has a single ipv4 and ipv6 address per data stream component. The SDP answer should follow the same format. As such it is not mandatory to use STUN/TURN to determine the ICE candidates Does Meta recommend any stun/turn servers or WebRTC infra for use by BSP? Meta doesn’t have recommendations. Here are a few ideas just as food for thought in case they are helpful.Check for any existing VoIP related technology and if so, consult that team. WebRTC relies on SRTP/SRTCP for actual media which is the VoIP media standard.Using STUN/TURN works well in an end user setup with a browser from a personal device. If the integration with the Meta voice APIs involves terminating the media directly on an end user device, the STUN/TURN, and so on, happen directly on that user device. But often, the media does terminate in a partner’s own infra so services like IVR can be offered. In such cases, the BSP infra may have its own ways to allocate an IP and port for VoIP connections, for example using VIP behind a load-balancer, and so on. What ICE role should the ICE agent on the business side take? Always take the CONTROLLING role as the Meta side ICE agent uses ICE-lite (RFC 8445⁠). Starting with the CONTROLLED role may cause the ICE process to stall and timeout. Even if it does work, it will take more time due to multiple round-trips needed to resolve role conflicts. Can more ICE candidates be added as part of signaling in offer + answer (for example using ICE Trickle)? Short answer is yes. Cloud API uses ICE-lite (RFC 8445)⁠ and always assumes the controlled role⁠ in ICE. Hence there is no need to send updated candidates to Meta. The ICE Agent can initiate connectivity checks from addresses not included in the SDP and the Meta ICE agent will consider unknown address as a valid candidate, as long as STUN message integrity passes. What is the recommendation on how to determine the ICE candidate? Meta has global infra presence and Meta will choose the media relay on Meta infra that is closest to the WhatsApp user involved in the call. On the BSP side, the media server/host (aka targeting) can be chosen based on many parameters including the IP Meta chooses, the country of consumer phone number, and the business phone number. The selection of media server location is an important factor in optimizing the media latency between BSP IP and Meta IP which in turn contributes to higher call quality. At the minimum, the BSP call/media hosting location should be close to the country of the WhatsApp user as determined from the country code of the user’s phone number. Any targeting implementation on the BSP side should optimize for the candidates IPs on the Meta SDPs and not on the source of signaling endpoints. Is there an API to send a provisional response equivalent to SIP 180 Ringing? If not, when does the caller’s device start ringing? Caller (the WhatsApp Consumer app) would already be ringing by the time the webhook is received. There is no need for provisional responses How are the calls secured? Cloud API uses SRTP for the encryption of media streams (RTP/SAVPF)⁠ and the actual SRTP key exchange is initially performed end-to-end with DTLS-SRTP⁠. Can Meta send the call webhooks to a different endpoint based on the caller’s geographical location or other factors such as network latency? The webhook URL is configurable. HTTPS is used, so standard load balancing and targeting techniques can be applied to reroute accordingly. A different (aka override or alternate) webhook URL can also be configured per WhatsApp Business Account and per business phone number. The webhook is only used for signaling and Meta servers calling the webhook server are located in US. Select the location of the media endpoint based on the country code of the WhatsApp consumer (available on the webhooks) or the ice candidate IPs on SDP sent by Meta. See the above FAQ questions “What is the recommendation on how to determine the ICE candidate?” and “How to reduce media latency of the calls?” . What are the Meta IP addresses that will call the Webhook or SIP or Media servers in order to allowlist them in a firewall? Refer to the WhatsApp Webhooks documentation on this topic. When collapsing the list of IPv4 addresses the result is around 23 prefixes. See below for an example command and output that was run as of December 11, 2024. $ src % whois -h whois.radb.net — '-i origin AS32934' | grep ^route | awk '{print $2}' | grep -iv ':' | cidrmerge 31.13.24.0/21 31.13.64.0/18 45.64.40.0/22 57.141.0.0/21 57.141.8.0/22 57.141.12.0/23 57.144.0.0/14 66.220.144.0/20 69.63.176.0/20 69.171.224.0/19 74.119.76.0/22 102.132.96.0/20 103.4.96.0/22 129.134.0.0/16 147.75.208.0/20 157.240.0.0/16 163.70.128.0/17 163.77.128.0/17 173.252.64.0/18 179.60.192.0/22 185.60.216.0/22 185.89.216.0/22 204.15.20.0/22 Is it possible to reduce the Meta IP addresses that will call webhook servers at-least for dev-test purposes? No. But see the above FAQ which deduced about 23 IPv4 prefixes to completely cover all Meta address space for v4. What is the retry policy for calling related webhooks? Do not assume anything in this regard. The webhook server should determine stale webhooks based on timestamp value and avoid calling Graph APIs to further process them. Existing messaging related webhooks are retried for up to 7 days. Calling related webhooks will likely have a shorter retry policy but stale webhooks may still be delivered as that may be useful information to a business to know that some consumers tried to reach them. Does Meta guarantee exactly one delivery for webhooks? No. Be prepared to handle duplicate webhooks. Due to the distributed nature of Meta’s architecture, exactly-once delivery cannot be guaranteed for any webhooks including even messaging related webhooks. Following are some known scenarios where duplicates can occur today.The Meta HTTPS request to the webhook server timed out after ~20s. In this case, the server thinks it successfully handled a webhook request but from Meta’s side, it failed due to timeout. Meta retries sending this webhook, which then appears as a duplicate.If the phone number has more than 1 app subscribed to the calls field and Meta dispatches webhooks to app1 and app2 in that order. If app2 fails, Meta will retry the whole dispatch so app1 will receive a duplicate webhook. Meta is in the process of fixing this.Failure recovery on Meta queueing infrastructure may result in duplicate webhook sends.There could be other reasons that are currently unknown. Do you guarantee ordering of webhooks for a given call? No. Ordering is not guaranteed due to the distributed nature of Meta’s architecture and retries. For example the terminate webhook can arrive before the connect webhook if the WhatsApp user hangs up the call immediately after initiating it. Following are other known examples. The connect webhook is attempted which fails with timeout after ~20s. The ‘terminate webhook’ is sent next. The retry of connect webhook happens after the ‘terminate webhook’. In case of timeout, the webhook server thinks there is no failure but this is seen as failure that warrants a retry. Can I configure multiple webhook servers for calling and have a notion of primary and secondary for high availability? Similar to messaging, multiple subscriptions with distinct apps associated with distinct callback URLs can be configured. Meta will dispatch all calling webhooks to all configured callback URLs. All URLs are treated as equal and there is no notion of primary/secondary Can I configure different URLs for messaging and calling related webhooks? Yes, this can be done by having 2 different Meta apps - one for messaging and one for calling. Subscribe the messaging app only to message related webhook subscription fields and the calling app to the calling related subscription fields. The callback URL can be overridden for each of these apps at WABA or phone number level to have different URL override for messages and calls. In general, using a single app is recommended. Can you share sample curl request for interacting with APIs? How should the SDP params be serialized with carriage returns and a new line? The session param requires the SDP to be set as a string per the RFC-8866⁠ specification which requires CRLF to be used to end a record. Sdp param itself is a string so it should not be further serialized. The legacy connection param however required the RFC-8866⁠ compliant SDP string to be within a JSON structure and hence required further serialization. In short, use “\r\n” for session->SDP param. Do not use the legacy connection->WebRTC->SDP param. How do I fix error ‘No fingerprint found in SDP’? The SDP should have an a=fingerprint line when using DTLS⁠ as the SRTP⁠ key exchange protocol. Make sure to add that line or configure the business phone number to use SDES instead. See all the possible Signaling and media possible configurations. WebRTC and media FAQ Is the peer to peer connection from Meta to BSP or end business? Typically it is the BSP but depending on the product offering and architecture it could be end business. If it is the end business, the BSP would need to programmatically interact with them to obtain the ICE candidates included in the Graph API call to accept the incoming call. What happens if the media stops flowing from one end due to connection issues? A simple example would be if the terminate call endpoint fails but the business side stops sending media. This will lead to lack of RTCP packets which helps detect inactive WebRTC agent and the call will disconnect followed by a terminate webhook. Is the codec always opus/48000? We also support G.711 (PCMA and PCMU). For opus, the RTP clock rate is set at 48000 in SDP as per RFC 7587⁠. WhatsApp mobile apps only support opus natively, so Meta media infra transcodes opus to other codecs if needed. What else is supported in terms of codecs? Audio codecs supported: OPUS, PCMA, PCMU (aka G.711) Is DTMF supported? Yes. See the DTMF section for details. Most SIP implementations should support processing DTMF coming through the RTP data stream (reference⁠). How many streams are supported in the SDP? Only one stream is supported in the Offer/Answer SDP. How many tracks are supported in each SDP stream? Only one audio track is supported in the SDP stream. For a consumer to business call, can WhatsApp consumer apps work with an SDP offer generated by a business agent’s browser? In this case, the WebRTC agent within the browser should generate an SDP answer, not an offer. This SDP answer should be supplied back to Meta using the accept call endpoint. Meta cannot work with any other SDP offer than the one it generated and supplied on the webhook. What certificate algorithm is recommended for DTLS? ECDSA certificates are recommended as they lead to faster cert generation and shorter DTLS handshakes due to lack of fragmentation⁠. Who would initiate the calls after accepting the user-initiated call - The BSP or Meta? The BSP should initiate the ICE connectivity checks as soon as the BSP decides to accept the call. This can be done even before calling the accept API but the ICE process will only converge after Meta processes the SDP answer, due to the need for DTLS certificate fingerprint. What are the port numbers used by ICE candidates on Meta’s SDP for allowlisting on firewalls? Port numbers can be any one from 40012, 3482, 3484, 3478, 3480. These are subject to change. How can I generate the WebRTC Accept SDP? Consult the documentation of the WebRTC library or tool planned for use. Processing an SDP offer to generate an SDP answer is the primary functionality of any VoIP technology stack. How to reduce media latency of the calls? Meta’s targeting algorithms will choose the Meta relay that receives media from BSP close to the WhatsApp consumer’s location. This media relay is the ice candidate Meta will share in the SDP. Any BSP side targeting should place the BSP media servers in the same region as the consumer. This obviously minimizes latency for calls within the same region, but it will minimize the media packet routes on public internet for international calls. Is there a process of reconnection if there is a temporary network drop on either end of the media leg? WhatsApp consumer apps will attempt a reconnect and automatically recover that leg of the call once network connectivity is restored. For the business leg, relatively more stable network conditions are expected. At this time there is no support to re-handshake or re-negotiate SDPs. In any case, the call can terminate after a certain duration of inactivity, after which a terminate webhook is sent. How much bandwidth would be required for the call center to support a given number of concurrent calls? Per call, roughly 40kbps is needed for codec + 20 kbps overhead The Opus codec has the ability to dynamically change bandwidth consumed based on network conditions. In general it can offer better audio quality with lower bandwidth consumption, compared to G711 codec. G711 codec in comparison needs 64 kbps for codec + 20 kbps overhead = 84 kbps per call. Multiply the above numbers with the expected number of concurrent calls to calculate the cumulative bandwidth required. Example: A 1mbps bandwidth can roughly handle 15 concurrent calls on opus (1000/64) vs. 12 concurrent calls on G711 (1000/84). To calculate the total data usage, multiply the bandwidth with call duration in seconds. For Opus, it’s a bit more tricky because it has variable bandwidth depending on many factors including available bandwidth estimated using bandwidth estimation, whether local party is talking or silent, and so on. But roughly, a 1 min call on Opus consumes 3.75MB of data vs. the same on G711 takes 4.9MB of data Is it possible to handover / transfer a call from one agent to another during an active call session? In essence, a customer is speaking with Agent A and needs to be transferred to Agent B? Meta doesn’t have any native support. Meta is unaware of different agents on the business / partner side, so this is an operation that is doable solely on the partner side. For example, the media flow can be Meta media server to Partner media server to Agent A. When transfer happens, the flow becomes Meta media server to Partner media server to Agent B. So in the both cases, the leg from Meta media server to Partner media server remains constant. WhatsApp Consumer Client FAQ When is the call icon in the chat title bar visible on WhatsApp Consumer apps? It is visible when all the following conditions are met:The business phone number has the calling status set to ENABLED in the call settings API.Business phone number call_icon_visibility is not HIDE_IN_CHAT and not DISABLE_ALLThe call icon visibility feature is supported in WhatsApp mobile versions 2.24.10.8 and above on Android and iOS.Consumer’s WhatsApp version 2.23.14 or above. All consumers are expected to be on this version or above. View the call settings API to learn more Why is the call icon in the WhatsApp Consumer app not reflecting the current call settings? After call configuration is updated, WhatsApp users may take up to 7 days to reflect that configuration although most users refresh much sooner. An immediate refresh in WhatsApp can be forced by entering the chat window with the business and opening the chat info page. Regardless of WhatsApp client behavior, the semantics of settings are still honored on the server side. Troubleshoot the call icon not showing using the following steps:Navigate to the chat window for the business and click on the business name or number in the chat title bar. This opens the Business Info screen and forces the app to refresh calling state for the business.Navigate out of the chat window for the business and re-enter.If the expected state is still not visible, kill the WhatsApp app and restart it.Make sure to get call settings to double confirm expected call settings. How long does it take for WhatsApp clients to reflect changes to calling configuration? It can take up to 7 days although most WhatsApp users should reflect the changes much sooner. One WhatsApp Business can have chats with any number of 3B+ WhatsApp users. Updates to calling settings sends change notifications to all users that have a chat with this business visible in their WhatsApp Inbox. However notification delivery is best effort so not all users may receive it. All WhatsApp clients refresh the business information (including calling configuration) every 7 days regardless of getting any change notifications. In either case (notification driven or 7d refresh), once the local state in WhatsApp client is refreshed, it is reflected in UI only on next enter of the chat screen or chat info screen. Must I create an allowlist of consumer numbers for calling to work? No. Is it possible to limit calling access to specific or individual WhatsApp users instead of all WhatsApp users? Example: a lead that’s qualified or a customer who is in premium tier No. There is no way to control visibility or access of calling on an individual WhatsApp user basis. However the Call Settings API can be used to set call_icon_visibility to DISABLE_ALL which will hide call icons to all WhatsApp users. For qualified WhatsApp users, a message with the call CTA button can be sent so only they can call the business by tapping on the button in the message Providing this type of feature would require Meta to store configuration per WhatsApp user which has higher privacy risk. It will also incur higher operational overhead to maintain large lists of allowlisted WhatsApp users on an ongoing basis. When the call icon is hidden using Call Settings API, is it still possible for consumers to call the business? Yes. A user can still call the business from other entry points which are unaffected by the Call Settings API such as:Save the business number as a contact and use new callCall logs from Calls tab > RecentCall CTA in messages sent from the businessCall bubble in the chat window that appears following any call between user and business Hence the recommendation is to treat DISABLE_ALL only as a broad first level filter and ensure webhooks do any additional filtering based on specific business logic. How will WhatsApp consumers type digits for DTMF? WhatsApp consumer apps are extended to support a new keypad for business calls. Learn more about DTMF support in Calling API What is the min version of WhatsApp mobile apps that support the voice call button?Min app version for Android is 2.24.1 What is the experience on the WhatsApp consumer side at various points in the call setup flow? When a WhatsApp consumer calls a business, the local ringback tone starts immediately if the WhatsApp consumer device has internet connectivity. The call UI shows ‘Calling BUSINESS_NAME’. When Cloud API receives the consumer call request and pre-accepts the call, the call UI changes to ‘Ringing BUSINESS_NAME’. After the accept Graph API call is made, the call UI changes to an active call window showing live timer for the call duration. Is calling supported for end users from WhatsApp Web or WhatsApp Desktop apps? No. WhatsApp Web does not support consumer-v-consumer or business calls. Desktop apps support only consumer-v-consumer calls at this point. Business Initiated Calling FAQ What WhatsApp versions and client platforms support the business initiated calling feature? WhatsApp Client versions 2.24.14.x and later support the call permission requests and business initiated calling feature. Both WhatsApp Android and iOS platforms support the feature. How to avoid 138011 in Business Initiated and user initiated conversation while dev/integration/testing? User Initiated conversation:Send a message to the Cloud API number from the WhatsApp consumer accountSend any message apart from the call permission message to the userSend a call permission request to the userAccept the call permission requests on the user’s device Business Initiated conversation:Send a template message to the user from the businessSend the call permission request to the userAccept the call permission requests on the user’s device Is there a way to reset the call permission request limits? A connected call will reset the call permission limits. What happens if the WhatsApp user has set up Silence Unknown Callers settings? Business initiated calls bypass ‘Silence Unknown Callers’ settings since the call can only happen after explicit permission provided by the user. Why is my Call Permission Request message rendered differently? WhatsApp’s renders messages on unsupported client app versions differently than supported ones. After the WhatsApp user updates their client app, it will be rendered correctly. I received error 138001 after sending a Call Permission Request, what do I do? Please view error codes in the troubleshooting page Does the permission expire after 24 hour connected calls limit is reached? I am seeing error 138012. Limit on connected calls in 24 hours is a time window based running limit. Reaching that limit does not revoke the permission, permission remains open until the full 7 days for temporary allowed permissions or permanently for always allowed permissions. Call permission rate limit API provides the exact timestamp when this limit is expires and next call can be made. Think of this as a rate limit for business initiated calls. Session Initiation Protocol (SIP) FAQ See SIP Errors for SIP specific errors and possible solutions. Why is user initiated call getting disconnected immediately after enabling SIP? Most likely reason for this is certificate validation error: See How to test if you have a valid TLS certificate Why am I not getting SIP INVITE when WhatsApp users calls? Possible reasons includeTLS certificate validation error: See How to test if you have a valid TLS certificateSIP is not configured. Fetch calling configuration to make sure SIP is enabledThe app that configured the SIP server does not have whatsapp_business_messaging permission on the business phone number. Try to send a message using the same business phone number as a way to verify the right permissions are in place. Why is our SIP TERMINATE to Meta is not hanging up on WhatsApp user side? Common reason is TLS handshake failure when the SIP server is trying to establish a TLS session with Meta SIP server. Do a network packet capture of SIP traffic or check the SIP server logs to confirm successful TLS handshake Why is my SIP server continuously responding with 401 Unauthorized for user initiated calls? Meta supports SIP digest auth for user initiated calls. When the SIP server responds with 401 Unauthorized (see example flow), Meta SIP server will resend the INVITE with proper Authorization header. Make sure the SIP server is configured with username as the business phone number and password as the Meta generated password for the business phone number. Alternatively, digest auth can be disabled on the SIP server, although this is NOT recommended from a security best practices point of view. Why is my SIP server responding with 488 Not Acceptable Here? Consult the SIP server documentation or vendor. The likely reason is the SIP server does not support WebRTC ICE (Interactive Connectivity Establishment) protocol. To fix this, configure the business phone number to use SDES instead. Is it required to SIP REGISTER business phone number to Meta SIP server? No. Do not send REGISTER requests to Meta’s SIP server. Doing so is unnecessary resource consumption on both sides. REGISTER requests will fail with 403 Forbidden error. As such Meta’s SIP server owns only meta.vc domain and the only SIP users in that domain are regular WhatsApp consumer users. The WhatsApp Business Numbers belong to the SIP domain configured using the settings API. Does Meta support SIP re-INVITEs? No. Re-INVITES are not supported today. A 500 Internal Server Error is returned from Meta SIP server. Is SIP calling as good as the Cloud Graph API/webhook option? Any reason to pick one over the other? Yes, there is functional parity between the two options. The best way to identify the best option is to complete a thorough assessment and select based on needs. If SIP is used for calling, are webhooks still needed? SIP for calling only covers call specific events. For messaging or any non-call specific events, webhooks still need to be used. Does Meta have a specific, approved list of vendors or SBCs for SIP? No. Any compatible SIP server. Catalogs Catalogs overview | Developer Documentation Catalogs overviewUpdated: Mar 3, 2026WhatsApp catalogs let businesses showcase products and services directly within customer conversations. Instead of redirecting customers to external websites or apps, catalogs bring the browsing experience into the chat — customers can view products, explore options, and place orders without leaving WhatsApp. What is a catalogA catalog is a structured inventory of products or services that you upload to Meta and connect to your WhatsApp Business Account (WABA). Each catalog item includes details like name, description, price, images, and availability. Once connected, this inventory becomes the foundation for all commerce interactions on WhatsApp.Catalogs support two categories of items: Products: Physical or digital goods with attributes like price, SKU, and images.Services: Offerings such as appointments, consultations, or subscriptions. How catalog commerce worksWhatsApp catalog commerce involves four stages: Inventory upload — You upload your product data to Meta through the Commerce API or the Meta Commerce Manager⁠. This creates the catalog that powers all downstream interactions.Commerce configuration — You configure commerce settings for your business phone number, including whether to enable cart functionality and catalog visibility. See Set commerce settings for details.Product sharing — You share products with customers using different message types — catalog messages, single product messages, multi-product messages, or carousel formats. See Share products for all available formats.Customer responses — Customers browse products, ask questions, and submit orders. You receive these interactions as webhook notifications containing order details and product inquiries. Key capabilities Product sharing formatsWhatsApp supports several message formats for sharing catalog products, each suited to different use cases: Catalog messages display a thumbnail of your full catalog, inviting customers to browse all available products.Single product messages highlight one specific product with its image, price, and description.Multi-product messages present a curated selection of up to 30 products organized into sections.Product carousel messages show products in a horizontally scrollable card format. Shopping cartWhen cart functionality is enabled, customers can add multiple products to a cart while browsing your catalog and submit a single order. The cart persists across the conversation, allowing customers to continue browsing and adding items before checking out.A shopping cart: Is unique to a customer/business chat thread on a specific device: Only one cart is created per chat thread between you and a customer, and carts do not persist across multiple devices. Once a cart is sent, the customer can open another cart with you and start the process again.Has no expiration date: The cart persists in the chat thread until it is sent to you. Once sent, the cart is cleared.Customers can add up to 99 units of each single catalog item to a shopping cart, but there is no limit on the number of distinct items that can be added to a cart.Once a cart has been sent, no edits can be made. Customers can send a new cart if they need new items, or would like to change their order. You cannot send carts to customers. Shopping cart experience example and expected behavior for item state change. PoliciesNever send messages that violate the Commerce and Business Policies. Additionally, multi-product and single-product messages are subject to the existing enforcement and data sharing rules for product catalogs: India compliance: Businesses based in India must comply with all online selling laws⁠.Rejection at product catalog level: WhatsApp automatically reviews items added to a catalog connected to a WABA. If a policy-violating item is added, the product is flagged and the business is directed to the WhatsApp Commerce Policies.Reporting options at the product catalog level: Users can report a specific product they receive through a message. If a user reports a product, it is reviewed for violations.Businesses can appeal for disapproved items directly in the Meta Commerce Manager⁠. LimitationsUnlike product messages sent via the WhatsApp Business app, messages sent via the Cloud API currently do not display a shopping cart icon in the chat thread header. Product updatesYou may need to update properties of items in your catalog. Depending on the updated property, this is how messages that showcase that product are handled: Updated Property Update Process Product’s price, title, description, and image. You send a product message containing product A.You update product A’s properties in your catalog.The screens that display that product are updated as soon as the customer client learns about the change from the server. Availability change You send a customer a product message containing product B.You sell all units of product B available. Then, you update your catalog saying that product B is no longer available.If a customer has already added product B to a cart, the item will be removed from the cart. The shopping cart displays a dialog saying “One or more items in your cart have been updated”.If a customer has not added product B to the cart, the product message now shows the item as unavailable. Upload inventory to Meta | Developer Documentation Upload inventory to MetaUpdated: Mar 3, 2026A business’s inventory needs to be uploaded to Meta in a catalog format — see About Catalogs⁠ for more information.If a business already has a Meta catalog set up, leverage that catalog for WhatsApp commerce use cases. Just connect the catalog to a WhatsApp Business Account⁠ (WABA) and the business will be able to share products with customers.If a business needs to create a catalog, there are two possibilities: Create a catalog using the Commerce APICreate a catalog using the Meta Commerce Manager⁠.You can only upload one catalog per WABA, but the same catalog can belong to multiple phone numbers. Solution PartnersSolution Partners onboarding client businesses into commerce messages have the following options: If a client business already has and manages their own Meta catalog, they can give permission to the Solution Partner to manage their catalog —these permissions are controlled via the Meta Business Manager⁠ and Meta Commerce Manager⁠. After that, the Solution Partner can connect the WhatsApp Business Account to the catalog⁠ via WhatsApp Manager.If a client business doesn’t have a Meta catalog, they can create and upload a new catalog under the Solution Partner’s business ID. Share products with WhatsApp users | Developer Documentation Share products with WhatsApp usersUpdated: Mar 3, 2026You have multiple ways to share products with your customers. Catalog messagesCatalog messages and Catalog template messages display a product thumbnail header image, custom body text, and a View catalog button. When a customer taps the button, your product catalog appears within WhatsApp. Catalog link messagesUse a Catalog link messages to send a link to your entire product catalog by assembling a wa.me link and including it in a standard text message. Checkout button messagesCheckout button template messages allow India-based businesses to showcase one or more products that WhatsApp users in India (with India country calling codes) can purchase without leaving the WhatsApp client. Single-product messagesSingle-product messages and Single-product template messages present a single product from your catalog, accompanied by a product image, product title, and product price, along with customizable body text, optional footer text, and an interactive View button. Multi-product messagesMulti-product messages and Multi-product template messages display up to 30 products from your catalog, organized into customizable sections. Product carousel messagesProduct carousel messages and Product carousel template messages allow you to send a single text message accompanied by a set of up to 10 product cards in a horizontally scrollable view. Receive responses from customers | Developer Documentation Receive responses from customersUpdated: Mar 3, 2026After receiving single- or multi-product messages, WhatsApp users can ask for more information about a product or place an order. These actions are communicated via the messages webhook. Sent message statusSent message statuses (sent, delivered, read) are described in status messages webhooks. Asking for informationWhenever a WhatsApp user receives a single- or multi-product message, they can ask for more information by sending you a text message in an existing WhatsApp thread, or by tapping a Message business or Message button when viewing a specific product.Messages sent after tapping a Message business or Message button are described in text messages webhooks and a context property will be included, whose value is an object describing the product the user was viewing when they tapped the button. OrdersWhen a WhatsApp user adds one or more products to their WhatsApp shopping cart and places an order, the order messages webhook is triggered, describing the contents of the order. Use the order contents to fulfill the order. Catalog link messages | Developer Documentation Catalog link messagesUpdated: Mar 3, 2026You can send a link to your entire product catalog by assembling a wa.me link and including it in a standard text message. When sending a text message, you can use the optional preview_url set to true to have the message render a set of product catalog thumbnails of any URL in the message body string.Note that if you disable the catalog, wa.me links and the View Catalog button in catalog link messages display an Invalid catalog link message when tapped.To assemble a wa.me link, append your business phone number, including country code, to the end of the following string: https://wa.me/c/For example: https://wa.me/c/15555455657 Catalog messages | Developer Documentation Catalog messages Updated: Mar 3, 2026 Catalog messages let you showcase your product catalog entirely within WhatsApp. Catalog messages display a product thumbnail header image of your choice, custom body text, a fixed text header, a fixed text sub-header, and a View catalog button. When a customer taps the View catalog button, your product catalog appears within WhatsApp. Requirements You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account?. Post body Properties Placeholder Description Sample Value String Required. Text to appear in the message body. Maximum 1024 characters. Hello! Thanks for your interest. Ordering is easy. Just visit our catalog and add items to purchase. String Optional. Text to appear in the message footer. Maximum 60 characters. Best grocery deals on WhatsApp! String Optional. Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message's header image. If the parameters object is omitted, the product image of the first item in your catalog will be used. 2lc20305pt String Customer phone number. +16505551234 Catalog templates | Developer Documentation Catalog templates Updated: Mar 3, 2026 This document explains how to create catalog templates. See Sell Products & Services to learn more about product catalogs and ways to showcase your products. Catalog templates are marketing templates that allow you to showcase your product catalog entirely within WhatsApp. Catalog templates display a product thumbnail header image of your choice and custom body text, along with a fixed text header and fixed text sub-header. When a customer taps the View catalog button in a catalog template message, your product catalog appears within WhatsApp. Creating catalog templates Requirements You must have inventory uploaded to Meta in an e-commerce catalog connected to your WhatsApp Business Account?. Request parameters Placeholder Description Sample Value String Required. Template body text. Variables are supported. Maximum 1024 characters. Now shop for your favorite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp! String (of an array of strings) Required if body text uses variables. Sample strings to replace variable placeholders in string. Maximum 1024 characters. 100 String Optional. Template footer text. Variables are supported. Maximum 60 characters. Best grocery deals on WhatsApp! String Required. Template language and locale code. en_US String Required. Template name. Maximum 512 characters. intro_catalog_offer Sending catalog template messages You can send approved catalog templates in a template message. See Sell Products & Services to learn more about product catalogs and ways to showcase your products. Requirements You must have inventory uploaded to Meta in an e-commerce catalog connected to your WhatsApp Business Account?. Request parameters Placeholder Description Sample Value String Required. Template language and locale code. en_US String Required. Template name. intro_catalog_offer String Optional. Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message's header image. If the parameters object is omitted, the product image of the first item in your catalog will be used. 2lc20305pt String Required if template uses variables. Template variable. 100 String Required. Customer phone number. +16505551234 String Required if template uses variables. Template variable type. text See also Sell Products & ServicesCatalog Messages Multi-product messages | Developer Documentation Multi-product messages Updated: Mar 3, 2026 Multi-Product Messages are interactive messages that display up to 30 products from your catalog, organized into sections. Customers can browse products, view details, add items to a cart, and send an order — all within WhatsApp. Multi-Product message example: Menu triggered when user clicks on Start Shopping: Overview Customers that receive Multi-Product Messages can perform 3 main actions:View products: Customers can see a list of products. Whenever a customer clicks on a specific item, the product’s latest info is fetched and the product displays in a Product Detail Page (PDP) format. Currently, PDPs only support product images — any videos or GIFs added to the product won’t be displayed in the PDP.Add products to a cart: Whenever a user adds a product to the shopping cart, the item’s latest info is fetched. If there has been a state change on any of the items, a dialog saying “One or more items in your cart have been updated” is displayed — see Product updates for more information. A cart persists in a chat thread between you and your customer until the cart is sent to you — see Shopping cart experience for details.Send a shopping cart to you: After adding all needed items, customers can send their cart to you. After that, you can define the next steps, such as requesting delivery info or giving payment options. If your customer has multiple devices linked to their account, Multi-Product Messages will be synced between devices. However, the shopping cart is local to each specific device. See Shopping cart experience for details. Currently, Multi-Product Messages can be received on the following platforms:iOS: 2.21.100Android: 2.21.9.15Web: The web client supports this feature. If the customer’s app version does not support Multi-Product Messages, they will instead receive a message explaining that they were unable to receive a message because they are using an outdated version of WhatsApp. You also receive a webhook notification indicating the message was unable to be delivered due to the customer using an outdated version of WhatsApp. Expected behavior Multi-Product Messages can be:Forwarded by one user to another.Reopened by a user within the same chat thread. Multi-Product Messages cannot be:Sent as notifications. They can only be sent as part of existing chat threads. Use cases Multi-Product Messages are best for guiding customers to a specific subset of your inventory, such as:Shopping in a conversational way. For example, using search functionality to allow customers to type a shopping list and send back a Multi-Product Message in response.Navigating to a specific category. For example, fitness apparel.Personalized offers or recommendations.Re-ordering previously ordered items. For example, a user can re-order their regular take-out order of less than 30 items. Multi-Product Messages can also be used as part of a human agent flow. However, you need to build the tooling to allow the human agent to generate a Multi-Product Message in thread. Why you should use them Multi-Product Messages lend themselves best to user experiences that are simple and personalized, where it’s a better experience to guide the customer to a subset of items most relevant to them, rather than browsing your full inventory. Simple and efficient Combining the features with navigation tools like Natural Language Processing (NLP), text search or List Messages and Reply Buttons to get to what the customer is looking for fast. Personal Populated dynamically so can be personalized to the customer or situation. For example, you can show a Multi-Product Message of a customer’s most frequently ordered items. Business outcomes A high-performing channel for driving orders. During testing, businesses had an average 7% conversion of Multi-Product Messages sent to carts received. No templates Interactive messages do not require templates or pre-approvals. They are generated in real-time and will always reflect the latest item details, pricing and stock levels from your inventory. Send a multi-product message Before sending product messages, follow the get started best suited for your needs:Direct developersSolution providers All API calls mentioned in this guide must be authenticated with an access token. You can authenticate your API calls with the access token generated in the App Dashboard > WhatsApp > API Setup panel. If you are a solution provider, you must authenticate with an access token with the whatsapp_business_messaging permission. Step 1: Assemble the interactive object To send a Multi-Product Message, assemble an interactive object of type product_list with the following components: Required Components Optional Components Header Object — Header’s type must be set to text. Remember to add a text object with the desired content.Body ObjectAction Object - Must include catalog_id and sections. Sections must be an array of objects describing each section using title and product_items. Each section’s product_items value must be an array describing each product in the section using product_retailer_id and the product’s SKU number. Footer Object See Messages, Interactive Object for full information. By the end of the process, the interactive object should look something like this: Missing items If none of the items provided in the API call matches a product from your product catalog, an error message is sent and the Multi-Product Message is not sent to the user. At least one item from the products list must match an item from your product catalog. In this case:Messages are sent successfullyItems without a match are droppedYou receive an error message asking for a catalog update Multi-product message templates | Developer Documentation Multi-product message templates Updated: Mar 3, 2026 This document describes multi-product message (“MPM”) templates, their uses, and how to use them. MPM templates are marketing templates that allow you to showcase up to 30 products from your ecommerce catalog, organized in up to 10 sections, in a single message. Customers can browse products and sections within the message, view details for each product, add and remove products from their cart, and submit their cart to place an order. Orders are then sent to you via a webhook. See our help center article About Multi-product message templates on WhatsApp⁠ for common use cases and tips on how to make the most of MPM templates. Requirements In order to create and use MPM templates you must have an ecommerce product catalog, with inventory, connected to your WhatsApp Business Account. See the Cloud API Commerce guide. Limitations Customers must be using WhatsApp v2.22.24 or greater.MPM templates cannot be forwarded to other customers. Interactive product carousel messages | Developer Documentation Interactive product carousel messages Updated: Mar 3, 2026 The interactive product carousel message enables businesses to send horizontally scrollable product cards within WhatsApp conversations, allowing users to browse and engage with products directly in-thread. This format integrates with the Product Catalog and supports Single Product Message (SPM) actions on each card, providing a seamless and interactive shopping experience via the WhatsApp Business APIs and mobile clients. How to build a product carousel message The product carousel message contains a card object. You must add 2 card objects to your message, and can add a maximum of 10. Each card exists in a cards[] array and must be given a "card_index" value of 0 through 9. The type of each card must be set to "product", and each card must reference the same "catalog_id". You must add a message body to the message, and no header, footer, or buttons are allowed. Lastly, each card must specify the product and catalog identifiers "product_retailer_id" and "catalog_id". The card object Request parameters Placeholder Description Sample Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Maximum 1024 characters. Which option do you prefer? String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Card object parameters Placeholder Description Sample value Integer Required Unique index for each card (0-9). Must not repeat within the message. 2 String Required The unique retailer ID of the product in the catalog. "0JkSUu4qizuXv" String Required The unique ID of the catalog containing the product. "Lq1ZtoWL5OkljTerAW" Product card carousel templates | Developer Documentation Product card carousel templates Updated: Mar 3, 2026 Product card carousel templates allow you to send a single text message accompanied by a set of up to 10 product cards in a horizontally scrollable view: When a WhatsApp user taps the View button, they can view more information about the product, add the product to a shopping cart, and place an order, all without leaving the WhatsApp client experience. If instead you prefer to send the user to your website when they click the button, see Media Card Carousel Templates. Product cards Carousel templates support up to 10 product cards, composed of message body text, a product image, product title, product price, and a single View button or URL button. All cards defined on a template must have the same components. View buttons When a WhatsApp user taps the button, the product details view appears, displaying product information pulled from your product catalog. Users can then add the product to a cart and place an order. When a user submits the cart, a webhook will be triggered describing the order, and an order confirmation message will appear in the message thread. Users who have placed an order can see the contents of the order by tapping the View details button. URL buttons Instead of View buttons you may wish to use URL buttons. When a WhatsApp user taps a URL button to buy a product, the URL mapped to the button is loaded in the device's default web browser, which takes the user out of the WhatsApp client experience. This can be useful if, for example, you wish to load the product in your mobile checkout page where users can add promo codes and find related products. With URL button flows, since order placement happens outside of the WhatsApp client, webhooks describing the order are not triggered. Catalogs To use product card carousel templates, you must have an ecommerce product catalog, with inventory, connected to your WhatsApp Business Account. See the Cloud API Commerce guide to learn more about connecting a catalog to your account. Single-product messages | Developer Documentation Single-product messages Updated: Mar 3, 2026 Single-Product Messages are interactive messages that display a single product from your catalog, allowing customers to view product details, add the item to a cart, and send an order — all within WhatsApp. Single-Product message example: Product Detail Page example: Overview Customers that receive Single-Product Messages can perform 3 main actions:View the product: Whenever a customer clicks on the item, the product’s latest info is fetched and the product displays in a Product Detail Page (PDP) format. Currently, PDPs only support product images — any videos or GIFs added to the product won’t be displayed in the PDP.Add the product to a cart: Whenever a user adds a product to the shopping cart, the item’s latest info is fetched. If there has been a state change, a dialog saying “One or more items in your cart have been updated” is displayed — see Product updates for more information. A cart persists in a chat thread between you and your customer until the cart is sent to you — see Shopping cart experience for details.Send a shopping cart to you: After adding items, customers can send their cart to you. After that, you can define the next steps, such as requesting delivery info or giving payment options. If your customer has multiple devices linked to their account, Single-Product Messages will be synced between devices. However, the shopping cart is local to each specific device. See Shopping cart experience for details. Currently, Single-Product Messages can be received on the following platforms:iOS: 2.21.210Android: 2.21.19Web: The web client supports this feature. If the customer’s app version does not support Single-Product Messages, they will instead receive a message explaining that they were unable to receive a message because they are using an outdated version of WhatsApp. You also receive a webhook notification indicating the message was unable to be delivered due to the customer using an outdated version of WhatsApp. Expected behavior Single-Product Messages can be:Forwarded by one user to another.Reopened by a user within the same chat thread. Single-Product Messages cannot be:Sent as notifications. They can only be sent as part of existing chat threads. Use cases Single-Product Messages are best for guiding customers to one specific item from your inventory, offering quick responses from a limited set of options, such as:Responding to a customer’s specific request.Providing a recommendation.Reordering a previous item. Single-Product Messages can also be used as part of a human agent flow. However, you need to build the tooling to allow the human agent to generate a Single-Product Message in thread. Why you should use them Single-Product Messages lend themselves best to user experiences that are simple and personalized, where it’s a better experience to guide the customer to a specific item most relevant to them, rather than browsing your full inventory. No templates Interactive messages do not require templates or pre-approvals. They are generated in real-time and will always reflect the latest item details, pricing and stock levels from your inventory. Send a single-product message Before sending product messages, follow the get started best suited for your needs:Direct developersSolution providers All API calls mentioned in this guide must be authenticated with an access token. You can authenticate your API calls with the access token generated in the App Dashboard > WhatsApp > API Setup panel. If you are a solution provider, you must authenticate with an access token with the whatsapp_business_messaging permission. Step 1: Assemble the interactive object To send a Single-Product Message, assemble an interactive object of type product with the following components: Required Components Optional Components Action Object — Must include both catalog_id and product_retailer_id. Body ObjectFooter Object See Messages, Interactive Object for full information. By the end of the process, the interactive object should look something like this: If none of the items provided in the API call matches a product from your product catalog, an error message is sent and the Single-Product Message is not sent to the user. Single-product message templates | Developer Documentation Single-product message templates Updated: Mar 3, 2026 This document describes single-product message (SPM) templates, their uses, and how to use them. SPM templates are marketing templates that allow you to present a single product from your ecommerce catalog, accompanied by a product image, product title, and product price (all pulled from your product within your catalog), along with customizable body text, optional footer text, and an interactive View button. WhatsApp users can tap the button to see details about the product, and can add or remove the product from the WhatsApp shopping cart: If the WhatsApp user adds the product to the cart and submits an order, you will be notified via webhook and the user will see that an order has been placed: Users who place an order are also able to use the View details button to see information about the order: Limitations Customers must be using WhatsApp v2.22.24 or greater.Message forwarding is disabled for SPM templates. Catalogs You must have an ecommerce product catalog, with inventory, connected to your WhatsApp Business Account. See the Cloud API Commerce guide to learn more about connecting a catalog to your account. Core WhatsApp Business Platform | Developer Documentation WhatsApp Business Platform Drive revenue growth, boost efficiency, and deliver exceptional customer experiences with the WhatsApp Business Platform—our enterprise-grade APIs for messaging and calling. Get started About the WhatsApp Business Platform | Developer Documentation About the WhatsApp Business Platform Updated: Dec 5, 2025 The WhatsApp Business Platform enables businesses to communicate with customers at scale. This documentation is intended for developers using our APIs. If you are looking for information on other ways to use WhatsApp for your business see the WhatsApp Business site⁠. Core APIs and capabilities WhatsApp Cloud API WhatsApp Cloud API enables you to programmatically message and call on WhatsApp. You can use Cloud API to send users a variety of messages, from simple text messages to rich media and interactive messages. WhatsApp Cloud API includes: Messaging: Send text messages, rich media, and interactive messagesCalling: Make and receive calls to customersGroups: Create, manage, and message WhatsApp group conversations WhatsApp messaging provides a powerful and private way to engage with customers. Use Cloud API to: Send order confirmations and shipping updatesShare appointment availability and other remindersDrive upsell and cross-sell opportunitiesFacilitate end-to-end transactions, from product discovery to paymentEnable multi-factor authentication or one-time passwords to verify accounts and usersDeliver custom interactive conversational experiences Learn more about message types on WhatsApp Cloud API. Business Management API The WhatsApp Business Management API enables you to programmatically manage a WhatsApp Business Account and its associated assets. Manage account assets with Business Management API like: Business phone numbers: Add and remove phone numbers associated with your businessTemplates: Create and modify message templates for scalable messaging. Business Management API also gives you access to account analytics like: Messaging analytics: The number and type of messages sent and delivered.Pricing analytics: Granular pricing breakdowns for delivered messages. Template analytics: Sent/read/delivered template metrics, alongside template message button clicks. Learn more about message templates.Learn more about managing business phone numbers.Learn more about account analytics. Marketing Messages API for WhatsApp MM API for WhatsApp is an API for sending optimized marketing messages on WhatsApp. When you send marketing messages through the MM API for WhatsApp, you can access new features not available on Cloud API and get automatic optimizations, so high engagement messages can reach more customers. The MM API for WhatsApp includes: Quality-based delivery: Up to 9% higher marketing message deliveries over Cloud API for high engagement content.Automated creative optimizations: Automatic enhancements to marketing creative to increase message performance.Performance benchmarks and recommendations: Comparison of read and click rates versus similar templates from businesses in your region.Conversion metrics: Measure marketing messages that lead users to perform app events such as ‘Add to Cart’, ‘Checkout Initiated’, or ‘Purchase’. Learn more about the Marketing Messages API for WhatsApp. Key resources Business portfolios A business portfolio allows organizations to bring all their Meta business assets together so they can be managed in one place. On the WhatsApp Business Platform, a business portfolio mainly serves as a container for WhatsApp Business Accounts (WABA). You must have a business portfolio to use the platform. Business portfolios can be verified, and verification status factors into improved functionality, such as higher throughput and Official Business Account status. Learn more about business portfolios.⁠ WhatsApp business accounts (WABA) A WhatsApp Business Account represents your business, storing metadata and linking to phone numbers, templates, and analytics. Learn more about WhatsApp Business Accounts. Business phone numbers Business phone numbers, real or virtual, are used for sending and receiving WhatsApp messages. They can have display names and earn Official Business Account status. Learn more about business phone numbers. Message templates Templates are customizable messages that you can construct in advance of sending them. Template messages generally require approval before you can send them. Templates are useful for messaging at scale. They are also the only type of message that can be sent to WhatsApp users outside of a customer service window. Templates have quality scores and are subject to various messaging limits. Learn more about message templates. Test resources When you get started with Cloud API, a test WABA and test business phone number are automatically created for you. Test WABAs and test phone numbers are useful for testing purposes, as they have relaxed messaging limits and don’t require a payment method on file in order to send template messages. You can delete your business portfolio and its test resources if: You are an admin on the business portfolio associated with the appNo other apps are associated with the business portfolioThe business portfolio is not associated with any other WABAsThe WABA is not associated with any other business phone numbers. To delete your business portfolio and its test resources: Go to the App Dashboard > WhatsApp > Configuration panel.Locate the Test Account section.Click the Delete button. We recommend using our API Playground when testing endpoints. You can find the playground in the “API Reference” section on the left sidebar of this page. In each reference, there is a “Try it” button which opens the playground. Also helpful for testing is our Postman collection⁠. Tools and integrations WhatsApp Manager WhatsApp Manager is a web app for managing WABAs, phone numbers, templates, and reviewing analytics. Access WhatsApp Manager⁠ Third-party SDKs Some SDKs, like PyWa⁠ (Python wrapper), are available but are not maintained or endorsed by Meta. Security and performance Throughput Business phone numbers can send up to 80 messages per second by default, with capacity upgrades available. Learn more about throughput. Encryption With the Cloud API, every WhatsApp message continues to be protected by Signal protocol encryption that secures messages before they leave the device. This means messages with a WABA are securely delivered to the destination chosen by each business. The Cloud API uses industry standard encryption techniques to protect data in transit and at rest. The API uses Graph API for sending messages and Webhooks for receiving events, and both operate over industry standard HTTPS, protected by TLS. See our Encryption Overview whitepaper for additional details. See the WhatsApp Encryption Overview whitepaper⁠ for additional details. Scaling The Cloud API automatically scales usage within your rate limits. Rate limits Requests made by your app on your WhatsApp Business Account (WABA) are counted against your app’s request count. An app’s request count is the number of requests it can make during a rolling one hour. For the following endpoints, your app can make 200 requests per hour, per app, per WABA, by default. For active WABAs with at least one registered phone number, your app can make 5000 requests per hour, per app, per active WABA. Type of request Endpoint GET / GET, POST, and DELETE //assigned_users GET //phone_numbers GET, POST, and DELETE //message_templates GET, POST, and DELETE //subscribed_apps GET / For the following Credit Line API requests, your app can make 5000 requests per hour. Type of request Endpoint GET //extendedcredits POST //whatsapp_credit_sharing_and_attach GET and DELETE / GET //owning_credit_allocation_configs For more information on how to get your current rate usage, see Headers. In addition, the platform applies several message rate limits: Test message rate limit (for unverified WABAs)Quality rating and messaging limits (for verified WABAs)Capacity rate limit (for all accounts)Business phone rate limit (per phone number) Pair rate limits Business phone numbers can send 1 message every 6 seconds to the same WhatsApp user (0.17 messages/second), which equals about 10 messages per minute or 600 per hour. Exceeding this limit triggers error code 131056 until you are back within the allowed rate. You may send up to 45 messages in a 6-second burst, but this “borrows” from your future quota. After a burst, you must wait the equivalent time it would take to send those messages at the normal rate (e.g., a burst of 20 requires a ~2-minute wait before sending more to that user). To manage post-burst throttling, if a send request fails, retry after 4^X seconds (starting with X=0 and increasing X by 1 after each failure) until successful. Terms and policies User opt-in You must obtain user opt-in before sending message templates. Opt-in must clarify your business name and intent. Learn more about the WhatsApp Business Messaging Policy.⁠ Terms and policies All platform use must comply with WhatsApp’s terms and policies. Using unauthorized third-party tools is prohibited. Learn more about terms and policies.⁠ Next steps Get started with the WhatsApp Business Platform. Learn more Display namesPhone numbersPricingWebhooks Pricing on the WhatsApp Business Platform | Developer Documentation Pricing on the WhatsApp Business Platform Updated: Mar 30, 2026 This document explains how pricing works on the WhatsApp Business Platform. Cloud API and Marketing Messages API for WhatsApp To align with industry-standards, effective July 1, 2025, Meta now charges on a per-message basis:You are only charged when a template message is delivered ().Rates vary based on the template’s category and the recipient WhatsApp phone number’s country calling code. Meta provides value to businesses in several ways:All non-template messages are free (, , and so on). These can only be sent within an open customer service window. See Sending messages for a list of message types.Utility templates delivered within an open customer service window are free.You can unlock lower rates for utility and authentication template messages, based on messaging volume.All messages are free for 72 hours, including template messages, if sent within an open free entry point window. Pricing explainer Our pricing explainer PDF outlines how Meta charges and the various ways Meta provides value to businesses, in PDF form:Pricing Explainer PDF Message template categories Unlike non-template messages, template messages are the only message type that can be sent outside of a customer service window. Templates can be categorized as:MarketingUtilityAuthentication See Template categorization to learn how template categorization works. Template messages vs. non-template messages CSW = Customer service windowFEP = Free entry point window Businesses are responsible for reviewing the category assigned to their approved templates. Whenever a template is used, a business accepts the charges associated with the category applied to the template at time of use. Charge example In the example below, a business sends 4 messages to a WhatsApp user but is only charged for 2 (1 marketing charge, 1 utility charge). Hour Action Rate Reason 0 You send a marketing template message to a WhatsApp user, promoting your new product. Marketing All marketing template messages are charged. 2 The user messages you about the product. This opens a 24 hour customer service window (“CSW”). - Messages sent from a WhatsApp user to a business are not charged. 3 You send a text message to the user (), describing the product in more detail. None All non-template messages are free within an open customer service window. 4 The user purchases the product and you send them a utility template confirming their order. None The CSW is still open, and utility templates sent within an open CSW are free. 26 The CSW closes, which means you can no longer send non-template messages. - 24 hours have passed since the user last messaged you. 30 You send a utility template message to the user, updating them on their order. Utility Utility template messages sent outside of a CSW are charged, and no open CSW exists between you and the user. Pricing calendar To better enable our customers to plan and prepare for pricing updates, the following pricing calendar applies for messaging and voice on the WhatsApp Business Platform:Meta may update pricing only on the 1st day of each quarter, thus up to 4 times per year: January 1, April 1, July 1, and/or October 1.Meta will provide advanced notice that is better aligned to the effort required to implement different types of pricing updates, per below: Type of pricing update Examples Minimum advance notice Rate card update Updating the rate for a given market–product Updating the volume tiers for a given market–product (utility and authentication only) Moving a market from one pricing region (e.g. “Other”) to another or to be standalone on the rate card 1 month Pricing model add-on Our July 1, 2025, introduction of new volume tiers for utility and authentication messages 3 months Pricing model change Our July 1, 2025 update to our pricing model, from conversation-based pricing to per-message pricing 6 months Rates Rates vary based on template category, volume tier, and country/region rate. Rate cards and volume tiers These rate cards reflect our current rates and volume tiers, effective April 1, 2026, based on WhatsApp Business Account timezone. This information is also available interactively on our WhatsApp Business website⁠. Currency Rates(CSV) Volume tiers(CSV) Rates and Volume tiers(PDF) USD USD rates USD volume tiers USD rates and volume tiers AED AED rates AED volume tiers AED rates and volume tiers ARS ARS rates ARS volume tiers ARS rates and volume tiers AUD AUD rates AUD volume tiers AUD rates and volume tiers CLP CLP rates CLP volume tiers CLP rates and volume tiers COP COP rates COP volume tiers COP rates and volume tiers EUR EUR rates EUR volume tiers EUR rates and volume tiers GBP GBP rates GBP volume tiers GBP rates and volume tiers IDR IDR rates IDR volume tiers IDR rates and volume tiers INR INR rates INR volume tiers INR rates and volume tiers MXN MXN rates MXN volume tiers MXN rates and volume tiers MYR MYR rates MYR volume tiers MYR rates and volume tiers PEN PEN rates PEN volume tiers PEN rates and volume tiers SAR SAR rates SAR volume tiers SAR rates and volume tiers SGD SGD rates SGD volume tiers SGD rates and volume tiers Updates to rate cards Below represents future updates to our rates. See our rate cards above for current rates. Rate cards effective July 1, 2026 Effective July 1, 2026, as of 9am PT – Eligible customers can create new WhatsApp Business Accounts in BRL (Brazilian Reals). This is only available for Solution Partners and directly-integrated clients whose Sold-To country is Brazil in Billing Hub⁠. Per our pricing calendar, Meta will publish per-message rates in BRL by June 1, 2026. Billing localization for India and Brazil Meta is introducing billing localization to help eligible customers to better manage costs of messaging amidst currency fluctuations. This will apply to the markets below, and specifically to Solution Partners and directly-integrated clients whose Sold-To country in Billing Hub is a market below:India⁠ – As of January 1, 2026.Brazil⁠ – As of July 1, 2026. Previous updatesEffective April 1, 2026 at 12am by WhatsApp Business Account timezone, the rate updates below applied: Saudi Arabia – Higher marketing message rate.India – Higher authentication-international rate.Pakistan – Higher utility and authentication rates. No change to the authentication-international rate.Turkey – Lower utility and authentication rates.8 new billing currencies introduced: ARS (Argentina), CLP (Chile), COP (Colombia), MYR (Malaysia), PEN (Peru), SAR (Saudi Arabia), SGD (Singapore), AED (United Arab Emirates).Effective January 1, 2026 at 12am by WhatsApp Business Account timezone, the rate updates below applied: India - Higher marketing rate.France, Egypt - Lower marketing rates.North America - Lower utility and authentication rates.Effective October 1, 2025 at 12am by WhatsApp Business Account timezone, the rate updates below applied: Colombia – Higher utility and authentication rates.Mexico – Lower marketing rates.United Arab Emirates – Higher marketing message rate.Argentina, Egypt, Saudi Arabia – Lower utility and authentication rates.Zimbabwe is mapped to our “Rest of Africa” region vs. “Other”. Messages delivered to WhatsApp users with a +263 country calling code (Zimbabwe) will be charged “Rest of Africa” rates.Effective July 1, 2025 – Lower utility and authentication message rates across several markets, to ensure pricing is on-par to alternate channels for these use cases. Marketing conversation rates became marketing message rates.Effective April 1, 2025 – Lowered authentication-international conversation rates for Egypt, Nigeria, Pakistan, and South Africa.Effective February 1, 2025 – Lowered authentication conversation rates for Egypt, Malaysia, Nigeria, Pakistan, Saudi Arabia, South Africa, and the United Arab Emirates.Effective November 1, 2024 – Service conversations are now free for all businesses.Effective October 1, 2024 – Updated marketing conversation rates in India, Saudi Arabia, the United Arab Emirates, and the United Kingdom.Effective August 1, 2024 – Lowered utility conversation rates. Authentication-international rates Specific countries have an authentication-international rate. Our rate cards reflect these rates. See Authentication-International rates to learn about these rates and if they apply to you. Country calling codes Charges for conversations are based on the country calling code of the recipient WhatsApp phone number. The table below shows how Meta maps country calling codes to countries or regions. If a country is not listed below, it maps to Other. This information is also available in a CSV file:Country Calling Codes and Regional Rate Mapping CSV Markets Calling Code (and network prefix if applicable) Countries Argentina Brazil Chile Colombia Egypt France Germany India Indonesia Israel Italy Malaysia Mexico Netherlands Nigeria Pakistan Peru Russia Saudi Arabia South Africa Spain Turkey United Arab Emirates United Kingdom 54 55 56 57 20 33 49 91 62 972 39 60 52 31 234 92 51 7 966 27 34 90 971 44 North America Canada United States 1 1 Rest of Africa Algeria Angola Benin Botswana Burkina Faso Burundi Cameroon Chad Republic of the Congo (Brazzaville) Eritrea Ethiopia Gabon Gambia Ghana Guinea-Bissau Ivory Coast Kenya Lesotho Liberia Libya Madagascar Malawi Mali Mauritania Morocco Mozambique Namibia Niger Rwanda Senegal Sierra Leone Somalia South Sudan Sudan Swaziland Tanzania Togo Tunisia Uganda Zambia Zimbabwe 213 244 229 267 226 257 237 235 242 291 251 241 220 233 245 225 254 266 231 218 261 265 223 222 212 258 264 227 250 221 232 252 211 249 268 255 228 216 256 260 263 Rest of Asia Pacific Afghanistan Australia Bangladesh Cambodia China Hong Kong Japan Laos Mongolia Nepal New Zealand Papua New Guinea Philippines Singapore Sri Lanka Taiwan Tajikistan Thailand Turkmenistan Uzbekistan Vietnam 93 61 880 855 86 852 81 856 976 977 64 675 63 65 94 886 992 66 993 998 84 Rest of Central and Eastern Europe Albania Armenia Azerbaijan Belarus Bulgaria Croatia Czech Republic Georgia Greece Hungary Latvia Lithuania Moldova North Macedonia Poland Romania Serbia Slovakia Slovenia Ukraine 355 374 994 375 359 385 420 995 30 36 371 370 373 389 48 40 381 421 386 380 Rest of Western Europe Austria Belgium Denmark Finland Ireland Norway Portugal Sweden Switzerland 43 32 45 358 353 47 351 46 41 Rest of Latin America Bolivia Costa Rica Dominican Republic Ecuador El Salvador Guatemala Haiti Honduras Jamaica Nicaragua Panama Paraguay Puerto Rico Uruguay Venezuela 591 506 1 (809, 829, 849) 593 503 502 509 504 1 (658, 876) 505 507 595 1 (787, 939) 598 58 Rest of Middle East Bahrain Iraq Jordan Kuwait Lebanon Oman Qatar Yemen 973 964 962 965 961 968 974 967 Other All other countries Varies by country Volume tiers You can unlock lower utility and authentication rates based on the number of messages you send in a month. Tiering accrualMessages are aggregated at the business portfolio level, across all WhatsApp Business Accounts (WABAs) owned by the portfolio — To determine what tier rates may apply in a given month for a given market–category pair, Meta aggregates messages across all of a business portfolio’s WABAs for each market-category pair (e.g., Brazil–authentication, Brazil–utility, India–authentication, and so on).Only messages that are charged count toward the tiers — Thus, the following messages do not count: Utility templates delivered to WhatsApp users within an open customer service window.Utility templates delivered within a free entry point window.Volume tiers will be determined solely by Meta — All insights data is approximate due to small variations in data processing. Undue reliance should not be placed on insights data. Key dynamicsTiers are market–category specific — Volume tiers are aligned to our rate cards and differ by market (e.g., Brazil or Rest of Latin America) and category (utility, authentication).Rates are tier-specific — When a business sends enough messages at a given market–category pair to reach the next tier, they unlock the rate of the next tier, specifically for messages in that tier. This rate applies across all of their WABAs.Tiers reset monthly — At the start of the next month (12am WABA timezone), message count resets to 0 and businesses begin to accrue messages toward that month. Volume tiers examples The table below is illustrative and only highlights the dynamics of volume tiers. Please refer to our rate cards to see the rates charged. Below are several examples to highlight how the tiers work and what is charged in a given month, for a given market–category. These examples refer to the illustrative table above: Example 1: A business that sends a total of B authentication messages in a month to India is charged:List rate for the first A messages.Tier rate 1 for messages A+1 to B.Total charges for that month = Rate per tier 𝗑 messages in each tier. Example 2: A business that starts to be charged our authentication-international rates on the 15th day of the month:Day 1 to 14 of that month: Volume tiers apply on the authentication rate.Day 15 onward of that month: Volume tiers apply on the authentication-international rate, with messages continuing to accrue in that month. For example, if a business has already reached the Tier 2, the business would be charged Tier 2’s authentication-international rate: Example 3: A business has 3 WABAs sending authentication messages to India. For WABA A, it is still July 31 based on their timezone. For WABAs B and C, it is already August 1 based on their timezone. For July, the business is already being charged Tier Rate 1.The business portfolio will be accruing toward tiers for both July (via WABA A) and August (via WABAs B, C) for a period of time.The business can reach the next tier for July, via WABA A. If that happens, messages for the remainder of July for WABA A will be charged Tier Rate 2. Example 4: A business has 3 WABAs, integrated across 2 solution providers. Provider 1 sends the first B messages in a given month, and provider 2 starts sending messages as of when the business is in the 3rd tier. The business does not send enough messages that month to reach the next tier. What we would charge each provider:Provider 1: List rate for A messages, then Tier Rate 1 from A+1 to B, and Tier Rate 2 for B+1 to C.Provider 2: Tier Rate 2 across all of their messages. Tiering webhooks Starting October 1, 2025, an account_update webhook with event set to VOLUME_BASED_PRICING_TIER_UPDATE will be triggered when your WhatsApp Business Account reaches a new volume tier, in any market, in a given month. This complements our pricing_analytics endpoint, which will continue to provide intra-month tiering progress and tiering information for delivered messages. Example webhook: tier_update_time tells when your WABA reached a higher volume tier (Unix timestamp). pricing_category tells you the template category for which your new volume tier rate applies. tier tells you the new volume tier’s lower and upper bounds. effective_month tells you the month in which your new volume tier rate is in effect. region tells you the WhatsApp user country/region for which your new volume tier rate applies. Note that it’s possible for multiple account_update webhooks to be triggered that describe the same tier switch event. In these cases, use the webhook with the smaller tier_update_time Unix timestamp as the official webhook. Tiering analytics You can get volume tier information via template analytics. Free non-template messages Non-template messages, which can only be sent within an open customer service window, are free. These messages will have type set to free_customer_service in the pricing object of status messages webhooks: Free utility template messages Utility template messages sent within an open customer service window are free. These messages will have type set to free_customer_service and category set to utility in the pricing object of status messages webhooks: Edge case If you send a message to a WhatsApp user prior to July 1, 2025 (which is when Meta switched from conversation-based pricing to per-message pricing), a utility conversation is opened between you and a user that spans the switch to per-message pricing (the conversation was opened before the switch but won’t close until after the switch). In this case, utility templates sent to the user after the switch while the conversation is open will be free, but attributed to the open conversation. In status messages webhooks, these messages will have a pricing_model of CBP and the utility conversation ID will be assigned to conversation.id. Once the conversation closes, subsequent utility messages will use per-message pricing, which will be reflected in new webhooks. Free Entry Point windows If a WhatsApp user messages you via a Click to WhatsApp Ad or Facebook Page Call-to-Action button using a device running our Android or iOS app (our desktop and web apps are not supported):A 24-hour customer service window is opened (as normal).If you respond within 24 hours using any type of message, the message will be free, and a Free Entry Point (“FEP”) window will be opened, starting from the time when you responded. FEP windows remain open for 72 hours. While open, you can send any type of message to the user at no charge. Note, however, that the customer service window is independent of the FEP window, so if the customer service window closes, you will only be able to send template messages. New max-price feature for Marketing Messages API for WhatsApp Starting in 2026, businesses integrated into Marketing Messages API for WhatsApp can choose to set a max-price per marketing message delivery; when a max-price is set, Meta will charge that max-price or lower for delivery. New pricing policy for AI Providers leveraging WhatsApp Business Platform Click here to learn more about our new pricing policy for “AI Providers” leveraging WhatsApp Business Platform, which is effective February 16, 2026 and updated as of March 4, 2026. Analytics Use the pricing_analytics field to get per-message pricing breakdowns and tiering information for delivered messages. Webhooks Billable messages have type set to regular in the pricing object of status messages webhooks: The tells you what rate was applied (e.g. marketing). See the status messages webhook reference for a list of possible values. Note that currently, tiering information is not included in any webhooks. Use the pricing_analytics field to get tiering information for delivered messages. Billing Billing and billing-related actions are handled through the Meta Business Suite. See About Billing For Your WhatsApp Business Account⁠ for more information. WhatsApp Business Calling API pricing The WhatsApp Business Calling API has different pricing. See our Calling API pricing document to learn more. Conversation-based pricing Conversation-based pricing is deprecated. It was replaced with per-message pricing on July 1, 2025. Authentication-international rates | Developer Documentation Authentication-international rates Updated: Dec 12, 2025 Specific countries have an authentication-international rate in our rate cards. If you send an authentication template message to a WhatsApp user whose country calling code is for a country that has an authentication-international rate, the delivered message will be billed the country's authentication-international rate if:your business is eligible for authentication-international ratesyour business is based in another country (see Primary Business Location)the message was delivered on or after your start time for that country For example, if your business is based in Indonesia and you send an authentication template message to a WhatsApp user who has a +62 (Indonesia) country calling code, and the message is delivered, you will not be billed the authentication-international rate since you are based in the same country as the user. If your business is based in India, however, you will be billed the authentication-international rate, if you meet all of the criteria above. See Examples for additional example scenarios. Status messages webhooks that include pricing details and pricing analytics will indicate if a message or set of messages were billed the authentication-international rate. Eligibility If your business sends more than 750K messages outside of customer service windows in a moving 30-day period, across all of your WhatsApp Business Accounts, with unique WhatsApp users whose country calling codes are for a country that has an authentication-international rate, it will be deemed eligible for authentication-international rates. Once deemed eligible, we will set your start times 30 days out for each country that has an authentication-international rate. In addition, we will attempt to determine your primary business location using publicly-available information. We will then send you an eligibility email that includes these start times and the country that we set as your primary business location (if we were able to determine the country). This provides you with 30 days notice before authentication-international rates apply. Webhooks will also be triggered that include your start times and your primary business location (if we set it). Note that eligibility is permanent. Once your business is deemed eligible, all authentication template messages sent on or after your start time will be charged the authentication-international rate in markets where authorization-international rates apply. Countries with authentication-international rates The following countries have authentication-international rates:EgyptIndiaIndonesiaMalaysiaNigeriaPakistanSaudi ArabiaSouth AfricaUnited Arab Emirates Please see Rate cards for more details about the rates. Start times Start times are business- and country-specific timestamps. They indicate when newly-delivered authentication template messages are subject to authentication-international rates. Authentication template messages sent by your business and delivered to WhatsApp users in these countries on or after these dates only will be charged authentication-international rates. Start times are set when your business is first deemed eligible for authentication-international rates, and are 30 days from your eligibility date, so you will always have 30-days notice before the authentication-international rate applies. Start times are included in your eligibility email and webhooks. You can also get these times by requesting the auth_international_rate_eligibility field on any of your business's WhatsApp Business Accounts: Request parameters Placeholder Description Example value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. WhatsApp Business Account ID. 102290129340398 Response parameters Placeholder Description Example value WhatsApp Business Account (WABA) ID. 102290129340398 Unix timestamp indicating start time for all countries with authentication-international pricing for which you do not have an exception. 1732057507 A unique object describing a country that has an exception start time. See exception country. For most WhatsApp Business Accounts, the exception_countries array will be empty. Primary business location Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024, if we are able to determine where your business is based using publicly-available information. The following publicly-available information is used to determine where your business is based:Where your business may be publicly-traded and listedYour business's corporate structure (where a parent or may be based or publicly-traded) We will attempt to determine where your business is based when:It is deemed eligible for authentication-international ratesYou edit your primary business location using the Business Manager. This process can take up to 3 business days. The outcome of this determination can be:Verified - We determined where your business is based and set your primary business location to this country (which also triggers a webhook).Need more information - We require more information in order to make a determination.Rejected - We disagreed with the country you designated in the Business Manager (if you used it to edit the Primary Business Location field) You will be notified of the outcome in your initial eligibility email, or in a separate email if you used the Business Manager to edit your location. If rejected or if we need more information, or if you disagree with the country we determined to be the primary business location, you can use the Business Manager to edit your location. Note that if your primary business location status is not verified but you are past your start time for a given country, any authentication messages that you send to a WhatsApp user in that country will be billed the authentication-international rate. Set or edit your primary business location To set or edit your primary business location:Navigate to Business Settings by clicking here?Select the country of the business's primary location of operation from the dropdown, or enter it in the text field. Note that this is the location where your business has its headquarters and maintains its bookkeeping records.Click NextAnswer the questions on the screen. These answers will help Meta verify your primary business location.Click NextClick Submit for review Note: You won't be able to make any changes while your verification is under review. Primary business location status The Primary Business Location field in the Business Manager will also display a status:Verified - We have verified your business's primary location.Pending verification - We are in the process of determining your business's primary location.Rejected - We disagreed with the country you designated, based on publicly available information and what you included when you edited your location. You can manually edit your location again and include different information as part of your submission. Get your location via API You can use the API to see if your business's primary business location is set by requesting the primary_business_location field on your WhatsApp Business Account (WABA): Response: Upon success: - WhatsApp Business Account ID. - Two-character country code indicating the country where we have determined the business to be based. Eligibility email By sending authentication messages over WhatsApp, you acknowledge and agree that when your business is deemed eligible for authentication-international rates, an email will be sent to all of the email addresses associated with the admins of your accounts, and all third parties that your WhatsApp Business Accounts have been shared with (e.g. admins of Solution Partners that have access to your WhatsApp Business Accounts), to alert them that the threshold of eligibility has been reached. The email will include:Your exact start times for each country that has an authentication-international rate.The country that we set as your primary business location. Exception countries Authentication-international rates for applicable countries will begin on the same date, unless otherwise specified in your eligibility email, the exception_countries array in eligibility webhooks, or the exception_countries array returned when requesting the auth_international_rate_eligibility field on your WhatsApp Business Account (WABA). You will always be charged the domestic rate for your primary business location, even if it appears in the either exception_countries array. Example Scenario In the following examples, assume this scenario:there are three countries, identified by three fictitious country codes: A, B, and Ccountries A and B have authentication-international ratescountry C does not have an authentication-international ratethe business portfolio has a WABA with ID 12345 Requesting the auth_international_rate_eligibility field on WABA 12345 returns: Country C is not represented in the response because it does not have an authentication-international rate. Scenario 1 The business's primary business location is country C.The authentication-international rate applies for country A on June 1, 2024.The authentication-international rate applies for country B on July 1, 2024. Scenario 2 The business's primary business location is country B.The authentication-international rate applies for country A on June 1, 2024. The authentication-international rate for country B does not apply because the business's primary business location is also country B. Webhooks Eligibility webhook An account_update webhook will be triggered if your business is deemed eligible for international rates. The webhook will include start times for each country that has an authentication-international rate. Please see Rate cards for the list of countries with authentication-international rates. - WhatsApp Business Account ID. - Unix timestamp indicating when the webhook was sent. - Two-letter country code (e.g. ID for Indonesia) of the country with a start time exception. - Unix timestamp indicating authentication-international rate start time for the exception country. - Unix timestamp indicating start time for all countries with authentication-international pricing for which you do not have an exception. Primary business location update webhook Subscribe to the account_update webhook to be notified when the business's primary business location is set. If we are able to determine the country where your business is based, we will set your location to that country and trigger an account_update webhook with the country's two-character country code assigned to the BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE property. - WhatsApp Business Account ID. - Unix timestamp indicating when the webhook was sent. - ISO 3166-1 alpha-2 country code, indicating the country where we have determined the business to be based. Pricing in messages webhook If an authentication template message is billed the authentication-international rate, the pricing object in status messages webhooks will have category set to authentication_international. Examples A business with an Indonesia primary business location send an authentication template message to a WhatsApp user: User location Is business eligible? Is on/after start time? Rate billed Indonesia - - Authentication India No - Authentication India Yes No Authentication India Yes Yes Authentication-International A business with an India primary business location sends an authentication template message to a WhatsApp user: User location Is business eligible? Is on/after start time? Rate billed India - - Authentication Indonesia No - Authentication Indonesia Yes No Authentication Indonesia Yes Yes Authentication-International A business with a primary business location that does not have an authentication-international rate sends an authentication template message to a WhatsApp user: User location Is business eligible? Is on/after start time? Rate billed Indonesia No - Authentication Indonesia Yes No Authentication Indonesia Yes Yes Authentication-International India No - Authentication India Yes No Authentication India Yes Yes Authentication-International Conversation-based pricing (DEPRECATED) | Developer Documentation Conversation-based pricing (DEPRECATED)Updated: Nov 14, 2025Conversation-based pricing is deprecated. It was replaced on July 1, 2025, with per-message pricing. The document below is for reference purposes only.This document explains how conversation-based pricing works on the WhatsApp Business Platform.Charges are applied per conversation, not per individual message sent or received.Conversations are 24-hour message threads between you and your customers. They are opened and charged when messages you send to customers are delivered. The criteria that determines when a conversation is opened and how it is categorized is explained below.Businesses are responsible for reviewing the category assigned to their approved templates. Whenever a template is used, a business accepts the charges associated with the category applied to the template at time of use. Conversation categoriesConversations are categorized with one of the following categories: Marketing — Enables you to achieve a wide range of goals, from generating awareness to driving sales and retargeting customers. Examples include new product, service, or feature announcements, targeted promotions/offers, and cart abandonment reminders.Utility — Enables you to follow-up on user actions or requests. Examples include opt-in confirmation, order/delivery management (e.g., delivery update); account updates or alerts (for example., payment reminder); or feedback surveys.Authentication — Enables you authenticate users with one-time pass codes, potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).Service — Enables you to resolve customer inquiries.Marketing, utility, and authentication conversations can only be opened with template messages. Service conversations can be opened with any type of message other than a template message.See Message Types to learn more about the various types of messages you can send to customers. Opening conversationsConversations are opened when you send a message to a customer under the following conditions. Marketing, Utility, and Authentication ConversationsWhen you send an approved marketing, utility, or authentication template to a customer, we check if an open conversation matching the template’s category already exists between you and the customer. If one exists, no new conversation is opened. If one does not exist, a new conversation of that category is opened, lasting 24 hours.For example: Hour 0: You send a targeted promotion (marketing template message) to a customer. No open marketing conversation exists between you and the customer, so a marketing conversation lasting 24 hours is opened.Hour 4: The customer completes an order on your site, so you send them an order confirmation (utility template message). No open utility conversation exists between you and the customer, so a utility conversation lasting 24 hours is opened.Hour 10: You send a shipment confirmation (utility template message) to the customer. An open utility conversation already exists between you and the customer, so a new utility conversation is not opened.To learn more about template categories and how to choose an appropriate category when creating templates, see Template Categorization.For additional examples, see our pricing explainer PDF. Service conversationsService conversations are now free. This change does not affect how service conversations are opened.A service conversation is opened when any message other than a template message is delivered to your customer and no open conversation of any category exists between you and the customer.Note that a customer service window must exist between you and the customer before you can send them a non-template message.For example: Hour 0: You send a targeted promotion (marketing template) to a customer. No open marketing conversation exists between you and the customer, so a marketing conversation lasting 24 hours is opened.Hour 4: The customer messages you. This opens a customer service window between you and the customer, allowing you to send them any type of message for the next 24 hours.Hour 5: You send an interactive list message to the customer. An open conversation already exists between you and the customer (a marketing conversation in this case), so a service conversation is not opened.Hour 24: The marketing conversation expires.Hour 25: The 24-hour customer service window is still open, so you send a second text message to the customer. No open conversation exists between you and the customer anymore, so a service conversation is opened, lasting 24 hours.Hour 26: The 24-hour customer service window is still open, so you send a third text message to the customer. An open service conversation already exists between you and the customer, so a new service conversation is not opened.For additional examples, see our pricing explainer PDF. Customer Service WindowsSee Customer Service Windows. Conversation durationMarketing, utility, authentication, and service conversations last 24 hours unless closed by a newly opened free-entry point conversation.Free-entry point conversations last 72 hours. Multiple conversationsIt is possible to have multiple open conversations between you and a customer. This can happen in the following situations: An open marketing, utility, or authentication conversation exists between you and a customer and you send them a template message of a different category within 24 hours.An open service conversation exists between you and a customer and you send them a template message within 24 hours. Free Tier conversationsAs of November 1, 2024, you can open an unlimited number of service conversations at no charge. See Free Service Conversations to learn more. Free Entry Point conversationsA free entry point conversation is opened if (1) a customer using a device running Android or iOS (the desktop and web clients are not supported) messages you via a Click to WhatsApp Ad⁠ or Facebook Page Call-to-Action⁠ button and (2) you respond within 24 hours. If you do not respond within 24 hours, a free entry point conversation is not opened and you must use a template to message the customer, which opens a marketing, utility, or authentication conversation, per the category of the template.The free entry point conversation is opened as soon as your message is delivered and lasts 72 hours. When a free entry point conversation is opened, it automatically closes all other open conversations between you and the customer, and no new conversations will be opened until the free entry point conversation expires.Once the free entry point conversation is opened, you can send any type of message to the customer without incurring additional charges. However, you can only send non-templates messages if there is an open customer service window between you and the customer.For example, if the customer messages you via a Click to WhatsApp Ad at 10am and you respond via a template message at 10pm the same day: The free entry point conversation starts at 10pm and lasts 72 hours.You can send template messages at no charge in those 72 hours.You can send non-template messages until 10am the next day, at which point the customer service window closes, as it is independent of the free entry point conversation (if the customer messages you again, however, it opens another 24-hour customer service window in which you can send any type of message). RatesRates vary based on conversation category and country/region rate. You can download the rate card below that corresponds to your WhatsApp Business Account’s currency to see our rates by country/region for each conversation category.These rates apply for any conversation opened on or after June 1, 2023 at 12:00 AM, based on WhatsApp Business Account time zone. Rate CardsThese rate cards represent the current rates on our platform. Rates in USDRates in INRRates in IDRRates in EURRates in GBPRates in AUD Authentication-International ratesStarting June 1, 2024, we are introducing authentication-international rates. See Authentication-International Rates to learn about these rates and if they apply to you.Effective April 1, 2025, we are lowering our authentication-international rates in Egypt, Nigeria, Pakistan and South Africa, as part of continued efforts to ensure our prices are on-par with alternate channels. Marketing Messages API for WhatsApp pricingPer-message pricing is coming to Marketing Messages API for WhatsApp. Starting July 1, 2025, Cloud API marketing rates will apply to messages sent via Marketing Messages API for WhatsApp.Marketing Messages API for WhatsApp has different pricing. View the Marketing Messages API for WhatsApp pricing document for details. WhatsApp Business Calling API pricingThe WhatsApp Business Calling API has different pricing. View the Calling API pricing document for details. Updates to rate cardsAs announced in June 2024, we may update rates up-to-quarterly. For marketing, updates are to reflect demand and the value these messages deliver. For utility and authentication, our objective is to price on-par with alternate channels.To support these efforts, we have made the following updates: Effective April 1, 2025 Lowered authentication-international pricing rates for Egypt, Nigeria, Pakistan, and South Africa.Effective February 1, 2025 Lowered authentication pricing rates for Egypt, Malaysia, Nigeria, Pakistan, Saudi Arabia, South Africa, and the United Arab Emirates.Added authentication-international pricing rates for Egypt, Malaysia, Nigeria, Pakistan, Saudi Arabia, South Africa, and the United Arab Emirates.Effective November 1, 2024 Service conversations are now free for all businesses, including via AI-enabled conversational experiences.Effective October 1, 2024 Updated pricing rates in India, Saudi Arabia, the United Arab Emirates, and the United Kingdom.Effective August 1, 2024 Lowered utility conversation pricing rates. Country calling codesCharges for conversations are based on the country of the user’s phone number. We rely on your customer’s country calling code and network prefix (area code) to determine their country. The table below shows how we map country codes to countries or regions. If a country is not listed below, it maps to Other. Markets Calling Code (and network prefix if applicable) Countries Argentina Brazil Chile Colombia Egypt France Germany India Indonesia Israel Italy Malaysia Mexico Netherlands Nigeria Pakistan Peru Russia Saudi Arabia South Africa Spain Turkey United Arab Emirates United Kingdom 54 55 56 57 20 33 49 91 62 972 39 60 52 31 234 92 51 7 966 27 34 90 971 44 North America Canada United States 1 1 Rest of Africa Algeria Angola Benin Botswana Burkina Faso Burundi Cameroon Chad Republic of the Congo (Brazzaville) Eritrea Ethiopia Gabon Gambia Ghana Guinea-Bissau Ivory Coast Kenya Lesotho Liberia Libya Madagascar Malawi Mali Mauritania Morocco Mozambique Namibia Niger Rwanda Senegal Sierra Leone Somalia South Sudan Sudan Swaziland Tanzania Togo Tunisia Uganda Zambia 213 244 229 267 226 257 237 235 242 291 251 241 220 233 245 225 254 266 231 218 261 265 223 222 212 258 264 227 250 221 232 252 211 249 268 255 228 216 256 260 Rest of Asia Pacific Afghanistan Australia Bangladesh Cambodia China Hong Kong Japan Laos Mongolia Nepal New Zealand Papua New Guinea Philippines Singapore Sri Lanka Taiwan Tajikistan Thailand Turkmenistan Uzbekistan Vietnam 93 61 880 855 86 852 81 856 976 977 64 675 63 65 94 886 992 66 993 998 84 Rest of Central & Eastern Europe Albania Armenia Azerbaijan Belarus Bulgaria Croatia Czech Republic Georgia Greece Hungary Latvia Lithuania Moldova North Macedonia Poland Romania Serbia Slovakia Slovenia Ukraine 355 374 994 375 359 385 420 995 30 36 371 370 373 389 48 40 381 421 386 380 Rest of Western Europe Austria Belgium Denmark Finland Ireland Norway Portugal Sweden Switzerland 43 32 45 358 353 47 351 46 41 Rest of Latin America Bolivia Costa Rica Dominican Republic Ecuador El Salvador Guatemala Haiti Honduras Jamaica Nicaragua Panama Paraguay Puerto Rico Uruguay Venezuela 591 506 1 (809, 829, 849) 593 503 502 509 504 1 (658, 876) 505 507 595 1 (787, 939) 598 58 Rest of Middle East Bahrain Iraq Jordan Kuwait Lebanon Oman Qatar Yemen 973 964 962 965 961 968 974 967 Other All other countries Varies by countryThe information in the table above is also available in a CSV file: Country Calling Codes and Regional Rate Mapping CSV WebhooksPricing information is included in all message webhooks. See: Cloud API: Message Status UpdatesOn-Premises API (deprecated): Message Status Updates BillingBilling and billing-related actions are handled through the Meta Business Suite. See About Billing For Your WhatsApp Business Account⁠ for more information. Marketing Messages API for WhatsAppIf you are using the Marketing Messages API for WhatsApp, such usage is subject to Marketing Messages API for WhatsApp pricing. See the Marketing Messages API for WhatsApp pricing document for pricing information and rate cards. See also ConversationsAbout Billing For Your WhatsApp Business Account⁠PricingTemplate CategorizationSending messages with Cloud API New pricing policy for AI Providers leveraging the WhatsApp Business Platform | Developer Documentation New pricing policy for AI Providers leveraging the WhatsApp Business Platform Updated: Mar 4, 2026 This page is specific to “AI Providers” using the WhatsApp Business Platform. This does NOT change how Meta charges all other businesses using the WhatsApp Business Platform. Refer to the pricing page. Who this applies to This is specific to “AI Providers” using the WhatsApp Business Platform, as defined in our Terms of Service⁠ updated on January 15, 2026: Providers and developers of artificial intelligence or machine learning technologies, such as large language models, generative artificial intelligence platforms, general-purpose artificial intelligence assistants, or similar technologies who provide certain services on WhatsApp Business Platform. This does NOT change how or what Meta charges all other businesses using the WhatsApp Business Platform. They will continue to be charged as outlined in the pricing explainer. This includes not being charged for non-template messages sent in an open customer service window. This also does not change the mechanics of the customer service window. Why Meta is charging Specifically for third party AI Providers:Effective January 15, 2026, WhatsApp’s Terms of Service update⁠ “AI Providers” are only permitted to offer general purpose AI assistants on the WhatsApp Business Platform where Meta is legally required to permit this use case.Effective February 16, 2026, in countries where Meta is legally required to support AI Providers usage of the WhatsApp Business Platform, Meta will charge AI Providers for non-template messages sent to WhatsApp users in these countries. What and where Meta will charge Effective February 16, 2026 – Meta will charge for:Each non-template message (, and so on)Delivered from an “AI Provider”To a user in a market where Meta is legally required to permit AI Providers to use the WhatsApp Business Platform Markets and effective dates (as of January 28, 2026): Effective February 16, 2026, this applies to Italy (+39). Effective March 11, 2026, this applies to the following countries:Austria (+43)Belgium (+32)Brazil (+55)Bulgaria (+359)Croatia (+385)Cyprus (+357)Czech Republic (+420)Denmark (+45)Estonia (+372)Finland (+358)France (+33)Germany (+49)Greece (+30)Hungary (+36)Iceland (+354)Ireland (+353)Latvia (+371)Liechtenstein (+423)Lithuania (+370)Luxembourg (+352)Malta (+356)Netherlands (+31)Norway (+47)Poland (+48)Portugal (+351)Romania (+40)Slovakia (+421)Slovenia (+386)Spain (+34)Sweden (+46) For example: If a user in Italy sends an AI Provider a prompt, and the AI Provider delivers three non-template message responses to the user over a span of 5 minutes, that will incur three charges. RatesAI Provider rates for non-template messages CSV (March 4, 2026). AI Provider rates for non-template messages PDF (March 4, 2026). These rates are specific to AI Providers using the WhatsApp Business Platform. To see rates for marketing, utility, and authentication messages, please refer to Pricing on the WhatsApp Business Platform. Analytics The Pricing Analytics API will include a new value of AI_BOT to reflect AI Provider traffic. Webhooks The webhooks will reflect the for these non-template messages from “AI Providers” as general_purpose_ai. Billable messages have type set to regular in the pricing object of status messages webhooks: WhatsApp Cloud API Get Started | Developer Documentation WhatsApp Cloud API Get Started Updated: Oct 1, 2025 This guide helps developers quickly get started with the WhatsApp Cloud API. It covers the basic setup steps, including registering as a developer, creating a Meta app, sending your first message, and setting up a test webhook endpoint. You’ll also learn how to generate secure access tokens and send both template and non-template messages. Advanced features and further resources are introduced for deeper exploration. Download the Sample App The Jasper’s Market sample app contains all of the messages and code used in the Jasper’s Market demo. You can use this sample app to learn how to build an application that sends and handles WhatsApp Cloud API data. Download the Jasper’s Market Sample App Prerequisites You must have a Facebook account or a managed Meta account.You must be registered as a developer. If you have not registered as a developer, navigate to https://developers.facebook.com/async/registration/ and follow the prompts.You need access to a device with WhatsApp on it so you can send and receive test messages during setup. Step 1. Create a New Meta Developer App and Set Up with WhatsApp You need to create a Meta developer app and set the app up with the WhatsApp use case. Click on “Go to App Dashboard” and follow the instructions below to get started. Go to App Dashboard If you already have a Meta app Select your existing app in the App Dashboard.Click on Add use cases.Select Connect with customers through WhatsApp and follow the prompts to add the use case to your app. Note: If you do not have a Meta Business Portfolio, you will create one during this process. If you do not have a Meta app Follow the prompts in the App Dashboard to create a new app. Select the Connect with customers through WhatsApp use case.Select an existing Business Portfolio or follow the prompts to create a new one.Finish creating your app.Once your app has been created, select Use cases (pencil icon) from the sidebar. Step 2. Connect Your Meta App to a WhatsApp Business Account After creating your Meta app, you need to connect it to a WhatsApp Business Account. This connection allows your app to access the WhatsApp Cloud API and send messages on behalf of your business. Navigate to the App Dashboard and select your app.Click on Use cases (pencil icon) in the sidebar.Under your Connect with customers through WhatsApp use case, click Customize.In the API Setup section, select an existing WhatsApp Business Account or create a new one: To use an existing account: Select the WhatsApp Business Account from the dropdown menu.To create a new account: Click Create a WhatsApp Business Account and follow the prompts to set up your business profile.Once connected, you will see your WhatsApp Business Account ID displayed in the API Setup panel. Save this ID for use in API calls. Note: If you created a new Meta Business Portfolio during app creation, a WhatsApp Business Account may have been automatically created for you. Verify the connection in the API Setup section before proceeding. Step 3. Send Your First Template Message With your new app set up, let’s send your first message on WhatsApp. Click on Use cases (pencil icon) on the sidebar.Under your Connect with customers through WhatsApp use case, click Customize.In Quickstart, click on the Start using the API button and follow the first 2 steps to send the hello_world template message to a phone number of your choosing. Make sure to retain both your test phone number ID and WhatsApp Business Account ID for later use.Once you receive the message you sent, make sure to reply back to keep the conversation going. Step 5. Create a System User and Generate a Permanent Access Token The temporary access token you created to send the hello_world template message expires quickly and is not suitable for development purposes. So you should create a permanent token for use across the WhatsApp Business Platform. Navigate to Business Settings⁠ and click System users in the sidebar.Click the Add+ button in the upper-right corner and follow the prompts to create a new system user.Select the new system user you created, and click Assign Assets. Select your app and toggle Manage app under Full control.Select your WhatsApp account and toggle Manage WhatsApp Business Accounts under Full control.Click the Assign assets button.Click Generate token. Follow the prompts to generate your token.Add the following permissions to the token: business_managementwhatsapp_business_messagingwhatsapp_business_managementCopy the token and store it in a secure place to be used in the later steps. Step 7. Finish The WhatsApp Cloud API enables you to send messages and receive webhooks—these are the fundamental building blocks for messaging integration. Beyond these basics, the API offers additional features such as group creation and management, as well as support for calling. To explore these advanced capabilities, check out the “Learn more” section below. Learn more Learn about the different types of non-template messagesLearn how to create and send template messagesLearn how to create and manage WhatsApp groups via APILearn how to send and receive calls on WhatsApp via APILearn how to add a business phone numberLearn how to set up your own webhook serverBecome a Solution ProviderView WhatsApp API OpenAPI Specification⁠ Ctwa Welcome Message Sequences - API Guide | Developer Documentation Welcome Message Sequences - API Guide Updated: Nov 17, 2025 When creating Click-to-WhatsApp ads, you can connect a Welcome Message Sequence from your messaging app. A sequence can include text, prefilled message, and FAQs. This guide explains how to manage Welcome Message Sequences via the API endpoint. Requirements Your app must be granted the whatsapp_business_management permission. Change an existing sequence A sequence linked to an active ad cannot be deleted. To update an existing sequence, send a POST request to the WHATSAPP_BUSINESS_ACCOUNT_ID/welcome_message_sequences endpoint with:The sequence_id parameter set to the ID of the sequence being updatedOther parameters, like name or welcome_message_sequence, that need to be updated. Sample response The response includes a success or error message. Delete a sequence A sequence linked to an active ad cannot be deleted. To delete a sequence, send a DELETE request to WHATSAPP_BUSINESS_ACCOUNT_ID/welcome_message_sequences with the sequence_id parameter set to the ID of the sequence you want to delete. Marketing API experience After you submit welcome message sequences through the API, use the sequence ID to configure ads through the Marketing API. In the ad creative, the sequence ID can be set as follows: For more information about messaging ads, refer to Messaging Ads in the Marketing API documentation. Ads Manager experience walk-through 1: In the Message Template section of the Ad Creative, select Partner App Click the Partner app dropdown and select the appropriate messaging partner app. 3: Under Message sequence, select the Welcome Message Sequence that you submitted via the API. Preview your message sequence and click Save. Error codes Code Description Possible Solutions 4027001 Invalid input data Some or all of the input data is not of the required format. Check all the fields and parameters passed into the request are of the correct type and format, and that all required parameters are present. 4027005 Unable to create a welcome message sequence An error occurred while trying to create a new welcome message sequence. Check that the access token has all the required permissions for the WhatsApp business account. 4027006 Unable to update a welcome message sequence Unable to update the welcome message sequence. Check all fields and the sequence ID for correctness. Check that the access token has the necessary permissions for the WhatsApp business account. 4027007 API unavailable The API being accessed is not available for use yet. Wait a day or two for the API to become available and try again. 4027010 Missing parameter One or more required parameters is missing. Check all the documentation and ensure the required parameters are present. 4027012 Sequence used in an ad The welcome message sequence is linked to an active ad and cannot be updated or deleted. Disconnect the sequence from the ad and try again. 4027017 Could not load the sequence Could not load the sequence being updated or deleted. The welcome message sequence either does not exist, or you do not have permission to access it. Please check the access token and make sure you have the required permissions. Data Privacy And Security Data Privacy & Security | Developer Documentation Data Privacy & SecurityUpdated: Mar 31, 2026This page describes how Meta provides Cloud API as a standalone service for businesses to message users at scale via WhatsApp. Meta also offers additional optional services that businesses can choose to use with Cloud API. For example, a business can leverage Meta’s AI capabilities to converse with customers via Cloud API. When a business chooses to use these services, different terms could apply. Please consult the applicable documentation for additional details on how Meta processes data for these services. Message FlowsWhen a user sends a message to a business that uses Cloud API, the message travels encrypted via WhatsApp between the user and Cloud API. Once the message is received by Cloud API, Cloud API decrypts the message and forwards it to the business. When a business uses Cloud API to send a message to a user, the reverse applies. Upon receiving a message from a business, Cloud API will encrypt the message using the Signal protocol before sending it to the user via WhatsApp. Per the Signal protocol, the user and Cloud API, acting on behalf of the business, negotiate encryption keys and establish a secure communication channel.WhatsApp acts as the transport channel. WhatsApp protects users by detecting unusual messaging patterns (like a business trying to message all users) and collecting spam reports from users. Cloud API, operated by Meta, acts as the intermediary between WhatsApp and businesses using Cloud API. In other words, those businesses have designated Cloud API to operate on their behalf.To the extent any data protection or privacy law applicable to you recognizes the concepts of “data processor” or “service provider” as defined within those laws, Meta, in providing Cloud API service, acts as a data processor/service provider on behalf of the business. Cloud API will only use the messages it processes on behalf of and at the instruction of the business, unless otherwise directed. Cloud API will not automatically use WhatsApp messages to inform the ads that a person sees.For further detail on message flows and encryption, see the WhatsApp Encryption Overview technical whitepaper⁠. Stored and Collected DataAll data collected, stored, and accessed by Cloud API is controlled and monitored to ensure proper usage and to maintain a high level of privacy.Business Data. Information about the businesses, including their business phone numbers, business address, etc. is maintained by Meta and the Meta Business Suite or Business Manager product, and is subject to the terms of service provided by Meta.Message Data. Messages have a maximum retention period of 30 days in order to provide the base features and functionality of the Cloud API service; for example, retransmissions.User Data. Identifiers are used as sources or destinations of individual messages; as such they are deleted within 30 days of the last status update (sent, delivered, read) of a message, unless otherwise directed.For a more detailed resource on Cloud API’s storage and processing of data, see the Meta Business Messaging Compliance Center⁠, which includes Cloud API’s certifications and compliance documentation. FAQsDoes Meta use the WhatsApp messages that are shared with it by a business for advertising?Cloud API will not automatically use WhatsApp messages to inform the ads that a person sees. However, as is always the case, businesses can use messages they receive for their own marketing purposes, which may include advertising on Facebook or other channels, like email or TV.Where are the servers for Cloud API? Cloud API processes messages on servers in Meta data centers⁠. If a business opts to use Cloud API Local Storage, message data is stored in data centers located in another designated country.Is the Cloud API end-to-end encrypted? What is the encryption model? See Cloud API Overview, Encryption.What happens to message data at rest? How long is it stored?Cloud API messages at rest are encrypted. Messages have a maximum retention period of 30 days in order to provide the base features and functionality of the Cloud API service; for example, retransmissions.Does Meta have access to encryption keys?In order to send and receive messages through Cloud API, Cloud API manages the encryption/decryption keys on behalf of the business. For more detail, see the WhatsApp Encryption Overview technical whitepaper⁠.What is the security model? Which certifications does the Cloud API have?We have obtained SOC 2 Type II and ISO 27001 reports. Please visit our Meta Business Messaging Compliance Center⁠ to learn more.How does Cloud API comply with regional data protection laws (such as GDPR, LGPD, and PDPB)?Meta takes data protection and people’s privacy very seriously and we comply with applicable legal, industry, and regulatory requirements governing data protection, as well as industry best practices. Cloud API customers must meet their own obligations under data protection laws, such as the General Data Protection Regulation (GDPR). Please visit our Meta Business Messaging Compliance Center⁠ to learn more.What does Meta and WhatsApp do to make sure the transfer of data from the E.U. and/or the UK to the US is compliant?Meta and WhatsApp rely on appropriate GDPR-compliant transfer mechanisms when it transfers data from the E.U. and/or the UK to the US.See the following legal terms for additional information: For all customers, see the Meta Hosting Terms for Cloud API⁠.For customers in the European Region, see the WhatsApp Business Data Transfer Addendum⁠.For customers in the UK, see the WhatsApp Business UK Data Transfer Addendum⁠.See the applicable WhatsApp Business Data Processing Terms⁠ or Meta Hosting Terms for Cloud API⁠ for an applicable list of sub-processors.We will ensure that our businesses and partners can continue to enjoy business solutions while keeping their data safe and secure. Display Names Display names | Developer Documentation Display names Updated: Mar 24, 2026 You must provide a display name when registering a business phone number. The display name appears in your business phone number's WhatsApp profile: It can also appear at the top of individual chat threads and the chat list if your business phone number is approved via display name verification. Note that if a WhatsApp user edits your profile name in the WhatsApp client, the name they set will appear instead. Display name guidelines See our Display name guidelines for the WhatsApp Business Platform? Help Center article for naming guidelines. Display name verification When you reach a higher messaging limit, your business phone number's display name automatically undergoes verification based on the display name guidelines?. When the process completes, a phone_number_name_update webhook and Meta Business Suite notification are triggered. If your display name is approved, the webhook has decision set to APPROVED, and the name_status field on your business phone number is set to APPROVED. If your display name is rejected, the webhook has decision set to REJECTED, and the name_status field on your business phone number is set to DECLINED. Review the display name guidelines? and edit your display name? accordingly, or file an appeal via Developer Support or Enterprise Developer Support. View display name in WhatsApp Manager Your business phone number's display name appears in the Name column in the WhatsApp Manager? > Account tools > Phone numbers panel. Learn more The following Help Center articles provide additional information about display names. About WhatsApp Business display name?How to change your WhatsApp Business display name? Docs About the WhatsApp Business Platform | Developer Documentation About the WhatsApp Business Platform Updated: Dec 5, 2025 The WhatsApp Business Platform enables businesses to communicate with customers at scale. This documentation is intended for developers using our APIs. If you are looking for information on other ways to use WhatsApp for your business see the WhatsApp Business site⁠. Core APIs and capabilities WhatsApp Cloud API WhatsApp Cloud API enables you to programmatically message and call on WhatsApp. You can use Cloud API to send users a variety of messages, from simple text messages to rich media and interactive messages. WhatsApp Cloud API includes: Messaging: Send text messages, rich media, and interactive messagesCalling: Make and receive calls to customersGroups: Create, manage, and message WhatsApp group conversations WhatsApp messaging provides a powerful and private way to engage with customers. Use Cloud API to: Send order confirmations and shipping updatesShare appointment availability and other remindersDrive upsell and cross-sell opportunitiesFacilitate end-to-end transactions, from product discovery to paymentEnable multi-factor authentication or one-time passwords to verify accounts and usersDeliver custom interactive conversational experiences Learn more about message types on WhatsApp Cloud API. Business Management API The WhatsApp Business Management API enables you to programmatically manage a WhatsApp Business Account and its associated assets. Manage account assets with Business Management API like: Business phone numbers: Add and remove phone numbers associated with your businessTemplates: Create and modify message templates for scalable messaging. Business Management API also gives you access to account analytics like: Messaging analytics: The number and type of messages sent and delivered.Pricing analytics: Granular pricing breakdowns for delivered messages. Template analytics: Sent/read/delivered template metrics, alongside template message button clicks. Learn more about message templates.Learn more about managing business phone numbers.Learn more about account analytics. Marketing Messages API for WhatsApp MM API for WhatsApp is an API for sending optimized marketing messages on WhatsApp. When you send marketing messages through the MM API for WhatsApp, you can access new features not available on Cloud API and get automatic optimizations, so high engagement messages can reach more customers. The MM API for WhatsApp includes: Quality-based delivery: Up to 9% higher marketing message deliveries over Cloud API for high engagement content.Automated creative optimizations: Automatic enhancements to marketing creative to increase message performance.Performance benchmarks and recommendations: Comparison of read and click rates versus similar templates from businesses in your region.Conversion metrics: Measure marketing messages that lead users to perform app events such as ‘Add to Cart’, ‘Checkout Initiated’, or ‘Purchase’. Learn more about the Marketing Messages API for WhatsApp. Key resources Business portfolios A business portfolio allows organizations to bring all their Meta business assets together so they can be managed in one place. On the WhatsApp Business Platform, a business portfolio mainly serves as a container for WhatsApp Business Accounts (WABA). You must have a business portfolio to use the platform. Business portfolios can be verified, and verification status factors into improved functionality, such as higher throughput and Official Business Account status. Learn more about business portfolios.⁠ WhatsApp business accounts (WABA) A WhatsApp Business Account represents your business, storing metadata and linking to phone numbers, templates, and analytics. Learn more about WhatsApp Business Accounts. Business phone numbers Business phone numbers, real or virtual, are used for sending and receiving WhatsApp messages. They can have display names and earn Official Business Account status. Learn more about business phone numbers. Message templates Templates are customizable messages that you can construct in advance of sending them. Template messages generally require approval before you can send them. Templates are useful for messaging at scale. They are also the only type of message that can be sent to WhatsApp users outside of a customer service window. Templates have quality scores and are subject to various messaging limits. Learn more about message templates. Test resources When you get started with Cloud API, a test WABA and test business phone number are automatically created for you. Test WABAs and test phone numbers are useful for testing purposes, as they have relaxed messaging limits and don’t require a payment method on file in order to send template messages. You can delete your business portfolio and its test resources if: You are an admin on the business portfolio associated with the appNo other apps are associated with the business portfolioThe business portfolio is not associated with any other WABAsThe WABA is not associated with any other business phone numbers. To delete your business portfolio and its test resources: Go to the App Dashboard > WhatsApp > Configuration panel.Locate the Test Account section.Click the Delete button. We recommend using our API Playground when testing endpoints. You can find the playground in the “API Reference” section on the left sidebar of this page. In each reference, there is a “Try it” button which opens the playground. Also helpful for testing is our Postman collection⁠. Tools and integrations WhatsApp Manager WhatsApp Manager is a web app for managing WABAs, phone numbers, templates, and reviewing analytics. Access WhatsApp Manager⁠ Third-party SDKs Some SDKs, like PyWa⁠ (Python wrapper), are available but are not maintained or endorsed by Meta. Security and performance Throughput Business phone numbers can send up to 80 messages per second by default, with capacity upgrades available. Learn more about throughput. Encryption With the Cloud API, every WhatsApp message continues to be protected by Signal protocol encryption that secures messages before they leave the device. This means messages with a WABA are securely delivered to the destination chosen by each business. The Cloud API uses industry standard encryption techniques to protect data in transit and at rest. The API uses Graph API for sending messages and Webhooks for receiving events, and both operate over industry standard HTTPS, protected by TLS. See our Encryption Overview whitepaper for additional details. See the WhatsApp Encryption Overview whitepaper⁠ for additional details. Scaling The Cloud API automatically scales usage within your rate limits. Rate limits Requests made by your app on your WhatsApp Business Account (WABA) are counted against your app’s request count. An app’s request count is the number of requests it can make during a rolling one hour. For the following endpoints, your app can make 200 requests per hour, per app, per WABA, by default. For active WABAs with at least one registered phone number, your app can make 5000 requests per hour, per app, per active WABA. Type of request Endpoint GET / GET, POST, and DELETE //assigned_users GET //phone_numbers GET, POST, and DELETE //message_templates GET, POST, and DELETE //subscribed_apps GET / For the following Credit Line API requests, your app can make 5000 requests per hour. Type of request Endpoint GET //extendedcredits POST //whatsapp_credit_sharing_and_attach GET and DELETE / GET //owning_credit_allocation_configs For more information on how to get your current rate usage, see Headers. In addition, the platform applies several message rate limits: Test message rate limit (for unverified WABAs)Quality rating and messaging limits (for verified WABAs)Capacity rate limit (for all accounts)Business phone rate limit (per phone number) Pair rate limits Business phone numbers can send 1 message every 6 seconds to the same WhatsApp user (0.17 messages/second), which equals about 10 messages per minute or 600 per hour. Exceeding this limit triggers error code 131056 until you are back within the allowed rate. You may send up to 45 messages in a 6-second burst, but this “borrows” from your future quota. After a burst, you must wait the equivalent time it would take to send those messages at the normal rate (e.g., a burst of 20 requires a ~2-minute wait before sending more to that user). To manage post-burst throttling, if a send request fails, retry after 4^X seconds (starting with X=0 and increasing X by 1 after each failure) until successful. Terms and policies User opt-in You must obtain user opt-in before sending message templates. Opt-in must clarify your business name and intent. Learn more about the WhatsApp Business Messaging Policy.⁠ Terms and policies All platform use must comply with WhatsApp’s terms and policies. Using unauthorized third-party tools is prohibited. Learn more about terms and policies.⁠ Next steps Get started with the WhatsApp Business Platform. Learn more Display namesPhone numbersPricingWebhooks Embedded Signup Embedded Signup | Developer Documentation Embedded Signup Updated: Nov 25, 2025 Embedded Signup is an authentication and authorization desktop- and mobile-compatible interface that makes it easy for your business customers to generate the assets you will need to successfully onboard them to the WhatsApp Business Platform. The Embedded Signup flow gathers business-related information from your business customers, automatically generates all WhatsApp assets needed by the platform, and grants your app access to these assets, so you can quickly provide your business customers with WhatsApp messaging services. How it works Embedded Signup leverages the Facebook Login for Business product and our JavaScript SDK. Once configured, you can add a link or button to your website or portal that launches the flow. Business customers who click the link or button will be presented with a new window where they can: authenticate their identity using their Facebook or Meta Business Credentialsaccept terms of service for Cloud API, WhatsApp Business, Meta, Marketing Messages Lite API and Meta Business Tool Termsselect multiple WhatsApp APIs and accept terms of servicegrant your app access to their WhatsApp assetsselect an existing business portfolio or create a new oneselect an existing WhatsApp Business Account (WABA) or create a new oneenter and verify their business phone number (their own, or one you have provided)enter a display name that can appear in place of their number in the WhatsApp client Upon successful completion, Embedded Signup returns the customer’s WABA ID, business phone number ID, and an exchangeable token code, to the window that spawned the flow. You must send this data to your server and use it in a server-to-server call to: exchange the code for a customer-scoped business tokenregister the customer’s business phone number for Cloud API usesubscribe your app to webhooks on the customer’s WABAshare your credit line with the customer (Solution Partners only) When these steps are complete, if you are a Solution Partner or are partnered with one, the customer can begin using your or your partner’s app for messaging immediately. If you are not a Solution Partner, or not partnered with one, the customer must first attach a payment method to their WABA before they can begin messaging. We’re testing a new experience in the Embedded Signup flow for all versions. The flow itself is unchanged, but after completion, you may see a new View your setup guide button. Clicking it will take you to a new setup guidance page in WhatsApp Manager, which offers next steps on: Business verificationResolving integrity issues and accessing Business Support HomeSending the first message via a partner solutionSending business-initiated messages using templates Asset ownership Business customers onboarded via Embedded Signup own all of their WhatsApp assets, which they can leverage with other Meta solutions such as Ads that Click to WhatsApp⁠. Business customers also have full access to WhatsApp Manager⁠, which they can use to access their assets. Note that you cannot restrict this access in any way. Refer to available assets here. Limitations Onboarding limits By default, you can onboard up to 10 new business customers in a rolling 7-day window. Only newly onboarded customers count against this limit. You can see your current onboarded customer count in the WhatsApp Manager > Partner overview panel. You will be notified by email if you approach this limit. If you complete Business Verification, App Review, and Access Verification, we will automatically increase your limit to 200 new business customers in a rolling 7-day window. If you need to onboard more than 200 customers per week, apply to become a Meta Business Partner⁠. Note: Existing WhatsApp Business Accounts (WABAs) that were originally created via the developer app cannot be selected or onboarded directly through the Embedded Signup flow. Business customer messaging limits Business customers onboarded via Embedded Signup start with standard messaging limits, which can be increased through API usage. Business customer phone number limits Business phone numbers can only be registered for use with Cloud API.Business phone numbers already in use with the WhatsApp Business app⁠ are supported, but require you customize the flow to enable WhatsApp Business app user onboarding (aka “Coexistence”).Business customers onboarded via Embedded Signup start with default messaging limits. Cloud API flow See Cloud API Flow for descriptions of each screen that your business customers will be presented with as part of the default implementation of Embedded Signup. Note that if you know information about your customer’s business, you can inject this data, which can significantly reduce the number of screens that your customers have to interact with. Access tokens Embedded Signup generates business tokens. When a business customer completes the Embedded Signup flow, an exchangeable token code will be returned as a message event and captured by the JavaScript SDK. You must exchange this code for a business token using a server-to-server call. If you are a Tech Provider, you will use business tokens exclusively. If you are a Solution Partner, you will use your system user access token (“system token”) to share your credit line with onboarded business customers, and business tokens for everything else. Note that the system user who the token represents must have granted your app the business_management permission, and must have been granted an Admin or Financial Editor role on your business portfolio, in order to be able to share your credit line. Permissions Embedded Signup can be configured to support business messaging products for your customers. If you are only interested in the Cloud API flow you are likely only going to need: whatsapp_business_management — necessary if your app needs access to onboarded customer WhatsApp Business Account settings and message templates.whatsapp_business_messaging — necessary if your app needs access to onboarded customer business phone number settings, or if your app will be used by customers to send and receive messages. You can specify which permissions your app needs during the implementation process. Note that while your app is in development mode, these permissions will appear in Embedded Signup’s authorization screen to anyone who has an admin, developer, or tester role on your app. However, once you switch your app to live mode, only permissions that have been approved for advanced access through the App Review process will appear in the flow. Billing Solution Partners If you are a Solution Partner, you must already have a line of credit⁠ and have accepted the Credit Allocation API terms in the Business Settings > Payments panel in the Meta Business Suite. In addition, you must share your line of credit with any customers as part of the onboarding process. Tech Providers and Tech Partners If you are a Tech Provider or Tech Partner, your onboarded business customers must add a payment method to their WhatsApp Business Account. They can do this by following the steps described in our Add a credit card to your WhatsApp Business Platform account⁠ Help Center article. Sandbox accounts You can test the Embedded Signup flow using your own Facebook account, but this can result in additional business portfolios, WABAs, and business phone numbers. If you don’t want to clutter your Facebook account with test data, you can claim a sandbox test account instead, and use it to simulate a business customer completing the flow. When you complete the flow using the sandbox account, the sandbox account’s WABA ID, business phone number ID, and an exchangeable token code will be returned, just as if it were a real customer completing the flow. Sandbox account limitations Sandbox accounts are valid for 30 days, after which they will be deactivated and must be reclaimed in order to be used again.The sandbox account cannot be used to create additional sandbox business portfolios, WABAs, or business phone numbers; the assets are generated automatically and will appear in the Embedded Signup flow.The sandbox account is associated with the app’s admin. In order for the sandbox account’s assets to appear in the Embedded Signup flow, the app admin must be signed into their Meta developer account.The sandbox account’s business portfolio will not appear in the Meta Business Suite or WhatsApp ManagerYou can exchange the returned token code for the sandbox account’s business token and use it to get data on the account’s WABA ID, but the business phone number cannot be used to send or receive messages. Claiming sandbox accounts To claim your sandbox account: Navigate to the App Dashboard > WhatsApp > Quickstart panel.Locate the Testing Integrations section.Click the Claim sandbox account button. Deleting sandbox accounts Sandbox account deletion is being released gradually over several weeks, starting June 25, 2025. If you are done testing and want to keep your testing environment clean, you can delete your sandbox account. Deleting a sandbox account is irreversible and removes all associated test data. If you accidentally delete your sandbox account but need to test again, you must claim a new one. To delete your sandbox account: Navigate to the App Dashboard > WhatsApp > Quickstart panel.Locate the Testing Integrations section, then locate your sandbox account.Click your sandbox account’s Delete account button. 555 business phone numbers Business customers can claim up to two 555 business phone numbers. These numbers behave the same way as standard business phone numbers (subject to pricing rules, impacted by quality ratings, etc.), but must have their display names approved before they can be used to send messages. In addition, 555 numbers: Have a US country calling code (+1)Have a 555 area codeAre verified automaticallyCannot be migrated to another WhatsApp Business Account, or used outside of the WhatsApp Business platform If your business customers are eligible for 555 numbers, the phone number addition screen will automatically give them the option to choose a 555 number: WhatsApp Asset migration Embedded Signup can be used to migrate onboarded business customer assets in several ways. See Migrating business customer assets. App Review You will not be able to onboard business customers until your app has been approved for advanced access for each of the permissions it requires. See App Review to learn more about App Review and what you must provide in order to complete the process successfully. Embedded Signup Integration Helper The Embedded Signup Integration Helper is a setup and testing tool within the App Dashboard. The tool allows you to: launch Embedded Signup in various flow configurationssee data that gets returned when a business customer completes the flowgenerate implementation code and onboarding queries, which you can copy and paste into your website, business customer portal, and serversend API queries to endpoints you will need to use when onboarding customers who complete the flow You can access the integration helper by navigating to App Dashboard > WhatsApp > Embedded Signup Builder. Note: The Embedded Signup Integration Helper is available only for Business-type apps. You can view your app type at the top of the app dashboard. Localization The Embedded Signup flow is available in 30 languages. The localized flow is automatically triggered based on the language that the business customer uses Facebook in. Arabic, Czech, Danish, Greek, English (UK), Spanish (Spain), Spanish, Finnish, French (France), Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian (bokmal), Dutch, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Swedish, Thai, Turkish, Vietnamese, Simplified Chinese (China), Traditional Chinese (Hong Kong), Traditional Chinese (Taiwan). Next steps Learn how to implement Embedded Signup into your website or portal. Implementation | Developer Documentation Implementation Updated: Mar 25, 2026 This document explains how to implement Embedded Signup v4 and capture the data it generates to onboard business customers onto the WhatsApp Business Platform. Before you startYou must already be a Solution Partner or Tech Provider.If your business customers will be using your app to send and receive messages, you should already know how to use the API to send and receive messages using your own WhatsApp Business Account and business phone numbers. You should also know how to create and manage templates and have a webhooks callback endpoint properly set up to digest webhooks.You must be subscribed to the account_update webhook, as this webhook is triggered whenever a customer successfully completes the Embedded Signup flow, and contains their business information that you will need.If you are a Solution Partner, you must already have a line of credit?.The server where you will be hosting Embedded Signup must have a valid SSL certificate. Step 1: Add allowed domains Load your app in the App Dashboard and navigate to Facebook Login for Business > Settings > Client OAuth settings: Set the following toggles to Yes:Client OAuth loginWeb OAuth loginEnforce HTTPSEmbedded Browser OAuth Loginuse Strict Mode for redirect URIsLogin with the JavaScript SDK Embedded Signup relies on the JavaScript SDK. When a business customer completes the Embedded Signup flow, the customer's WABA ID, business phone number ID, and an exchangeable token code will be returned to the window that spawned the flow, but only if the domain of the page that spawned the flow is listed in the Allowed domains and Valid OAuth redirect URIs fields. Add any domains where you plan to host Embedded Signup, including any development domains where you will be testing the flow, to these fields. Only domains that have enabled HTTPS are supported. Step 2: Create a Facebook Login for Business configuration A Facebook Login for Business configuration defines which permissions to request, and what additional information to collect, from business customers who access Embedded Signup. Navigate to Facebook Login for Business > Configurations: Click the Create from template button and create a configuration from the WhatsApp Embedded Signup Configuration With 60 Expiration Token template. This will generate a configuration for the most commonly used permissions and access levels. Alternatively, you create a custom configuration. To do this, in the Configurations panel, click the Create configuration button and provide a name that will help you differentiate the custom configuration from any others you may create in the future. When completing the flow, be sure to select the WhatsApp Embedded Signup login variation: Select your products you want to onboard for this configuration. When choosing assets and permissions, select only those assets and permissions that you will actually need from your business customers. Assets that are already selected are added by default. For example, if you select the Catalogs asset but don't actually need access to customer catalogs, your customers will likely abandon the flow at the catalog selection screen and ask you for clarification. When you complete the configuration flow, capture your configuration ID, as you will need it in the next step. Step 3: Add Embedded Signup to your website Add the following HTML and JavaScript code to your website. This is the complete code needed to implement Embedded Signup. Each portion of the code will be explained in detail below. Session logging message event listener This portion of the code creates a message event listener that captures the following critical information:The business customer's newly generated asset IDs, if they successfully completed the flowThe name of the screen they abandoned, if they abandoned the flowAn error ID, if they encountered an error and used the flow to report it // Session logging message event listener window.addEventListener('message', (event) => { if (!event.origin.endsWith('facebook.com')) return; try { const data = JSON.parse(event.data); if (data.type === 'WA_EMBEDDED_SIGNUP') { console.log('message event: ', data); // remove after testing // your code goes here } } catch { console.log('message event: ', event.data); // remove after testing // your code goes here } }); This information will be sent in a message event object to the window that spawned the flow and will be assigned to the data constant. Add your own custom code to the try-catch statement that can send this object to your server. The object structure will vary based on flow completion, abandonment, or error reporting, as described below. Successful flow completion structure: On the final screen, both clicking Finish and closing the popup (for example, by clicking the X button) are considered successful onboarding. In both scenarios, the exchangeable token code and the session info object containing the customer's asset IDs will be returned. Exiting on the final screen is not considered a cancel event. { data: { phone_number_id: '', waba_id: '', business_id: '', ad_account_ids: ['', ''], page_ids: ['', ''], dataset_ids: ['', ''], catalog_ids: ['', ''], instagram_account_ids: ['', ''], waba_ids: ['', ''] }, type: 'WA_EMBEDDED_SIGNUP', event: '', } Placeholder Description Example value The business customer's business phone number ID 106540352242922 The business customer's WhatsApp Business Account ID. 524126980791429 The business customer's business portfolio ID. 2729063490586005 Only included if the customer selected ad accounts during the flow. The business customer's ad account ID. 4052175343162067 Only included if the customer selected Facebook Pages during the flow. The business customer's Facebook Page ID. 1791141545170328 Only included if the customer selected datasets during the flow. The business customer's dataset ID. 524126980791429 Only included if the customer selected catalogs during the flow. The business customer's catalog ID. 8827498273649182 Only included if the customer selected Instagram accounts during the flow. The business customer's Instagram account ID. 1749204838281942 (in waba_ids array) Only included for multi-WABA flows. Array of the business customer's WhatsApp Business Account IDs. 524126980791429 Indicates the customer successfully completed the flow. Possible Values: FINISH: Indicates successful completion of Cloud API flow. FINISH_ONLY_WABA: Indicates user completed flow without a phone number. FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING: Indicates user completed flow with a WhatsApp business app number. FINISH_OBO_MIGRATION: Indicates user completed an on-behalf-of migration flow. FINISH_GRANT_ONLY_API_ACCESS: Indicates user completed a grant-only API access flow. ERROR: Indicates the user encountered an error during the flow. FINISH Abandoned flow structure: { data: { current_step: '', }, type: 'WA_EMBEDDED_SIGNUP', event: 'CANCEL', } Placeholder Description Example value Indicates which screen the business customer was viewing when they abandoned the flow. See Embedded Signup flow errors for a description of each step. PHONE_NUMBER_SETUP User reported errors { data: { error_message: '', error_code: '', session_id: '', timestamp: '', }, type: 'WA_EMBEDDED_SIGNUP', event: 'CANCEL', } Placeholder Description Example value The error description text displayed to the business customer in the Embedded Signup flow. See Embedded Signup flow errors for a list of common errors. Your verified name violates WhatsApp guidelines. Please edit your verified name and try again. Error code. Include this value if you contact support. 524126 Unique session ID generated by Embedded Signup. Include this ID if you contact support. f34b51dab5e0498 Unix timestamp indicating when the business customer used Embedded Signup to report the error. Include this value if you are contacting support. 1746041036 Parse this object on your server to extract and capture the customer's phone number ID and WABA ID, or to determine which screen they abandoned. See Abandoned flow screens for a list of possible values and the screens they correspond to. Note that the try-catch statement in the code above has two statements that can be used for testing purposes: console.log('message event: ', data); // remove after testing console.log('message event: ', event.data); // remove after testing These statements just dump the returned phone number and WABA IDs, or the abandoned screen string, to the JavaScript console. You can leave this code in place and keep the console open to easily see what gets returned when you are testing the flow, but you should remove them when you are done testing. Response callback Whenever a business customer successfully completes the Embedded Signup flow, we will send an exchangeable token code in a JavaScript response? to the window that spawned the flow. // Response callback const fbLoginCallback = (response) => { if (response.authResponse) { const code = response.authResponse.code; console.log('response: ', code); // remove after testing // your code goes here } else { console.log('response: ', response); // remove after testing // your code goes here } } The callback function assigns the exchangeable token code to a code constant. Add your own, custom code to the if-else statement that sends this code to your server so you can later exchange it for the customer's business token when you onboard the business customer. Note that the if-else statement in the code above has two statements that can be used for testing purposes: console.log('response: ', code); // remove after testing console.log('response: ', response); // remove after testing These statements just dump the code or the raw response to the JavaScript console. You can leave this code in place and keep the console open to easily see what gets returned when you are testing the flow, but you should remove them when you are done testing. Launch method and callback registration This portion of the code defines a method which can be called by an onclick event that registers the response callback from the previous step and launches the Embedded Signup flow. Add your configuration ID here. // Launch method and callback registration const launchWhatsAppSignup = () => { FB.login(fbLoginCallback, { config_id: '', // your configuration ID goes here response_type: 'code', override_default_response_type: true, extras: { setup: {}, } }); } Launch button This portion of the code defines a button that calls the launch method from the previous step when clicked by the business customer. Testing Once you have completed all of the implementation steps above, you should be able to test the flow by simulating a business customer while using your own Meta credentials. Anyone who you have added as an admin or developer on your app (in the App Dashboard > App roles > Roles panel) can also begin testing the flow, using their own Meta credentials. Onboarding business customers Embedded Signup generates assets for your business customers, and grants your app access to those assets. However, you still need to make a series of API calls to fully onboard new business customers who have completed the flow. The API calls you must make to onboard customers are different for Solution Partners and Tech Providers/Tech Partners.Onboarding customers as a Solution PartnerOnboarding customers as a Tech Provider Onboarding business customers as a Tech Provider or Tech Partner | Developer Documentation Onboarding business customers as a Tech Provider or Tech Partner Updated: Nov 14, 2025 This document describes the steps Tech Providers and Tech Partners must perform to onboard new business customers who have completed the Embedded Signup flow. If you are a Tech Provider or Tech Partner, any business customer who completes your implementation of the Embedded Signup flow will not be able to use your app to access their WhatsApp assets or send and receive messages (if you are offering messaging services) until you complete these steps. What you will needthe business customer’s WABA ID (returned via session logging or API request)the business customer’s business phone number ID (returned via session logging or API request)your app ID (displayed at the top of the App Dashboard)your app secret (displayed in the App Dashboard > App settings > Basic panel) Also, if you wish to test messaging capabilities using the customer’s business phone number, you will need a WhatsApp phone number that can already send and receive messages from other WhatsApp numbers. Perform all of the requests described below using server-to-server requests. Do not use client-side requests. Step 1: Exchange the token code for a business token Request parameters Placeholder Description Example value Required. Your app ID. This is displayed at the top of the App Dashboard. 236484624622562 Required. Your app secret. You can get this from the App Dashboard > App Secret > Basic panel. 614fc2afde15eee07a26b2fe3eaee9b9 Required. The code returned by Embedded Signup when the customer successfully completed the flow. AQBhlXsctMxJYbwbrpybxlo9tLPGy-QAmjBJA03jxLos43wxlBlrYozY5C33BXJULd133cOJf_5y6EkJZYMrAmW-EMj3Wdap9-NUM2nS4s8tC-ES7slBhh6QpCFM7-SzpI-iqsjqTGyxbUUW3AeaEyLkeZFIkBgcQ_SOxo9HShm20SDR5_n7AT9ZJ5dcgpqBQykNT-pQ8V7Ne9-sr6RLAWtJMF7-Zx6ABudRcWIN53tUTtquDVNuq3lrco4BlVQAv-54tR83Ae0ODN9Uet6j-BVLuetXhQCM3sz9RdgedlbxkidMbkztvYX1j7baOrJxyLyYGWYgbnUrKRQKCtWTsO5ekIGFgtbpS8UPJNqV6j8E5XKPJ8QA7ZFqzkB0s2O__J5FrjHzc_rDo1EuRbw98ihHDzQnvuXeHapEyfhLDJct0A Response parameters Placeholder Description Example value The customer’s business token. EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn Step 2: Subscribe to webhooks on the customer’s WABA Request parameters Placeholder Description Example value String Optional. Graph API version. v25.0 String Required. The business customer’s business token. EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn String Required. WhatsApp Business Account ID. 102290129340398 Step 5: Instruct the customer to add a payment method Instruct your customer to use the WhatsApp Manager to add a payment method. You can provide them with the following Help Center link: https://www.facebook.com/business/help/488291839463771⁠ Alternatively, you can instruct them to:Access the WhatsApp Manager > Overview panel at https://business.facebook.com/wa/manage/home/⁠Click the Add payment method buttonComplete the flow Once your customer adds a payment method, they are fully onboarded onto the WhatsApp Business Platform and can begin using your app to access their WhatsApp assets and send and receive messages (if you are providing them with that service). Onboarding business customers as a Solution Partner | Developer Documentation Onboarding business customers as a Solution Partner Updated: Nov 14, 2025 This document describes the steps Solution Partners must perform to onboard new business customers who have completed the Embedded Signup flow. If you are a Solution Partner, any business customer who completes your implementation of the Embedded Signup flow will not be able to use your app to access their WhatsApp assets or send and receive messages until you complete these steps. What you will needthe business customer’s WABA ID (returned via session logging or API request)the business customer’s business phone number ID (returned via session logging or API request)your app ID (displayed at the top of the App Dashboard)your app secret (displayed in the App Dashboard > App settings > Basic panel)your credit line ID (displayed in Business Manager > Business Settings > Business Info or returned via API request)your system user access token (“system token”) Also, if you wish to test messaging capabilities using the customer’s business phone number, you will need a WhatsApp phone number that can already send and receive messages from other WhatsApp numbers. Perform all of the requests described below using server-to-server requests. Do not use client-side requests. Step 1: Exchange the token code for a business token Request parameters Placeholder Description Example value Required. Your app ID. This is displayed at the top of the App Dashboard. 236484624622562 Required. Your app secret. You can get this from the App Dashboard > App Secret > Basic panel. 614fc2afde15eee07a26b2fe3eaee9b9 Required. The code returned by Embedded Signup when the customer successfully completed the flow. AQBhlXsctMxJYbwbrpybxlo9tLPGy-QAmjBJA03jxLos43wxlBlrYozY5C33BXJULd133cOJf_5y6EkJZYMrAmW-EMj3Wdap9-NUM2nS4s8tC-ES7slBhh6QpCFM7-SzpI-iqsjqTGyxbUUW3AeaEyLkeZFIkBgcQ_SOxo9HShm20SDR5_n7AT9ZJ5dcgpqBQykNT-pQ8V7Ne9-sr6RLAWtJMF7-Zx6ABudRcWIN53tUTtquDVNuq3lrco4BlVQAv-54tR83Ae0ODN9Uet6j-BVLuetXhQCM3sz9RdgedlbxkidMbkztvYX1j7baOrJxyLyYGWYgbnUrKRQKCtWTsO5ekIGFgtbpS8UPJNqV6j8E5XKPJ8QA7ZFqzkB0s2O__J5FrjHzc_rDo1EuRbw98ihHDzQnvuXeHapEyfhLDJct0A Response parameters Placeholder Description Example value The customer’s business token. EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn Step 2: Subscribe to webhooks on the customer’s WABA Request parameters Placeholder Description Example value Required. The customer’s business token. EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn Required. The customer’s WABA ID. 102290129340398 Step 3: Share your credit line with the customer We are currently testing new steps for sharing your credit line with onboarded business customers. These steps will eventually replace this step, so if you wish to implement these steps now, see Alternate method for sharing your credit line. Note: If you are using the below API i.e. whatsapp_credit_sharing_and_attach, you would need to add your System User to the shared WhatsApp Business Accounts as a pre-requisite. Please refer to this doc for steps. Request parameters Placeholder Description Example value Required. The business’s currency, as a three-letter currency code. Support values are: AUD EUR GBP IDR INR USD This currency is used for invoicing and corresponds to pricing rates. USD Required. The customer’s WABA ID. 102290129340398 Required. Your extended credit line ID. 1972385232742146 Required. Your system token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD Response parameters Placeholder Description Example value The extended credit line’s allocation configuration ID. Save this ID if you want to verify that your credit line has been shared with the customer. 58501441721238 The customer’s WABA ID. 102290129340398 Cloud API flow | Developer Documentation Cloud API flowUpdated: Nov 11, 2025This document describes the default screens that your business customers will be presented with as they navigate the Embedded Signup flow. Note that if you inject pre-filled data, you can pre-fill some of these screens, and bypass many of them entirely, reducing the likelihood of errors and making it much easier for your business customers to onboard onto the platform. This is the UI flow for the latest version v4. Screens Authentication screenThis screen authenticates business customers using their Facebook or Meta Business Suite credentials. Authorization screenThis screen describes the data the business customer will be permitting your app to access. Business Asset Selection ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Business Asset Creation ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Phone number addition screenThis screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead. Phone number verification screenThis screen allows the business customer to verify ownership of the business phone number they entered in the previous step. Permissions review screenThis screen provides a summary of the permissions the business customer will be granting to your app. Success screenThis screen indicates that Meta successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform. Customizing the default flow | Developer Documentation Customizing the default flowUpdated: Nov 14, 2025This document provides an overview of the various ways that you can customize Embedded Signup’s default flow to present different versions of the flow to your business customers. Onboarding WhatsApp Business app users (aka “Coexistence”)You can configure Embedded Signup to allow business customers to onboard using their existing WhatsApp Business app account and phone number: Businesses who are successfully onboarded after choosing this option will then be able to use your app to message their customers at scale, but still have the ability to send messages on a one-to-one basis using the WhatsApp Business app. Pre-filling screensYou can pre-fill many of Embedded Signup’s default flow screens with a business customer’s business data. Pre-filling screens can dramatically reduce the amount of input and interaction required by your customers, and shorten flow. Bypassing phone number addition and verificationYou can customize Embedded Signup to entirely skip the phone number addition and verification screens. This can be useful if you don’t want business customers to have to enter a phone number, retrieve the verification code sent to the number, and then verify the code using the number. App-Only InstallApp-Only Install is a way to configure Embedded Signup so that only business tokens can be used to access assets owned by customers onboarded via the flow. This does not affect the flow itself, only which tokens must be used. Onboarding WhatsApp Business app users (aka "Coexistence") | Developer Documentation Onboarding WhatsApp Business app users (aka "Coexistence") Updated: Mar 20, 2026 You can configure Embedded Signup to allow business customers to onboard using their existing WhatsApp Business app⁠ account and phone number. Customers who are successfully onboarded after choosing this option will then be able to use your app to message their customers at scale, but still have the ability to send messages on a one-to-one basis using the WhatsApp Business app, while keeping messaging history between both apps in sync. How it works When you configure Embedded Signup for WhatsApp Business app phone numbers, a business customer who goes through the flow will be given the option to connect their existing WhatsApp Business app account to Cloud API: If they choose this option and enter their WhatsApp Business app phone number, they will be presented a verification code to enter. The message instructs the business to copy the verification code and follow the steps: Expect to receive a message from the official Facebook Business Account. Click Connect: Tap the Connect to the Business Platform button to continue the onboarding process. Tap the Confirm button in the app to give the business the option to share their chat history with you. Paste the verification code. They can complete the remainder of the Embedded Signup flow. This returns their asset IDs and exchangeable token code to the spawning window, as normal. You can then use that information in API calls to (1) onboard the business customer the same way you would any other business customer and (2) synchronize their contacts and messaging history (if permitted by the business) so you can populate it in your app. Requirementsthe business customer must be using WhatsApp Business app version 2.24.17 or higher.the business customer’s phone number country code must be supportedyou must already be a Solution Partner or Tech Provideryou must know how to use Cloud APIyour webhook callback must be be able successfully accept and digest webhooksyou must be using Embedded Signup with session logging LimitationsIn order to remain compatible with the WhatsApp Business app, business phone numbers that are in use with both the WhatsApp Business app and Cloud API have a fixed throughput of 20 mps.If your business customer worked with a partner in the past and still shares the previous credit line, they may see an error when attempting to switch to a new partner. Follow the guide to resolve the error. Unsupported countries WhatsApp Business account phone numbers with country codes from the following countries are not supported:NigeriaSouth Africa Pricing After a business customer has been onboarded to Cloud API, messages sent by the business via the WhatsApp Business app will continue to be free, but messages sent via API will be subject to Cloud API pricing. See our API Solutions for WhatsApp Business App Users pricing explainer PDF for breakdowns of common pricing scenarios. Customer service window Customer service windows will only be opened when a WhatsApp user messages a business customer who is already onboarded onto Cloud API. If a WhatsApp user messages a business just prior to the business being onboarded onto Cloud API, the business can only respond with a template message, since no customer service was opened. If the user messages the business after it has been onboarded onto Cloud API, a customer service window will be opened as normal, and the business can then respond with a non-template message. The 24-hour customer service window restriction applies to messages sent via Cloud API. Messages sent from the WhatsApp Business app are not subject to the customer service window and do not create, extend, or affect Cloud API conversation windows or Cloud API pricing. Feature comparison The following table describes features available to business customers who have been onboarded to Cloud API, as well as any changes to WhatsApp Business app functionality post-onboarding. Existing feature on the WhatsApp Business App Changes to features on the WhatsApp Business App AFTER onboarding to Cloud API Is the WhatsApp Business app feature supported on Cloud API? Individual (1:1) chats Message Edit/Revoke is now supported. Supported. All chat messages in the most recent 6 months can be synchronized. Messages sent and received are mirrored between the Cloud API and WhatsApp Business app. Contacts No change. Supported. All contacts with a WhatsApp number can be synchronized. Group chats No change. Not supported. Group chats will not be synchronized. Disappearing messages Disappearing messages will be turned off for all individual (1:1) chats Not supported. View once message⁠ View once messages will be disabled for all individual (1:1) chats Not supported. Live location message Live location messages will be disabled for all individual (1:1) chats Not supported. Broadcast lists Broadcast list will be disabled. Business will not be able to create new Broadcast Lists. Existing Broadcast Lists will become read-only. Not supported. Voice and video calls No change. Not supported. Business tools (eg. catalog, orders, status) No change. Not supported. Messaging tools (e.g., marketing messages, greeting message, away message, quick replies, labels) No change. Not supported. Business profile (eg. business name, address, website) No change. Not supported. Channels No change. Not supported. Linked devices Businesses can link up to four WhatsApp “companion” clients to their WhatsApp Business app account on other devices (described as “linked devices⁠” in our Help Center). All companion clients are supported, except for WhatsApp for Windows⁠ and WhatsApp for WearOS⁠. Once a business customer onboards to Cloud API with an existing WhatsApp Business app account and number, all companion apps will be unlinked from the account, and the business can then re-link any supported companion apps. WhatsApp users who use an unsupported companion client to message an onboarded business can do so, but the message will not trigger messages webhooks, so the business won’t be able to mirror the message in their own app. Messages sent from an onboarded business (by any means) that are viewed in an unsupported companion device will appear with placeholder text, instructing the WhatsApp user to view the message in their primary device. Setting up your app Step 1: Subscribe to webhooks Navigate to the App Dashboard > WhatsApp > Configuration panel and subscribe your app to the following WhatsApp Business Account webhook topic fields, and make sure your app’s callback code can digest payloads for each of them. Note that these fields are in addition to any fields you are already subscribed to as a solution provider.history — describes past messages the business customer has sent/receivedsmb_app_state_sync — describes the business customer’s current and new contactssmb_message_echoes — describes any new messages the business customer sends with the WhatsApp Business app after having been onboarded Step 2: Customize Embedded Signup Add a featureType property set to whatsapp_business_app_onboarding to the extras object in the launch method and callback registration portion of the Embedded Signup implementation code. To verify that you have enabled the feature correctly, access your implementation of Embedded Signup. If the WABA selection screen has been replaced with a screen that gives you the option to connect your existing WhatsApp Business account, the feature is enabled: Step 3: Surface Embedded Signup to customers Once you have confirmed that the feature has been enabled, surface Embedded Signup to your business customers. Note that when a business completes the flow and you onboard the customer, you have 24 hours to synchronize their messaging history, otherwise they must be offboarded and they must complete the flow again. For this reason, we recommend that you:onboard and synchronize as soon as the business completes the flowinform the business that you are synchronizing their WhatsApp Business app dataadvise them to keep the WhatsApp Business app open to facilitate the synchronization process Onboarding and synchronization can take several minutes, depending on a number of factors such as the size of the business’s messaging history, their internet speed, how quickly you can digest webhooks, etc. When you complete the onboarding process, the WhatsApp Business app will automatically refresh and indicate to the business that their number is now connected to the API: After you finish synchronizing the business’s messaging history, we recommend that you inform the customer that the process is complete. Onboarding business customers When a business customer successfully completes the Embedded Signup flow, their asset IDs and an exchangeable token code will be returned to the window that spawned the flow, as normal, but the session event payload will have event set to FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING: { data: { waba_id: "" }, type: "WA_EMBEDDED_SIGNUP", event: "FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING", version: 3 } Capture the customer’s asset IDs and exchangeable token code and use them to onboard the customer as you normally would, but skip the phone number registration step, as the number is already registered.Onboarding business customers as a Solution ProviderOnboarding business customers as a Tech Provider Once you have completed these onboarding steps, you can begin the messaging history synchronization process. Check onboarding status (optional) If you wish, you can check if the customer’s business phone number is registered for both Cloud API and WhatsApp Business app use by requesting the is_on_biz_app and platform_type fields on the business phone number ID: Example request: Example response: If is_on_biz_app is true and platform_type is CLOUD_API, the business phone number is able to use Cloud API and the WhatsApp Business app: Synchronizing WhatsApp Business app data After you onboard the business customer, you have 24 hours to synchronize their contacts and messaging history, otherwise they must be offboarded and complete the flow again. For this reason, we recommend that you begin the synchronization process as soon as you finish onboarding the business. As a reminder, make sure that you subscribed to the business’s WABA when you onboarded the business, and that you are subscribed to the additional webhook fields, otherwise you will miss important webhooks. Step 2: Initiate message history synchronization Upon success, one or more history webhooks will be triggered, depending on if the business chose to share their messaging history with you. Note that you can only perform this step once. If you need to perform it again, the customer must first offboard, then complete the Embedded Signup flow again. Messaging history shared If the business chose to share their messaging history with you, a series of history webhooks will be triggered, describing each message sent to, or received from, WhatsApp users within a set period of time. See history for a description of the contents of these webhooks and how they are organized. Messaging history not shared If the business chose not to share their messaging history with you, a history webhook with error code 2593109 will be triggered instead. Step 3: Mirror new WhatsApp Business app messages Onboarded businesses are still able to use the WhatsApp Business app and supported companion devices to send and receive messages. Each time a business sends a message with one of these apps, it triggers an smb_message_echoes webhook, which you must digest and display in the contact message thread history in your app. Reporting conversion activity Onboarded business customers may run Click to WhatsApp ads, so we recommend that you report purchase/lead-gen signals on behalf of the business using the Conversions API. See Conversions API for business messaging. Offboarding business customers Instead, your business customers can use the WhatsApp Business app to disconnect from Cloud API by navigating to the Settings > Account > Business Platform and clicking the Disconnect Account button. When a business customer disconnects from Cloud API, an account_update webhook with a PARTNER_REMOVED event is triggered. Errors If you onboard a business customer with a WhatsApp Business app phone number, you may receive an unsupported messages webhook with error code 131060. This is expected and can occur in the following scenarios:First-time messaging: A WhatsApp user messages your business for the first time. This is especially common when users tap one of your ads that click to WhatsApp⁠ and immediately send a message. The error typically resolves within a few seconds, after which messages are delivered normally.Unsupported companion device: A WhatsApp user with an unsupported companion device sends or receives a message to or from your business. If you receive this webhook, instruct the business to check the WhatsApp Business app for the message. Need support? For Coexistence onboarding, choose:Question Topic: “WABiz: Onboarding” and “TechProvider: Onboarding”Request Type: “Embedded Signup - Coexistence Onboarding” For Coexistence API issues, choose:Question Topic: “WABiz: Cloud API”Request Type: “Coexistence Data Synchronization APIs and Webhooks” Pre-filling screens | Developer Documentation Pre-filling screens Updated: Nov 10, 2025 If you know details about your customer’s business, such as its name and address, you can inject this data into Embedded Signup. This can pre-fill screens or bypass them altogether, dramatically reducing the amount of input and interaction required by your customers. For example, here is the business portfolio screen, pre-filled with business’s name, email address, website, country, and a pre-verified business phone number: We recommend that you inject business portfolio data, a pre-verified number, and phone profile data. Injecting this data provides the best experience for your customer, as it:entirely pre-fills the business portfolio screenbypasses the WhatsApp Business Account (WABA) selection and creation screensbypasses the business phone number selection and verification screensautomatically sets the business phone number’s profile information in the WhatsApp client Embedded Signup Integration Helper The Embedded Signup Integration Helper provides a convenient way for you to create pre-filled data payloads and test their impact on the flow. To access the payload tool:Navigate to App Dashboard > WhatsApp > Embedded Signup Builder.Locate the Embedded Signup Setup section.Locate the Embedded Signup Pre-fill row.Click the Edit pre-fill data button. Injecting Data The FB.login function, which gets called when a business customer launches Embedded Signup, accepts an object as an argument. Use this object’s extras.setup property to inject data: // Launch method and callback registrationconst launchWhatsAppSignup =()=>{ FB.login(fbLoginCallback,{ config_id:'',// your configuration ID goes here response_type:'code', override_default_response_type:true, extras:{ setup:{ business:{// Business portfolio data goes here}, preVerifiedPhone:{// Pre-verified phone number IDs go here}, phone:{// Phone number profile data goes here}, whatsAppBusinessAccount:{// WABA IDs go here}}, featureType:'', sessionInfoVersion:'3',}});} Business portfolio data You can inject the following business portfolio details into the business portfolio screen:business portfolio namebusiness portfolio email addressbusiness portfolio websitebusiness portfolio country (as well as additional address details)business phone number Alternatively, you can inject just an existing business portfolio ID, and its existing details will automatically be injected into the screen. This can be useful if you want a pre-verified phone number to be associated with the customer’s existing business portfolio. Injecting business portfolio data will pre-fill the business portfolio screen and also cause Embedded Signup to skip the WABA selection and WABA creation screens. Injecting business phone number data will pre-fill the phone number addition screen: Note that even if you inject data, the business customer can still edit this data using the Edit button, if they wish. When a business customer completes the flow, the business portfolio information you injected will be used to create the business customer’s business portfolio and WABA. Business object syntax setup: { business: { id: , name: '', email: '', website: '', address: { streetAddress1: '', streetAddress2: '', city: '', state: '', zipPostal: '', country: '' }, phone: { code: , number: '' }, timezone: '' } } Business object parameters Placeholder Description Example value Integer or null Required if using an existing business portfolio, otherwise set to null or omit to create a new portfolio. Set to the business customer’s existing business portfolio ID if you want to pre-fill the screen with data already set on the business portfolio, or if you want to associate a pre-verified phone number with this portfolio. If set to a portfolio ID, we will check if the business customer owns the portfolio. If they own it, we will inject its existing data into the flow and ignore all other business object properties. If they do not own it, we will inject business.name, business.email, business.website, and address.country values, if they are all set. If any are not set, the flow will display the default business portfolio screen instead. Set to null (or omit the id property entirely) if you want to create a new business portfolio based on injected business.name, business.email, business.website, and address.country values. 2729063490586005 String Required if creating a new business portfolio. Business portfolio name. If this name matches the name of an existing business portfolio owned by the business customer, the existing portfolio will be used instead (it will be treated as if you assigned the existing portfolio’s ID to the id property). This name will also be used as the WhatsApp Business Account name, which is only visible in the WhatsApp Manager. Maximum 100 characters. Wind & Wool String Required if creating a new business portfolio. The business’s email address. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. support@windandwool.com Integer Required if injecting a business phone number. Business phone number country calling code. 1 String Required if injecting a business phone number. Business phone number, without country calling code. 6505559999 String Required if creating a new business portfolio. The business’s website URL. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. https://windandwool.com/ String The business’s street address, line 1. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. 1 Hacker Way String The business’s street address, line 2. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. Suite 1 String The business’s city address. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. Menlo Park String The business’s state address. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. California String The business’s zip code address. This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. 94025 String Required if creating a new business portfolio. Business address ISO 3166-1 alpha-2⁠ country code. US String The business’s time zone in UTC offset⁠ format. UTC-07:00 Example Business Object setup:{ business:{ name:'Wind & Wool', email:'support@windandwool.com', website:'https://windandwool.com/', address:{ streetAddress1:'1 Hacker Way', streetAddress2:'Suite 1', city:'Menlo Park', state:'California', zipPostal:'94025', country:'US'}, phone:{ code:1, number:'6505559999'}, timezone:'UTC-07:00'}} Pre-verified phone numbers You can inject a pre-verified business phone number ID into Embedded Signup, which will cause Embedded Signup to skip the phone number addition and phone number verification screens. If you are injecting a pre-verified phone number along with business portfolio data (either creating a new portfolio or using an existing one), the business portfolio screen will be pre-filled with the pre-verified number: If you are not injecting business portfolio data along with a pre-verified number ID, the number will appear in the WABA selection screen: PreVerifiedPhone object syntax setup: { preVerifiedPhone: { ids: [ '' ] } } Replace with a unique, pre-verified business phone number ID. Note that although the ids value accepts an array of strings, if you include more than one pre-verified business phone number ID, only the first ID in the array will appear in the WABA selection screen. Phone profile data You can inject the following phone number profile data. This data does not pre-fill any Embedded Signup screens, but it does populate the business phone number’s profile in the WhatsApp client, which is visible to WhatsApp users.Phone number profile display namePhone number categoryPhone number description If you do not include this data, the category will be set to Other, and the business customer must set or edit their profile data on their own. Phone object syntax setup: { phone: { displayName: '', category: '', description: '' } } Phone object parameters Placeholder Description Example value String Required. Business profile display name, visible to WhatsApp users in the WhatsApp client (see screenshot above). Wind & Wool String Required. Business profile display category. APPAREL String Required. Business phone number profile description.Maximum 512 characters.Rendered emojis are supported however their unicode values are not. Emoji unicode values must be Java- or JavaScript-escape encoded.Hyperlinks can be included but will not render as clickable links.Markdown is not supported. Bespoke artisan apparel and lifestyle goods from upcoming designers. Example phone object setup:{ phone:{ displayName:'Wind & Wool', category:'APPAREL', description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}} WhatsApp Business Accounts If you are injecting a pre-verified phone number, you can also include a WABA ID. This will associate the pre-verified number with the existing WABA instead of with a new one that the business customer would be prompted to create as part of the flow. WhatsAppBusinessAccount object syntax setup: { whatsAppBusinessAccount: { ids: '' } } Replace with a unique WABA ID. Example whatsAppBusinessAccount object This example associates a pre-verified phone number with an existing WABA. setup:{ preVerifiedPhone:{ ids:['106540352242922']}, whatsAppBusinessAccount:{ id:['432428883295692']}} Examples New business portfolio, pre-verified number, and display profile // Launch method and callback registrationconst launchWhatsAppSignup =()=>{ FB.login(fbLoginCallback,{ config_id:'31602279155865', response_type:'code', override_default_response_type:true, extras:{ setup:{ business:{ name:'Wind & Wool', email:'support@windandwool.com', website:'https://windandwool.com/', address:{ streetAddress1:'1 Hacker Way', streetAddress2:'Suite 1', city:'Menlo Park', state:'California', zipPostal:'94025', country:'US'}, phone:{ code:1, number:'6505559999'}, timezone:'UTC-07:00'}, preVerifiedPhone:{ ids:['106540352242922']}, phone:{ displayName:'Wind & Wool', category:'APPAREL', description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}}, featureType:'', sessionInfoVersion:'3',}});} Existing business portfolio, pre-verified number, and display profile // Launch method and callback registrationconst launchWhatsAppSignup =()=>{ FB.login(fbLoginCallback,{ config_id:'31602279155865', response_type:'code', override_default_response_type:true, extras:{ setup:{ business:{ id:'2729063490586005'}, preVerifiedPhone:{ ids:['106540352242922']}, phone:{ displayName:'Wind & Wool', category:'APPAREL', description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}}, featureType:'', sessionInfoVersion:'3',}});} Pre-verified phone numbers | Developer Documentation Pre-verified phone numbers Updated: Dec 12, 2025 This document explains how to offer your business customers pre-verified business phone numbers. Pre-verified business phone numbers are WhatsApp business phone numbers that have already been verified by you, eliminating the need for customers to have to contact you for a one-time password. Note that pre-verified business phone numbers are represented by WhatsApp Business Pre-Verified Phone Number objects, which are temporary. When a business customer selects one of these numbers and completes the Embedded Signup flow, the temporary object will be replaced by a valid WhatsApp Business Phone Number object. You must get this new object's ID and use it to register the number within 90 days. RequirementsYour business must be an approved Solution Partner.The app user must be a business admin on the business account that pre-verified business phone numbers are added to.A User or System User access token.The business_management permission.Business phone numbers must be valid. LimitationsYou are responsible for keeping track of who has claimed a pre-verified business phone number.If a pre-verified business phone number is not claimed by an end client in the Embedded Signup flow within 90 days of verification, the number will revert to an unverified status and must be verified again to have its status restored for another 90 days.Unclaimed pre-verified business phone numbers can't be re-verified until 45 days before they are scheduled to revert to an unverified status. This time is indicated by the verification_expiry_time field.If you add a phone number to your pool of pre-verified business phone numbers (Step 1) but do not verify it within 90 days (Step 3), it will be removed from your pool and you will have to add it again.Once a business customer claims a pre-verified business phone number, you have 90 days to register it. Displaying pre-verified numbers in Embedded Signup You can display pre-verified business phone numbers in the Embedded Signup flow using pre-filled form data. To do this, add a preVerifiedPhone object with an ids property to the setup object and assign the IDs of your pre-verified business phone numbers as an array of strings to the ids property: { scope: '', extras: { feature: '', setup: { preVerifiedPhone: { ids: [] } } } } For example: { scope: 'business_management,whatsapp_business_management', extras: { feature: 'whatsapp_embedded_signup', version: 2, setup: { business: { name: 'Acme Inc.', email: 'johndoe@acme.com', phone: { code: 1, number: '6505551234' }, website: 'https://www.acme.com', address: { streetAddress1: '1 Acme Way', city: 'Acme Town', state: 'CA', zipPostal: '94000', country: 'US' }, timezone: 'UTC-08:00' }, phone: { displayName: 'Acme Inc.', category: 'ENTERTAIN', description: 'Gears and widgets' }, preVerifiedPhone: { ids: ['106540352242922','105954558954427'] } } } } Note that if a pre-verified business phone number with a status of VERIFIED is not claimed within 90 days of verification, its status will be set to UNVERIFIED but it will still appear in the Embedded Signup flow. If a business customer attempts to claim an unverified number, they must complete verification on their own, which means they must request a one-time password from you. To prevent this experience, we recommend that you keep track of when you verified a number and re-verify it before it reverts to an unverified state. If you don't know when you last verified a given pre-verified business phone number, request the code_verification_time and verification_expiry_time fields on the pre-verified business phone number ID. These fields indicate its most recent verification time and its verification expiration time. Determining if a number has been claimed through Embedded Signup See Getting claimed phone number IDs. Getting and registering claimed phone numbers Once a business customer claims a pre-verified business phone number, it will be replaced with a verified WhatsApp business phone number (a WhatsApp Business Phone Number object with a code_verification_status set to VERIFIED). You will have 90 days to register this number using its ID. If you do not register it within this time frame, it will revert to an UNVERIFIED status and you will have to request a new verification code and use the code to verify the WhatsApp business phone number again. Getting claimed numbers via session logging If you are using session logging, the ID will be returned in a message event and captured by your event listener. Send this ID to your server and then use it to register the WhatsApp business phone number. Getting claimed numbers via API Parse for the display_phone_number property on each object returned in the result set. If an object in the result set has a display_phone_number value that matches a number you used to create a pre-verified business phone number, the object represents the WhatsApp business phone number that has replaced the pre-verified business phone number. Copy this object's ID and use it to register the WhatsApp business phone number. Alternatively, you can use the same endpoint with field expansion to request the display_phone_number field and specify the display phone number. For example: Get pre-verified business phone numbers Results are automatically sorted in order of creation time. You can also use field expansion to request the code_verification_status field to have the API only return pre-verified business phone numbers with the indicated verification state: Registering pre-verified numbers programmatically If you have customized Embedded Signup to bypass the phone number addition screen, you can register pre-verified business phone numbers on an onboarded business customer's WhatsApp Business Account programmatically. To do this, first complete all of the steps to create a pre-verified number, then use the pre-verified number ID to complete Step 1 and Step 4 in the Register Phone Numbers document. Bypassing the phone number addition screen | Developer Documentation Bypassing the phone number addition screen Updated: Nov 14, 2025 This document describes how to customize Embedded Signup to bypass the phone number addition screen (shown below) and phone number verification screen. If you don’t want your business customers to have to enter or choose a business phone number in the phone number addition screen, you can customize Embedded Signup to skip the screen entirely. However, after a customer successfully completes the customized flow, you must programmatically create and register their business phone number, or build a UI in your app that allows them to do this. Enabling the feature To enable this feature, set featureType to only_waba_sharing in the launch method and callback registration portion of the Embedded Signup code: // Launch method and callback registrationconst launchWhatsAppSignup =()=>{ FB.login(fbLoginCallback,{ config_id:'',// your configuration ID goes here response_type:'code', override_default_response_type:true, extras:{ setup:{}, featureType:'only_waba_sharing',// set to only_waba_sharing sessionInfoVersion:'3',}});} When a business customer successfully completes the flow, the session logging message event will have event set to FINISH_ONLY_WABA: { data: { phone_number_id: "", waba_id: "" }, type: "WA_EMBEDDED_SIGNUP", event: "FINISH_ONLY_WABA", version: 3 } Website field optional | Developer Documentation Website field optional Updated: Nov 4, 2025 This feature is currently only available to approved Select Solution and Premier Solution Partners. See our Sign up for partner-led business verification? Help Center article to learn how to request approval. By default, the website field is required in the business portfolio screen. If you have been approved for Partner-led Business Verification however, the website field will become optional and will be accompanied by a My business does not have a website or profile page checkbox: When a business customer checks this box and completes the flow, the customer's WhatsApp assets and exchangeable token code will be generated and returned in a message event and JavaScript response, as usual. However, the account_update webhook that's triggered when the customer completes the flow will have event set to PARTNER_CLIENT_CERTIFICATION_NEEDED, which indicates that you must verify their business as part of the onboarding process. Onboard the customer as you normally would, and when you're done, complete the steps described in our Partner-led Business Verification document to verify their business. The customer will not be able to send messages until their business is verified. Onboarding business customers as a Solution ProviderOnboarding business customers as a Tech Provider Note that if you are unable to verify your customer's business, the customer must first add a website on their own using Meta Business Suite > Settings > Business info?, or they won't be able to send messages. Once they have added a website and it has been accepted, they can also verify their business? on their own, if they choose to do so. Hosted Embedded Signup | Developer Documentation Hosted Embedded Signup Updated: Nov 4, 2025 If you don’t want to implement Embedded Signup by adding JavaScript code to your website or customer portal, you can instead use a link that, when clicked, displays a web page describing onboarding steps, and a button that launches the Embedded Signup flow: Limitations Hosted Embedded Signup (“Hosted ES”) can only be used to onboard business customers to Cloud API, and the flow cannot be customized. RequirementsYou must have completed the steps to become a Solution Partner or Tech Provider.If your app is for messaging, it must be able to send messages, manage templates, and have a properly configured production webhook endpoint.Your app must be subscribed to the account_update webhook.Solution Partners must have a line of credit. You will also need:Your system token.Your app secret. Step 1: Create a Facebook Login for Business configuration If you don’t already have a Facebook Login for Business configuration, you must create one. A Facebook Login for Business configuration defines which permissions to request, and what additional information to collect, from business customers who access Embedded Signup. Navigate to Facebook Login for Business > Configurations and click the + Create configuration button to access the configuration flow. Use a name that will help you differentiate this configuration from any others you may create in the future. When completing the flow, be sure to select the WhatsApp Embedded Signup login variation: When choosing assets and permissions, select only those assets and permissions that you will actually need from your business customers. For example, if you select the Catalogs asset but don’t actually need access to customer catalogs, your customers will likely abandon the flow at the catalog selection screen and ask you for clarification. Step 2: Get the Hosted ES URL Navigate to the WhatsApp > Quickstart panel and click the View onboarding button. Locate the Zero integration onboarding card. The URL displayed in the card is the onboarding page URL: Click the Copy button to copy the URL to your clipboard. Map this URL to a button on your website or customer portal that, when clicked, opens the URL in a new browser window. To see what this looks like, you can load the URL in a new browser window or tab, or click the blue “new window” icon, which does the same thing. This onboarding page looks like this: Click the Get started button. This is the flow that business customers who click the button on your website or customer portal will see. Complete the flow if you wish. Step 3: Capture customer asset IDs Step 4: Generate an HMAC-SHA256 hash Generate an HMAC-SHA256 hash of your app secret and system token. Bash example for Linux and macOS echo -n "" | openssl dgst -sha256 -hmac "" — Your system token. — Your app secret (App Dashboard > App settings > Basic) Step 5: Get a business token Step 7: Onboard the customer Onboard the business customer by completing the steps in the appropriate onboarding guide below:Onboarding business customers as a Tech Provider or Tech Partner (skip step 1)Onboarding business customers as a Solution Partner (skip step 1) Automatic Events API | Developer Documentation Automatic Events API Updated: Nov 18, 2025 Business customers who access Embedded Signup can opt in to automatic event identification: If a business customer opts in, Meta use a combination of regex and natural language processing to analyze the customer’s new message threads originating from Click-to-WhatsApp ads. If our analysis determines that a lead gen or purchase event occurred, an automatic_events webhook is triggered, describing the event. You can then report the event for the customer using the Conversions API so the customer can use it on a Meta surface (in 2026, see Limitations below). To learn more about how this feature works, see these additional resources⁠. Limitations Automatic event identification is a new feature. Your business customers won’t see or use automatic events reported via Conversions API in Meta surfaces until 2026. However, you can surface this information to your customers using your own solution before then. This allows them to gain a deeper understanding of their own customers’ needs, preferences, and ad performance.Automatic event identification is not available to business customers in the European Union, United Kingdom, or Japan. Requirements You have already implemented Embedded Signup and are able to onboard business customers who complete the flow.Your webhook server is successfully processing webhooks. Enabling and disabling via Meta Business Suite Business customers who have already been onboarded via Embedded Signup can enable automatic event identification using Meta Business Suite. If a business customer who you have already onboarded wants to enable this feature, you can send them these instructions: Access Meta Business Suite at https://business.facebook.com⁠.Navigate to Settings > Accounts > WhatsApp accounts and click your WhatsApp Business Account.Scroll down to Privacy and data sharing in the Summary tab.Use the “Automatically identify... “ toggles to enable or disable automatic event identification as desired. Versions | Developer Documentation Versions Updated: Dec 11, 2025 The latest Embedded Signup Version is: v4 This guide provides an overview on versioning in Embedded Signup. The versioning cadence will align with Graph API. The versions are not exclusive, partners can gradually roll out a new version of ES to reduce risk. The Embedded Signup version is determined inside of the extras object of the implementation code. Note: The refreshed UI, currently available in the public preview, will be rolled out to all versions of Embedded Signup in early September. Available ES Versions Version Date Introduced Available Until v4 October 8th, 2025 TBD v3-public-preview August 14, 2025 October, 2026 v2-public-preview August 14, 2025 October, 2026 v3 May 29, 2025 October, 2026 v2 January 2023 October, 2026 Overview of feature availability Version Feature types Features Completion State Prefilled Info Session Info Logging Products (via login config) v4 whatsapp_business_app_onboarding app_only_install Users can finish with a verified, unverified or no phone number Can fill business information, no screens will be skipped. Sent back for all flows Marketing Messages API for WhatsApp(MM API for WhatsApp) Click to WhatsApp Ads (CTWA) Conversions API (WhatsApp) v3-public-preview whatsapp_business_app_onboarding app_only_install marketing_messages_lite Users can finish with a verified, unverified or no phone number Can fill business information, no screens will be skipped. Sent back for all flows Not supported v2-public-preview only_waba_sharing whatsapp_business_app_onboarding marketing_messages_lite app_only_install marketing_messages_lite Users will finish with a verified phone number Can fill business information, no screens will be skipped. Sent back for all flows Not supported v3 whatsapp_business_app_onboarding app_only_install marketing_messages_lite Users can finish with a verified, unverified or no phone number Can fill business information, no screens will be skipped. Sent back for all flows Not supported v2 only_waba_sharing whatsapp_business_app_onboarding marketing_messages_lite marketing_messages_lite Users will finish with a verified phone number Can fill business information and skip screens Partners are required to add a sessionInfoVersion to receive the callback Not supported Version 4 Released: October 8, 2025 | Detailed changes Login Configuration Extras Configuration extras:{}// The extras object is purposely empty for v4. To use v4: You need to create a new Facebook Login for Business Configuration, and select your desired products. Selecting the products will automatically set you to v4. Version 3 Public Preview Released: August 14, 2025 | Available until: October, 2026 | Detailed changes Extras Configuration extras:{ setup:"", features:[{ name:""}], featureType:"", version:""} Placeholder Description Example Value Prefilled business data to inject data into Embedded Signup. Indicates a flow or feature to enable. Possible Values: app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT) marketing_messages_lite - Enables the Marketing Messages API for WhatsApp onboarding flow. Indicates a flow or feature to enable. Possible Values: whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow. Leave blank to enable the default onboarding flow. Indicates Embedded Signup version flow. Possible Values: v3-public-preview, v2-public-preview, v3, v2 Version 2 Public Preview Released: August 14, 2025 | Available until: October, 2026 | Detailed changes Extras Configuration extras:{ setup:"", features:[{ name:""}], featureType:"", sessionInfoVersion:"" version:""} Placeholder Description Example Value Prefilled business data to inject data into Embedded Signup. Indicates a flow or feature to enable. Possible Values: app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT) marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. Indicates a flow or feature to enable. Possible Values: whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow. only_waba_sharing - Enables the WhatsApp Business App phone number onboarding custom flow. Will NOT show the new consolidated UI. marketing_messages_lite - Enables the MM API for WhatsApp onboarding custom flow. Will NOT show the new consolidated UI. Leave blank to enable the default onboarding flow. Indicates the returned session payload. Possible Values: 3 Indicates Embedded Signup version flow. Possible Values: v3-public-preview, v2-public-preview, v3, v2 Version 3 Released: May 29, 2025 Available until: October, 2026 Blog post Detailed changes Extras Configuration extras:{ setup:"", features:[{ name:""}], featureType:"", version:"v3"} Placeholder Description Example Value Prefilled business data to inject data into Embedded Signup. Indicates a flow or feature to enable. Possible Values: app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT) marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. Indicates a flow or feature to enable. Possible Values: whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow. Leave blank to enable the default onboarding flow. Indicates Embedded Signup version flow. Possible Values: v3-public-preview, v2-public-preview, v3, v2 Version 2 Released: January 2023 Available until: October, 2026 Extras Configuration extras:{ setup:"", features:[{ name:""}], featureType:"", sessionInfoVersion:"",} Head to the pre-fill screens page to see how to inject customer business data into Embedded Signup. Placeholder Description Example Value Prefilled business data to inject data into Embedded Signup. Indicates a flow or feature to enable. Possible Values: app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT) marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. Indicates a flow or feature to enable. Possible Values: whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow. only_waba_sharing - Enables the WhatsApp Business App phone number onboarding custom flow. marketing_messages_lite - Enables the MM API for WhatsApp onboarding custom flow. Leave blank to enable the default onboarding flow. Indicates the returned session payload. Possible Values: 3 Indicates Embedded Signup version flow. Possible Values: v3-public-preview, v2-public-preview, v3, v2 Version 4 | Developer Documentation Version 4Updated: Dec 12, 2025Release date: October 8, 2025. Check back soon for updates on additional supported products.To upgrade to the v4 experience: You need to create a new Facebook Login for Business Configuration, and select your desired products. Selecting the products will automatically set you to v4.See screenshots below. Overview of v4 changes Simplified onboarding experience for businesses: You can onboard businesses to more business messaging in a single flow (see supported products).Asset selection, business information, and permissions are each consolidated onto a single page.Asset admins can share assets from other business portfolios.Phone numbers are auto-linked to Facebook Pages when onboarding to ads that click to WhatsApp via the Marketing API.Value proposition and Terms of Service are clearly presented.The Facebook Login for Business Configuration is used to define which products to add into your onboarding flow. Learn more v4 - Cloud API flow Supported productsv4 supports additional business messaging products, ensuring businesses to set up and manage multiple communication channels from a single platform: Conversions API (WhatsApp): Track and optimize messaging interactions by selecting the messaging platform you want to monitor, enabling enhanced measurement and optimization.Click to WhatsApp Ads (CTWA): Create ads that direct users to initiate WhatsApp conversations with your business.Click to Messenger Ads (CTM): Run advertising campaigns that start conversations with users on Facebook Messenger.Click to Direct Ads (CTD): Launch Instagram ad campaigns that drive users to direct messaging conversations on Instagram Direct. All other supported productsv4 continues to support existing business messaging products, allowing businesses to seamlessly manage their established communication channels. Cloud API: Integrate and manage WhatsApp messaging at scale, enabling businesses to send and receive messages, automate workflows, and access advanced messaging features.Marketing Messages API for WhatsApp: Utilize to manage optimized marketing messaging , providing tools for message analytics, and enhanced customer engagement.WhatsApp Business App users (aka “Coexistence”) support: Onboarding via Coexistence continues to be supported through the feature_type parameter.Partner-led Business Verification (PLBV) support: PLBV enables partners to verify business after onboarding via Embedded Signup. If you are considering this option, ensure you are an approved Select Solution or Premier Solution Partner, and approved for access⁠.Automatic Events API: Automatic Events API notifies your application about key events that occur through Click-to-WhatsApp ads. Use the Facebook Login for Business Configuration to get started with v4v4 enables you to easily set up and change which products you want to include in your onboarding flow:Step 1: Navigate to App Dashboard > Facebook Login for Business > Configurations to create a new configuration.Step 2: Select Embedded Signup as the login variation. Step 3: Select which products you want to include in your onboarding flow. Selecting more than one product is optional. Step 4: Copy the configuration id to use inside the Facebook Login SDK. Required assets and permissionsWhen selecting products for v4, the flow will automatically select all necessary permissions and assets. You will need advanced access for all permissions automatically selected in the flow. If needed, you can select additional assets and permissions. The table below is a reference on what assets and permissions you need depending on what product you would like to offer. Product Required assets Required permissions (Advanced Access) Cloud API WhatsApp Business accounts whatsapp_business_managementwhatsapp_business_messaging Click to WhatsApp (CTWA on Marketing API) WhatsApp Business accountsFacebook PagesAd accounts ads_readads_managementpages_manage_adspages_read_engagementpages_show_list Click to Messenger (CTM on MAPI) Facebook PagesAd accounts ads_managementpages_manage_adspages_read_engagementpages_show_list Click to Instagram (CTD on MAPI) Facebook PagesAd accountsInstagram accounts ads_managementpages_manage_adspages_read_engagementpages_show_list Marketing Messages API for WhatsApp WhatsApp Business accounts whatsapp_business_managementwhatsapp_business_messaging Conversions API for CTWA WhatsApp Business accountsPixels whatsapp_business_manage_events Conversions API for CTM Facebook PagesAd accountsPixels page_events Conversions API for CTD Facebook PagesAd accountsInstagram accountsPixels instagram_manage_events Version 3 | Developer Documentation Version 3 Updated: Dec 11, 2025 We are introducing versioning cadence to Embedded Signup that will align with Graph API. v3 will be released on May 29th for all partners to adopt, which will include the following changes. Business customers can now complete the flow without a phone number Previously in v2, you would always be required to register a verified phone number (unless partners enabled the bypass phone numbers flow) to complete the flow. You can now complete the flow with statuses like verified, unverified, or no phone number at all. You can either go through Embedded Signup again, go on WhatsApp manager, or the partner can utilize API calls to verify the number. To determine the status of the phone number, visit the documentation on session info logging. Session Info Logging is automatically enabled All partners who are on v3 will have session info logging enabled automatically. Partners will still have to add an event listener on the same window of Embedded Signup to process the incoming information. Adding the features property in the configuration You can now utilize the features property to enable a range of features in Embedded Signup. The property allows you to add multiple features instead of just one in the featureType property from v2. v3 request syntax // Launch method and callback registration const launchWhatsAppSignup = () => { FB.login(fbLoginCallback, { config_id: '', // your configuration ID goes here response_type: 'code', override_default_response_type: true, extras: { version: 'v3' setup: {}, features: [], featureType: '' } } Placeholder Description Example Name of feature to enable in ES configuration. Note: You can leave the value blank to follow the default flow. Values can be: app_only_install — Allows partners to only access WABAs via API using a business token. marketing_messages_lite — Enables the MM API for WhatsApp onboarding flow. { features: [ { name: 'marketing_messages_lite' } ] } Name of feature types to enable in ES configuration. Value can only be whatsapp_business_app_onboarding, which enables the WhatsApp Business App phone number onboarding custom flow. whatsapp_business_app_onboarding Removal of multiple featuretype options in the ES Configuration In v2, business customers enabling a custom flow would be required to complete the embedded sign up multiple times depending on the number of featureTypes added to the configuration. Removing only_waba_sharing The bypass phone number screen flow allows for a streamlined onboarding process where the WABA is shared without the need to go through the phone number setup steps. This flow will no longer be supported in v3. If you want to use the flow, use v2. Removing marketing_messages_lite Marketing Messages API for WhatsApp will still be supported through the features argument. If you would still like to use the flow, update your configuration to the following. Removing coexistence To launch the WhatsApp Business App Onboarding flow, partners will have to use whatsapp_business_app_onboarding instead of coexistence. Embedded Signup Pre-Filled will no longer skip screens. Partners will still be able to pre-fill business information in Embedded Signup, but the business customer will not have the option to bypass any screens in the flow. For partners who would still like to use the flow, you should stick to using v2. Measurement Partners must remain on v2 Please note that Measurement product onboarding will only be supported on v2 for the time being. Continuing to support Measurement partners is important and will be supported in a future version. Version 3 Public Preview | Developer Documentation Version 3 Public PreviewUpdated: Nov 4, 2025We are updating the UI for Embedded Signup. You can get a preview of what it looks like by enabling v3-public-preview. The new version will give partners a preview on what’s to come for Embedded Signup in the near future. Functionality between v3-public-preview and v3 are identical; the key difference is a simplified UI on v3-public-preview. Authentication screenThis screen authenticates business customers using their Facebook or Meta Business Suite credentials. Authorization screenThis screen describes the data the business customer will be permitting your app to access. Business Asset Selection ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Business Asset Creation ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Phone number addition screenThis screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead. Phone number verification screenThis screen allows the business customer to verify ownership of the business phone number they entered in the previous step. Permissions review screenThis screen provides a summary of the permissions the business customer will be granting to your app. Success screenThis screen indicates that we successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform. Version 2 Public Preview | Developer Documentation Version 2 Public PreviewUpdated: Nov 4, 2025We are updating the UI for Embedded Signup. You can get a preview of what it looks like by enabling v2-public-preview. The new version will give partners a preview on what’s to come for Embedded Signup in the near future. Functionality between v2-public-preview and v2 are identical; the key difference is a simplified UI on v2-public-preview. Authentication screenThis screen authenticates business customers using their Facebook or Meta Business Suite credentials. Authorization screenThis screen describes the data the business customer will be permitting your app to access. Business Asset Selection ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Business Asset Creation ScreenThis screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.Users also have the option to create new assets if they have not reached their portfolio limit. Phone number addition screenThis screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead. Phone number verification screenThis screen allows the business customer to verify ownership of the business phone number they entered in the previous step. Permissions review screenThis screen provides a summary of the permissions the business customer will be granting to your app. Success screenThis screen indicates that we successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform. App-Only Install | Developer Documentation App-Only Install Updated: Nov 4, 2025 You can configure Embedded Signup so that only business tokens can be used to access assets owned by customers onboarded via the flow. This approach offers enhanced security by reducing risk associated with system tokens, flexibility in simplifying onboarding for other Meta assets, and scalability to support a larger number of onboardings. By using a granular token, you can also reduce the negative impact in case of a compromised token, making it a more secure and efficient way to manage your business customer assets. Note that App-Only Install can't be used to onboard WhatsApp Business app users. Getting Opt In Get opt-in for WhatsApp | Developer Documentation Get opt-in for WhatsAppUpdated: Nov 3, 2025Businesses are required to obtain opt-in before messaging people on WhatsApp.As per the November 2024 WhatsApp Business Messaging Policy⁠ update, before messaging people on WhatsApp, businesses are required to obtain opt-in permission, which can be general and not specifically for WhatsApp, as long as businesses comply with all local laws. Businesses may contact people on WhatsApp if: (a) they have given their mobile phone number; and (b) businesses have received opt-in permission from the recipient confirming that they wish to receive subsequent messages or calls from a particular business. RequirementsBusinesses must follow the below requirements when obtaining opt-in: Businesses must clearly state that a person is opting in to receive communication from the businessBusinesses must clearly state the business’s name that a person is opting in to receive messages fromBusinesses must comply with applicable law Opt-in methodsIt is up to businesses to determine the method of opt-in, that they have obtained opt-in in a manner that complies with laws applicable to their communications, and that they have otherwise provided notices and obtained permissions that are required under applicable law.As long as the opt-in method meets the above requirements, it will be policy compliant. The following are examples of supported opt-in methods: SMSWebsiteBy phone (using an interactive voice response (IVR) flow)In person or on paper (customers can sign a physical document to opt in) Helpful tipsBusinesses should continue to optimize for the user experience while obtaining opt-in. For example: Users should expect the messages they receive. Businesses can set this expectation by: Obtaining an opt-in that encompasses the different categories of messages that a business will send (ex: order updates, relevant offers, product recommendations, etc.).Obtaining separate opt-in by specific message category. This mitigates the risk that users will block your business because they receive unsolicited messages.Provide clear instructions for how people can opt out of receiving specific categories of messages, and honor these requests.Ensure opt-in and opt-out flows are clear and intuitive for users.Businesses should clearly communicate the value of receiving this information.Businesses should monitor quality rating, especially when rolling out new opt-in methods. Maintaining high qualityDriving high-quality chat threads between people and businesses is still a top priority. People can share feedback with WhatsApp or choose to stop receiving marketing messages from individual businesses. People can also block or report a business. Our systems will rate limit businesses if the business’s quality is low for a sustained period of time. We may also reactively evaluate user feedback to flag policy violations and develop additional types of enforcement over time. Groups Groups API | Developer Documentation Groups APIUpdated: Nov 14, 2025Eligibility for Groups APIThe Groups API is now open to all businesses with an Official Business Account (OBA)The Groups API enables you to programmatically create groups for messaging and collaboration. How it worksGroups are an invite-only experience where participants join using a group invite link you send them. This invite link provides context about the group, helping the user decide whether they want to join. Get StartedWhen you are ready to start using the Groups API, head on over to our “Get Started” guide for more information:Get Started with Groups API Quick Facts Max group participants: 8Supported message types: Text, media, text-based templates, and media-based templatesMax groups you can create: 10,000 per business numberMax Cloud API businesses per group: 1 AnalyticsPerformance metrics are not available for message templates used in Groups.Please create new templates specifically for Groups use instead of repurposing templates used for one-to-one messaging. LimitsEligibility for Groups APITo qualify for groups features, your business must be an Official Business Account (OBA)Groups are not available for Coexistence users and phone numbers onboarded to Multi-solution Conversations.The Calling API is not supported in groups. Non-supported message types: CallingDisappearing messagesView-onceAuthCommerce messagesInteractive messages Non-supported actions: Admin hide group participant listEdit messageDelete messageMarking message as read PricingThe Groups API uses per-message pricing.Learn more about Groups API pricing here Features and reference Group management features Create and delete groupGroups with join requests enabledGet and reset group invite linkSend group invite link template messageRemove group participantsGet group infoGet active groupsUpdate group settingsView Group Management reference Group messaging features Send group messagesReceive group messagesPin and unpin group messageView Group Messaging reference Get started with Groups API | Developer Documentation Get started with Groups APIUpdated: Nov 14, 2025Eligibility for Groups APITo qualify for groups features, your business must be an Official Business Account (OBA) OverviewGroups on are invite-only, meaning that potential group participants are ultimately in control of wether they want to join the group or not.When you create a group, a unique invite link that is generated which you can share to potential group participants. This link includes information about the group, enabling users to make an informed decision about wether or not they want to join the group.Once a user joins the group, a webhook is triggered, signaling that you are now eligible to send messages to the group.For a complete overview of available features, see the Groups API Features below. How to start using groups PrerequisitesBefore you get started with the Groups API, ensure that: Your business number is in use with Cloud API (not the WhatsApp Business app).Your webhook server is set up for use with Cloud API.Your app is subscribed to the following groups webhook fields: group_lifecycle_update group_participants_update group_settings_update group_status_updateYour app is subscribed to the WhatsApp Business Account of your business phone number.Your app has the whatsapp_business_messaging permission for the business number. Step 2: Create a groupUse the Create Group endpoint to create a group, providing a subject and an optional description. Once a group has been successfully created, a group_lifecycle_update webhook for successful group creation will be returned. This webhook will include a invite_link field with the invite link that you can now share with potential group participants. Step 3: Invite WhatsApp users to the group 3.1 Add a group invite link template in Template Library⁠ to your account templates: Navigate to Template Library⁠On the left, click the Group invite link dropdown, then click the Group invite upon request checkbox.Select the template you want to use, give it a name, and click Submit 3.2 Send the invite link to potential group participantsOnce the template has been approved, use the template to invite members to the group using the invite link provided in the webhook from Step 2.You can follow the instructions in the Send Group Invite Link Template Message reference to send the invite link with the template you just added to your account. 3.3 Notification of when participants join the groupWhen a participant joins, a group_participants_update webhook for a group participant joining webhook will be triggered. Step 4: Send and receive messagesYou can now use the Cloud API send message endpoint to send messages to the group.Sent, delivered, and read status webhooks will be triggered when there are updates in the group. Replies from participants will also trigger webhooks.Learn more about how to send and receive group messages FeaturesTo learn more about all the features available in groups: Visit the Group Management reference to learn more about features available for managing groups.Visit the Group Messaging reference to understand sending, receiving, and other messaging functions in groups. Group management | Developer Documentation Group management Updated: Mar 25, 2026 Overview The Groups API gives you simple functions to control groups through their lifecycle. When you create a new group, an invite link is created for inviting participants to the group. Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users who you would like to join the group. Group management featuresCreate and delete groupGroups with join requests enabledGet and reset group invite linkSend group invite link template messageRemove group participantsGet group infoGet active groupsUpdate group settings To learn how to message groups, view the Group Messaging reference. Subscribe to groups metadata webhooks In order to receive webhook notifications for metadata about your groups, please subscribe to the following webhook fields: group_lifecycle_update group_participants_update group_settings_update group_status_update For a full reference of webhooks for the Groups API, please visit our Webhooks for Groups API reference. Groups with join requests You can create groups that require join request approval. Once enabled, WhatsApp users who click the group invitation link can submit a request to join the group, or cancel a prior request: When a WhatsApp user joins the group using a join request, a [ group_participants_update webhook for a user accepting the join request] (/documentation/business-messaging/whatsapp/groups/webhooks#user-accepts-or-cancels-join-request) is triggered. You can also get a list of open join requests via API. Use the contents of the webhook or API response to approve or reject requests. Approve join requests Request parameters Placeholder Description Sample Value String Required. Group ID. Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD Response parameters Placeholder Description Sample Value String ID of approved join request, or ID of failed join request, if we were unable to approve. MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw Integer Error code, if unable to approve. 131203 String Error message, if unable to approve. (#131203) Recipient has not accepted our new Terms of Service and Privacy Policy. String Error title, if unable to approve. Unable to add participant to group String Error details, if unable to approve. Recipient has not accepted our new Terms of Service and Privacy Policy. Reject join requests Request parameters Placeholder Description Sample Value String Required. Group ID. Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD String Required. ID of join request to reject. MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw Response parameters Placeholder Description Sample Value String ID of rejected join request, or ID of failed join request, if we were unable to reject. MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw Integer Error code, if unable to reject. 131203 String Error message, if unable to reject. (#131203) Recipient has not accepted our new Terms of Service and Privacy Policy. String Error title, if unable to reject. Unable to add participant to group String Error details, if unable to reject. Recipient has not accepted our new Terms of Service and Privacy Policy. Delete group Request properties Placeholder Description Sample Value String Required The ID of the group you want to delete. Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD Group message status webhooks When you send a message to a group, you receive a status messages webhook when the message is delivered or read by group participants. Status webhooks for individual group participants may be aggregated into a single webhook containing multiple status objects in the statuses array. However, aggregation is not guaranteed. If multiple participants' statuses are generated at approximately the same time, they may be combined into a single webhook. If statuses are generated at different times, you may receive separate webhooks for each participant. Each webhook only ever references a single message sent to a single group and a single status type (for example, delivered). Statuses for different messages, groups, or status types are never combined into a single webhook. Pricing information Status messages webhooks that contain pricing information will have set to one of: group_marketing - Indicates a group marketing conversation. group_utility - Indicates a group utility conversation. group_service - Indicates a group service conversation. Group messaging | Developer Documentation Group messaging Updated: Nov 14, 2025 Overview This document provides comprehensive information on the APIs and webhooks available for sending and receiving messages within groups. It details support for various message types, including: Text messagesMedia messagesText-based templatesMedia-based templates Subscribe to groups metadata webhooks In order to receive webhook notifications for metadata about your groups, please subscribe to the following webhook fields: group_lifecycle_update group_participants_update group_settings_update group_status_update For a full reference of webhooks for the Groups API, please visit our Webhooks for Groups API reference. Receive group messages You can use the following webhooks to receive statuses on messages received in the group. The message object includes a group_id field to indicate this is a group message. The from field in the message object and the contact object point to the same participant who sends this message. Group message status webhooks When you send messages to a group, you will receive a webhook when the message is delivered or read. Instead of sending multiple webhooks for each status update, we will send an aggregated webhook. This means that if you send a message and are set to receive several read or delivered statuses, we will send you a single, aggregated webhook that contains multiple status objects. Each webhook you receive is only ever in reference to a single message sent to a single group and a single status type. Learn more about the Group Message Status webhook Webhooks for Groups API | Developer Documentation Webhooks for Groups API Updated: Feb 11, 2026 In order to receive webhook notifications for metadata about your groups, please subscribe to the following webhook fields: group_lifecycle_update group_participants_update group_settings_update group_status_update group_lifecycle_update webhooks A group_lifecycle_update webhook is triggered when a group is either created or deleted. Group create succeed Group create fail Delete group succeed Delete group fails group_participants_update webhooks A group_participants_update webhook is triggered when a WhatsApp user joins a group with an invite link, requests to join a group, cancels their request, or when one or more join requests are approved. User joined group using invite link succeed User accepts or cancels join requestFor join requests:  GROUP_REQUEST_TYPE is set to group_join_request_created.For cancel requests:  GROUP_REQUEST_TYPE is set to group_join_request_revoked. Group participant remove succeed Group participant remove with participants partially fails Group participant remove fails Group participant leaves webhook This webhook is sent when a group participant leaves the group. The initiated_by field and only the wa_id in the removed_participants list will point to the participant who left the group. group_settings_update webhooks Group settings update succeed Group settings update partial fail Group settings update total fail group_status_update webhooks WhatsApp uses advanced machine learning technology to evaluate group information including group subjects, profile photos, and group descriptions. We also provide simple options for users to make reports to us from any chat. We may prevent further activity in chat groups to comply with our legal obligations. We may also prevent further chat activity when a group admin is in violation of our Terms of Service?. You may receive a webhook if a group you manage is suspended. You may also receive a webhook if a suspended group you manage becomes clear of suspensions. Group suspended Group suspension cleared Group Message Status Webhooks When you send messages to a group, you will receive a status webhook when the message is sent, delivered, and read. Instead of sending multiple webhooks for each status update, we may send an aggregated webhook. There are two types of aggregated message status webhooks you can receive. Multiple Participants, Single Message If you send a message and are set to receive several read or delivered statuses from participants, we will send you a single, aggregated webhook that contains multiple status objects. Each webhook you receive will be in reference to a single message sent to a single group and a single status type, i.e single group, single status by multiple participants for a single message. Aggregated group message status Multiple Messages, Single Participant If you send multiple messages to a group and are set to receive several 'read' or delivered statuses from a single participant, we may send you a single, aggregated webhook that contains multiple status objects. Each webhook you receive will be in reference to multiple messages sent to a single group and a single status type, i.e single group, single status by single participant for multiple messages. Aggregated group message status Group message delivered Pricing information Status messages webhooks that contain pricing information will have: CONVERSATION_CATEGORY set to one of: group_marketing - Indicates a marketing conversation. group_utility - Indicates a utility conversation. group_service - Indicates a service conversation. IS_BILLABLE set to one of: true - Indicates a billable conversation. false - Indicates a non-billable conversation. PRICING_MODEL set to PMP. Learn more about Groups API pricing Group message read (With pricing) Group message read (Without pricing) Groups API Error Codes and Troubleshooting | Developer Documentation Groups API Error Codes and TroubleshootingUpdated: Oct 31, 2025 Error Codes Code Description HTTP Status Code 131020Bad Group Cannot send messages to single member groups. 400Bad Request 131041Group unknown The group was not found, either because it doesn’t exist or you are not a member. 400Bad Request 131059Invalid cursor The cursor has either expired or become corrupted. Start pagination from the beginning again. 400Bad Request 131201Request partially succeeded Not all participant-level operations in the request succeeded. 206Partial Content Success 131202Duplicate participant Duplicate participants in the participant array input. 400Bad Request 131204Participant overlimit Group participant size exceeds limit. 400Bad Request 131207Group suspended The group violates platform policies. 403Forbidden 131208Group Rate Limit Hit Group operation failed because there were too many group operations from this phone number in a short period. 429Too many requests 131209Invalid Group Profile Picture Aspect Ratio Width and height of the image must be equal. 400Bad Request 131210Image is Too Small to Process Image width and height must be greater than 192px. 400Bad Request 131211Group create limit reached Reached the limit for the maximum number of groups that can be created for this number. 400Bad Request 131212Participant is not a part of the group. Participant is not a part of the group. 400Bad Request 131213Group join request does not exist. Group join request does not exist. 400Bad Request 131214Group creation is temporarily disabled Group creation is temporarily disabled due to excessive marketing messages sent by the WABA in customer service window over the past 7 days. 400Bad Request 131215This phone number is not eligible to access Groups APIs Groups APIs are only available for eligible phone numbers. Please check eligibility for Groups APIs in our documentation - /documentation/business-messaging/whatsapp/groups/get-started 400Bad Request Groups API Pricing | Developer Documentation Groups API Pricing Updated: Oct 22, 2025 Per-message pricing on Groups API Groups API uses Cloud API's per-message pricing model to determine if a given message is billable. However, you are charged each time a billable message is delivered to someone in the group. For example, if you send a (billable) marketing template message to a group with 5 WhatsApp users and it is delivered to all 5 users, you would be charged for 5 delivered messages at the going marketing message rate for each recipient's country calling code. If the message was delivered to only 4 of the 5 users, you would only be charged for the 4 delivered messages. How customer service windows work with Groups API Customer service windows work differently when using Groups API. When any WhatsApp user in the group messages you, a customer service window is opened between you and the entire group (or is refreshed, if one already exists). This allows you to send utility and marketing template messages, or free form messages, for free. This is different from 1:1 messaging, where when a WhatsApp user messages you, a customer service window is opened between you and that customer (or is refreshed, if one already exists). Everything else about customer service windows remains the same. Pricing information in Message Status webhook Pricing information for messages sent using Groups API is included in messages status webhooks. How read and delivered message status webhooks are processed In order for a message status to be considered read, it must have been at least delivered. In some scenarios, such as when a user is present in the chat thread when a message arrives, the message is marked delivered and read nearly simultaneously. In this and other similar scenarios, the delivered webhook is not sent back. This is because it is implied that the message was delivered since it has been read. How pricing data is displayed in the Message Status webhook Not all Message Status webhooks include pricing information. With the introduction of Per-message Pricing, pricing data can be present in sent, delivered or read status webhook. If a message is charged, you can expect that at least one webhook ( delivered or read) will contain the pricing information. Sent message status webhook Delivered / Read message status webhook Parameters Placeholder Description Version 24.0 and higher: The conversation object will be omitted entirely Version 23.0 and lower: Value will now be set to a unique ID per-message, instead of per-conversation. Not changing. Not changing. Not changing. However, the billable property will be deprecated in a future versioned release, so we recommend that you start using pricing.type and pricing.category together to determine if a message is billable, and if so, its billing rate. New property. Values can be: regular - indicates the message is billable. free_group_customer_service - indicates the message is free because it was either a utility template message or non-template message sent within a customer service window. Values are not changing, but can now be interpreted as follows: group_marketing - indicates a marketing template message. group_utility - indicates a utility template message. group_service - indicates a non-template message. Identifying billable messages Billable messages have pricing.type set to regular. The pricing.category value indicates the rate ( group_marketing or group_utility). Identifying free messages Free messages have pricing.type set to free_group_customer_service. The pricing.category value tells you why it was free: group_utility - the message was sent within an open group customer service window. group_service - all non-templates messages are free. Messaging analytics for Groups API The analytics field provides the number and type of messages sent and delivered by the phone numbers associated with a specific WABA - for conversation metrics, see Conversation Analytics. You can use the following endpoint to retrieve analytics for messages sent using Groups API: /?fields=analytics..... Filter parameters for messaging analytics For a full list of messaging analytics filter parameters, view the Messaging Analytics reference. Changes to filter parameters for Groups API Name Description product_types type: Array Optional. The types of messages (notification messages and/or customer support messages) for which you want to retrieve notifications. Provide an array and include: 101 for group notification messages 102 for group customer support messages. 103 for inbound group messages If the above values are not provided, the API call will be return analytics for all messages together. Inbound product type cannot be queried together with other product types, or you will see an error similar to the one below: Response value Successful responses to the analytics API when querying Groups API message data will return an object similar to the following: Note: The country code filter is not supported for group sent messages. Pricing analytics for Groups API The pricing_analytics field allows you to get pricing breakdowns for any messages delivered within a specified date range. GET / ?fields=pricing_analytics .start() .end() .granularity() .phone_numbers() .country_codes() .metric_types() .pricing_types() .pricing_categories() .dimensions() Filter parameters for pricing analytics For a full list of messaging analytics filter parameters, view the Messaging Analytics reference. Changes to filter parameters for Groups API Name Description Array of strings Optional. Array of pricing categories. If you send an empty array, we return results for all pricing categories. Values can be: GROUP_MARKETING: Group messages charged the marketing rate. GROUP_SERVICE: Group messages that were not charged. Includes all non-template messages and utility messages sent inside of a customer service window. GROUP_UTILITY: Group messages charged the utility rate. Array of strings Optional. Array of pricing types. If you send an empty array, we return results for all pricing types. Values can be: FREE_GROUP_CUSTOMER_SERVICE: Free group messages. These are non-template messages and utility messages sent within group customer service windows. REGULAR: Billable messages. Includes all authentication and marketing template messages, and any utility template messages sent outside of a customer service window. Rate cards Group utility messages are not eligible for volume tiers. Messaging rates for Groups API are the same as per-messaging pricing rates for 1 to 1 messaging. View per-message pricing rate cards Groups API FAQ | Developer Documentation Groups API FAQUpdated: Oct 22, 2025 What happens when I delete a group? No members, including you, will be able to message the group.If any messages or statuses were received by Cloud API before the group was deleted, you may still receive webhooks for those. Why can’t a participant join the group using my invite link?Some possible reasons include: The invite link may have been deleted.You may have removed the participant from the group previously.The group may already be full. How can I send my invite link to users? You can send the invite link over a 1:1 conversation.A new utility template is available in the Template Library⁠ to send group invite links.You may also create custom, free-form marketing templates. What countries is Groups available in? Groups is available in all countries Cloud API is available in. Identity Change Identity Change | Developer Documentation Identity ChangeUpdated: Oct 24, 2025A business may want to communicate private information with a customer via WhatsApp. In order to do that securely, the business must first establish trust that they are communicating with the right person via authentication (this is done off WhatsApp today).Once trust is established between a business and a WhatsApp account, the business does not know when the person with access to the WhatsApp account may have changed.Businesses using the WhatsApp Business Platform can choose to be notified when there was a potential update to a customer’s identity. This gives businesses a signal that the person behind the account may have changed.In this situation, the best practice would be for the business to break the trust and authenticate the user again to re-establish trust before continuing to send personal information.If a business opts in to this feature, they will be informed when they receive messages from users who have potentially changed ownership and will be blocked from sending messages to such users until the business acknowledges it’s safe to send the message. This will protect the business and their customers from leaking sensitive information. TriggerThe trigger for notifying a business is the identity for a WhatsApp account has changed.When a business receives this signal they may want to invoke a re-authentication flow to ensure they are always exchanging personal information securely. Recommended Workflow The business opts in to receive notifications when WhatsApp identifies a WhatsApp account with whom they are communicating is potentially under control of a different person.When WhatsApp detects a potential change in the user’s cryptographic identity, WhatsApp sends notification to the business.The business breaks trust with user (for example, unlinking the WhatsApp as trusted channel on their CRM)The business initiates re-authentication workflow (typically done off WhatsApp).The business acknowledges receipt of notification and continues to communicate with the account when they deem it safe to do so (usually following successful authentication).All outgoing messages to the user will be blocked until the business acknowledges receipt of the notification signaling that the person in control of the WhatsApp account could have changed. Since it is the business’s responsibility to establish trust with the user before sharing sensitive information, the business is recommended to re-authenticate the user (off WhatsApp) before acknowledging the notification, which would enable the business and user to continue exchanging personal information on WhatsApp. Acknowledging the notification does not ensure the user is “trusted”. Link Previews Link Previews | Developer Documentation Link Previews Updated: Nov 5, 2025 WhatsApp supports link previews when the link is sent via chat or shared via status. WhatsApp will attempt to perform a link preview when possible for a better user experience. To enable this experience, WhatsApp relies on link owners to define properties that are specifically optimized for WhatsApp. Not meeting these requirements may risk the link to be not previewed. Get Started To get started with enabling link previews, websites need to add HTML mark-ups to the HEAD section on the page. The containing the HTML mark-ups must appear within the first 300KB of the HTML. The entire HTML does not need to fit within 300KB. The , and mark-ups must be inside the tag. They should not be empty. The mark-up represents the title of the content without any branding. WhatsApp will display this in primary text color, in bold and in at most 2 lines. The mark-up represents the description of the content. WhatsApp will display this in a smaller size than the title and in secondary text color. It is limited to 1 or 2 lines and 80 characters will suffice. The mark-up represents the canonical URL of the page. The URL should be undecorated, without session variables, user identifying parameters and counters. The mark-up is an absolute URL for an image used as the thumbnail for the link preview. This image should be under 600KB in size. Image should be 300px or more in width with 4:1 width/height or less aspect ratio. WhatsApp will make the best attempt to show link previews, eg: relaxing requirements, looking for other HTML mark-ups and reverting to small link previews. However, this should not be relied on. It’s not guaranteed to work (and continue to work). WhatsApp crawls the web page via an HTTP GET request. The request will have the User-Agent header set to WhatsApp/2.x.x.x A|I|N, where x are major/minor numeric versions of WhatsApp and A|I|N is for Android, iOS and web respectively. Some examples of valid User-Agent header values: WhatsApp/2.22.20.72 A, WhatsApp/2.22.19.78 I, WhatsApp/2.2236.3 N. Web site owners can identify such incoming requests and can customize the content (mark-ups and images) accordingly. The request will also have the Accept-Language header set to the language selected by the recipient, if any. Some examples of valid Accept-Language header values are: en , fr, de. Similarly, web site owners can customize the content language accordingly. Note that the language set by the recipient will also be seen by the recipient. How to verify? Start with composing a message with the link to test (not tap to send yet). On behalf of the sender, WhatsApp will crawl this URL and attempt to generate a link preview. If a preview does not come up above the composer box after 10 seconds, please check all the requirements above are met. Else, continue with sending the message by tapping the “send” button. If a preview does not show up in the expected large size, please check the image requirements above are met. Else, link previews are all working as expected. Congratulations, you’re all set! Local Storage Local Storage | Developer Documentation Local Storage Updated: Mar 31, 2026 Local storage offers an additional layer of data management control, by giving you the option to specify where your message data is stored at rest. If your company is in a regulated industry such as finance, government, or healthcare, you may prefer to have your message data stored in a specific country when at rest because of regulatory or company policies. How local storage works Local storage is controlled by a setting enabled or disabled at a WhatsApp business phone number level. Both Cloud API and Marketing Messages API for WhatsApp support local storage, and the setting will apply to any messages sent via either API if enabled. When Local storage is enabled, the following constraints are applied to message content for a business phone number:Data-in-use: When message content is sent or received by Cloud API or Marketing Messages API for WhatsApp, message content may be stored on Meta data centers internationally while being processed. The data-in-use period differs between Cloud API and Marketing Messages API for WhatsApp: When using Local Storage for Cloud API, the data-in-use period is up to 60 minutes.When using Local Storage for Marketing Messages API for WhatsApp, the data-in-use period is up to 90 minutes.Data-at-rest: After the data-in-use period, message content is deleted from Meta data centers outside of the specified local storage region, and persisted only in data centers within the local storage region selected. The local storage feature supplements other WhatsApp Business Platform privacy and security controls?, and allows customers to ensure a higher level of compliance with local data protection regulations. Data in scope Local storage applies to message content (text and media) sent and/or received via Cloud API and Marketing Messages API for WhatsApp. The following message content are in scope of the local storage feature:Text messages: text payload (message body)Media messages: media payload (audio, document, image or video)Template messages (static template + parameters passed at message send time): components with text / media payload In addition, a limited set of metadata attributes is included with the locally stored message content, in order to correctly associate the encrypted message payload with the originally processed message, and to audit the fact of localization. The stored metadata is protected with tokenization and encryption. Phone number storage via contact information requests If your business has enabled the contact book feature and a WhatsApp user shares their contact information by tapping the share contact information button, Meta extracts the user's phone number from the shared contact card (vCard) and stores it in your contact book. The contact book is hosted on Meta data centers, regardless of your Local Storage configuration. Only the phone number is extracted and stored; no other vCard data is retained on Meta data centers beyond the standard data-in-use period. Contact book retention policies apply to this data and you can turn off this feature. Available Regions To see what regions are supported by local storage, see the data_localization_region parameter in the documentation on phone number registration. LimitationsMedia files uploaded by a business phone number with local storage enabled are only accessible to that specific phone number, and cannot be shared with other phone numbers associated with the business.If your business has the contact book feature enabled, phone numbers shared via the share contact information button are extracted from the vCard and stored in your contact book on Meta data centers, regardless of your Local Storage configuration. See Phone number storage via contact information requests for details. Disabling local storage using v20 and older For example: Note that this deregisters the business phone number so it cannot be used with WhatsApp Cloud API. If you want to continue using it with Cloud API but without local storage enabled, you must reregister it without including the data_localization_region parameter. FAQs Q. What are the migration paths for moving a phone number to the Cloud API version with Local Storage? We support all migration paths to Cloud API version with Local Storage, this includes:Existing Cloud API number migrating to Cloud API version with Local StorageNew Cloud API number enabling Local Storage In all these scenarios you would need to send a POST request to the /register endpoint for the selected phone number, specifying the target country for which data to be localized in a new parameter data_localization_region. Q. Are there any migration risks? Any downtime associated with this? No migration risks. Downtime is typically less than 5 minutes and no re-verification of the business phone number is required. Q. Is there any downtime associated with enabling local storage for a business phone number? If a business phone number is already registered, you will need to de-register and re-register the phone number with local storage enabled. This process typically takes less than 5 minutes. No re-verification of the business phone number is required during this process. Marketing Messages Marketing Messages API for WhatsApp | Developer Documentation Marketing Messages API for WhatsAppUpdated: Feb 10, 2026Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.MM API for WhatsApp is our next-generation marketing solution built to enhance the customer experience and deliver the right message to more of the right people. Key benefits Boost and measure business results: With our automatic delivery optimizations, you can reach more of the people who will find your messages valuable and may drive more reads and clicks. You can also access exclusive measurement insights: Performance benchmarks, to understand how your message performed compared to similar businessesTailored recommendations, to improve campaign performanceEnhance customer experience and engagement: MM API for WhatsApp helps deliver more relevant and timely marketing messages to customers with exclusive features like: Automatic creative optimizations (in testing), to apply creative treatments like image animation and filtering for more engaging messages.Richer media formats, like GIFs.Time-to-live, to avoid irrelevant or delayed message delivery for time-sensitive campaigns.Upgrade easily, with consistent reliability and security: MM API for WhatsApp is easy-to-use, reliable, and secure. It offers a similar technical schema and same billing model as Cloud API, and businesses can use existing phone numbers and MM templates.Send all your marketing traffic to the /marketing_messages endpoint for automatic routing of eligible business’ messages. Footnotes *An AB test was conducted with approximately 12 million delivered marketing messages sent by advertisers in India between January 1, 2025, and January 31, 2025. The test compared MM API for WhatsApp optimized delivery to standard Cloud API delivery for high engagement messages only (For example, messages with more reads, clicks, etc.) and the analysis consisted of a t-test at a 95% confidence level. Get started | Developer Documentation Get started Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Learn how to send a template message with the Marketing Messages API for WhatsApp (MM API for WhatsApp). RequirementsYou have an active WhatsApp Business Account and are in a country eligible for MM API for WhatsApp.You have an approved marketing template message.You are subscribed to the messages webhook. Step 1: Accept Terms of ServiceNavigate to the App Dashboard > WhatsApp > Quickstart panel.Locate the “Improve ROI with marketing messages with optimizations” module and click the “Get started” button.Click on “Continue to integration guide” and accept the Terms of Service. Step 3: Verify message was sent through the status webhook Geographic availability of features Some advanced features and reporting capabilities of MM API for WhatsApp are available only in particular geographies due to Meta policy and/or local regulation. European Economic Area, United Kingdom, Japan, South KoreaMessages sent from a business phone number in these countries, or to a consumer in these countries, will not receive delivery optimizations. Note that per-user marketing message template limits are also not active in these countries, so a lack of delivery optimizations will not have any effect on message delivery.Messages sent from a business phone number in these countries, or to a consumer in these countries, will not have click and conversion reporting metrics available.For businesses in these countries, metrics are not available on Ads Manager UI or Insights API. As with Cloud API, metrics will be available via Business Management API and WhatsApp Manager UI ‘conversation’ metrics. United StatesStarting April 1, 2025, marketing messages sent to WhatsApp users in the United States will not be delivered (error code 131049). Note that this policy is not specific to MM API for WhatsApp - it is in place across all Business Messaging APIs (including Cloud API, see docs).Businesses phone numbers in the US will continue to be able to use MM API for WhatsApp to message users outside of the United States. Cuba, Iran, North Korea, Syria, and three sanctioned regions in the Ukraine (Crimea, Donetsk, Luhansk):Businesses in these regions are not eligible to onboard, and messages cannot be sent to a consumer in these regions. This policy is not specific to MM API for WhatsApp - it is in place across all Business Messaging APIs (including Cloud API, see docs). Russia Starting June 20, 2025, businesses in Russia will be able to use MM API for WhatsApp with the following feature exceptions:Messages sent by a business with a Meta business profile in Russia, or using a payment method with a Russian address, will not receive delivery optimizations.Messages sent from a business phone number in these countries, or to a consumer in these countries, will not have click and conversion reporting metrics available. For businesses in these countries, metrics are not available on Ads Manager UI or Insights API. As with Cloud API, metrics will continue to be available via Business Management API and WhatsApp Manager UI conversation metrics.All other features of MM API for WhatsApp continue to be available. Learn moreLearn about additional marketing message formats Features | Developer Documentation FeaturesUpdated: Feb 10, 2026Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.Marketing Messages API for WhatsApp offers added features that are not available on Cloud API, such as performance benchmarks and recommendations, time-to-live, and automated creative optimizations (in testing).For more detail, see the comparison tables below. Optimization features Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Quality-based delivery: Improving deliveries of high engagement messages. Yes: Marketing Messages API for WhatsApp factors if a message is high engagement into delivery decisions, offering up to 9% higher deliveries vs. Cloud API (see footnote below). High engagement marketing messages refers to messages that are expected by users, relevant, and timely, and therefore more likely to be read and clicked. No: Message quality does not factor into per-user marketing message limits. No ability to increase delivery for high engagement messages. Automated creative optimizations: Automatic enhancements to creative to increase message performance. Yes (pilot): Automatically enhance the visual appeal and engagement of marketing template messages. See full list of capabilities here. No Marketing message formats Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Animated Image (GIF) Header: Marketing message templates support a GIF media type in the header. Yes No Android App Deep Links: Links that directly open up the app on a customer’s phone. Yes No Customizable Message Validity Periods: Set a time-to-live for messages that should expire if they cannot be delivered soon enough. Yes: TTL can range from 12 hours to 30 days. Limited: Only supports Authentication and Utility messages. Basic marketing message formats: Media, carousel, product catalog, flow, interactive list, interactive reply, etc. Yes Yes Guidance Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Benchmarks: Comparison of read and click rates versus similar templates from businesses in your region. Yes No Recommendations: Evidence-based recommendations to improve the performance of your template. Yes No Metrics Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Conversion metrics: Conversions on Web and App. Yes: Measure marketing messages leading users to perform app events, such as “Add to Cart”, “Checkout Initiated”, and “Purchase”. No Cost metrics: Spend per Template, Cost per click, Cost per delivery. Yes Yes Basic metrics: Sent, delivered, read, clicked, errors. Yes Yes Enterprise, Security 5 & Compliance Features Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Local Storage Support: Phone numbers with Local Storage enabled. Yes Yes Compliance certification: Compliance resources available on the Business Messaging Compliance Center⁠. Yes: Certification for LGPD, GDPR, System Audit Report, SOC, ISO27001. Yes: Certification for LGPD, GDPR, System Audit Report, SOC, ISO27001. Automatic throughput upgrades: Automatic upgrades (and webhook notifications) to a phone number’s messaging throughput. Yes Yes Real-time service status updates: Uptime and availability metrics are live on metastatus.com⁠. Yes Yes Onboarding Description Marketing Messages API for WhatsApp (Supports Marketing) Cloud API (Supports Auth, Utility, Service, Marketing) Streamlined Onboarding: Onboard via Embedded Signup, Intent API, and Intent UI. Yes Limited: Embedded signup only. Error Codes: Graph API error codes. Yes: Specific Marketing Messages API for WhatsApp error codes. Yes Onboarding Status via API: Granular eligibility status data and error codes. Yes: A new eligibility status field has been introduced to better report on the API onboarding status. Limited Coexistence: Onboarding WhatsApp business app users. Yes Yes FootnoteThe A/B test was conducted with ~12 million delivered marketing messages sent by advertisers in India between 1st Jan 2025 to 31st Jan 2025. It compared Marketing Messages API for WhatsApp optimized delivery to standard Cloud API delivery for high engagement messages only (that is to say, more reads, clicks, etc.) and the analysis consisted of a t-test at 95% confidence. Onboard | Developer Documentation Onboard Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Onboarding to the Marketing Messages API for WhatsApp (MM API for WhatsApp) is a low-effort upgrade to sending marketing messages with optimizations on Cloud API. See the directions below to onboard your business, whether you integrate with the API directly or work with a partner. When a business registers for the MM API for WhatsApp, read-only Ad accounts are created that are linked to each of the marketing templates that exist under their business portfolio. These linked accounts allow a business to:fetch their MM API for WhatsApp insights from the Marketing API “Insights API” to view the same These read-only ad accounts are kept in sync with any changes to marketing templates, so that any changes to marketing templates are reflected in the linked ad entity. Follow the steps below to Onboard to MM API for WhatsApp. Eligibility requirements In order to use the Marketing Messages API for WhatsApp (MM API for WhatsApp), a business must comply with applicable legal, vertical and content restrictions (country dependent) outlined in WhatsApp Business Messaging Policies⁠. In addition, the following requirements must be met:WABA is active and not restricted from messaging due to any violationsWABA tax country is not in sanctioned regionsOwner Business country is not in sanctioned regions MM API for WhatsApp will continuously update vertical eligibility and policies to comply with various policies and regulations internationally, so these requirements may change. Checking eligibility status (alternative) This field will be deprecated in version 24.0. We recommend using the marketing_messages_onboarding_status field instead. For partner-managed WABAs, businesses can find eligible WABAs using the following endpoint: Register a phone number on Cloud API In order to send a message via MM API for WhatsApp, a business phone number must also be registered on Cloud API. MM API for WhatsApp and Cloud API are used together on the same phone number: Cloud API allows a business to send Authentication, Service, Utility, and non-Optimized Marketing template messages and freeform messages, and receive inbound messages from consumers on a business phone number. MM API for WhatsApp allows a business to send marketing messages with optimizations, over the same phone number as is registered on Cloud API. WhatsApp Business phone numbers that are not registered on Cloud API cannot be used with MM API for WhatsApp. If a business phone number is already registered on Cloud API, phone number verification is not required when registering for MM API for WhatsApp, as no new phone numbers are registered during the MM API for WhatsApp registration process. Existing Phone Numbers remain registered on Cloud API, and will now be eligible to use MM API for WhatsApp in addition to and simultaneously with Cloud API for sending marketing messages. For solution providers If you are a solution provider onboarding your end businesses, refer to onboard business customers. Onboarding business customers You can instruct your business customers to have someone with full control to the business portfolio to accept the Terms of Service and onboard MM API for WhatsApp via WhatsApp Manager.Open WhatsApp Manager > Overview.In the Alerts section, click Accept terms to get started for Marketing Messages API for WhatsApp.Follow the steps to finish signing MM API for WhatsApp Terms of Service. Your business customers should be able to start sending messages via MM API for WhatsApp. If you are unable to access your WhatsApp Manager, find your business portfolio admin here. For business customers without a partner If your business directly integrates with Cloud API without a partner, follow the instructions below to accept the Terms of Service and onboard to MM API for WhatsApp.Navigate to the App Dashboard > WhatsApp > Quickstart panel.On the Quickstart page, locate the “Improve ROI with Marketing Messages API for WhatsApp” card and click the “Get started” button.Click on “Continue to integration guide” to accept the Terms of Service Receive MM API for WhatsApp Terms of Service signed webhook (Preferred) Note: The ToS event value will be available from September 8th, 2025. Refer to the legacy webhook below. When the MM API for WhatsApp Terms of Service (ToS) is signed for a business, a new account_update webhook will be sent for each WhatsApp Business Account (WABA) under your business portfolio. The webhook indicates that the WABA’s business has successfully accepted the MM API for WhatsApp ToS. When the webhook is triggered, your WABA will be allowed to send messages through MM API for WhatsApp. You can use the included business portfolio ID and WABA ID to verify compliance and begin sending messages, or trigger subsequent onboarding actions as needed. This webhook is the preferred webhook to track MM API for WhatsApp onboarding and eligibility status. Receive onboarding completion webhook (Legacy) Once you have completed onboarding and linked Ad accounts have been set up, an account_update webhook will be sent for each WABA under your business portfolio to indicate that onboarding has successfully completed. This webhook contains the ID of the read-only Ad account that each WABA is linked to, for use when calling Insights APIs. Note: This webhook is considered legacy for MM API for WhatsApp onboarding. Please use the MM API for WhatsApp Terms of Service signed webhook. Important: The ad_account_linked webhook event will no longer be fired since partners will not receive access to ad accounts. Setting up conversion measurement | Developer Documentation Setting up conversion measurement Updated: Mar 27, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Using Marketing Messages API for WhatsApp, you can integrate your marketing messages with events, allowing you to measure the rate and cost at which a Marketing message sent via Marketing Messages API for WhatsApp leads to a downfunnel event like “purchase” on your website or app. Conversion measurement is built on the same events that you can send to Meta when using Ads, making it seamless for businesses who are already integrated with Events for Ads purposes (for example, via Pixel or Conversions API for websites, or Meta SDK in their mobile app), to leverage the same reporting automatically with no setup. If a business is using both marketing messages on Marketing Messages API for WhatsApp and Ad Campaigns on the same business portfolio, conversion events reported will be automatically attributed to the last Meta touch (either Marketing Messages API for WhatsApp click or Ad click) before the event, based on the attribution window settings of each. For example, if a business is running both an Instagram Ad campaign and a Marketing message campaign on MM API for WhatsApp, each with a URL pointing to the same website for a sale, a user who purchases after clicking on both the Instagram Ad and the Marketing message will be attributed to either the MM API for WhatsApp click or the Ad click, based on the attribution window settings of each. This helps businesses better understand the holistic picture of their Ad and Marketing message campaigns in driving outcomes. Understanding linked Ad entities When a business registers for Marketing Messages API for WhatsApp, read-only Ad accounts are created under their business portfolio, which are synced to each WhatsApp Business Account under the same portfolio. Note that marketing messages are separate and distinct from Ads - the use of “Ads” terminology below represents the use of Ads entities as technical constructs only. No action is needed on the part of the business or partner - these linked read-only Ad accounts are kept in sync with any changes made to Marketing templates, so that any new or updated marketing templates are reflected by their linked ad entity. Linking Marketing templates to Ad accounts provides several benefits: Common UI and API for marketing teams: Businesses can view their Marketing Messages API for WhatsApp marketing campaigns and campaign metrics as “Campaigns” in Ads Manager’s “Marketing Messages” tab, and via API using the Marketing API “Insights API”. Using these interfaces helps a business’ marketing teams view their Ads and Marketing message campaigns using common interfaces and terminology, instead of viewing Ad campaigns in one place and marketing campaigns sent via WhatsApp in another. New metrics: The Ads Manager UI and Insights API report new Conversion metrics (for example, Web, App) that Cloud API and the Business Management API do not support. When Marketing template messages sent via MM API for WhatsApp lead to Conversion events (for example, add to cart, purchase) that a business reports from their website or app, these conversion events are attributed to the Marketing message and are shown in metrics, leading to a better understanding of Marketing message ROI. Reporting events is done via integration with Pixel or Conversions API for Web and App Events and the Meta SDK. Template-to-Ad-sync guidelines Marketing templates map to Ads only once during initial onboarding to Marketing Messages API for WhatsApp.Syncs must be completed for templates to display correct app conversion metrics.Ads syncing can take up to 10 minutes.Avoid sending messages with new templates before syncing completes to prevent errors or loss of optimization and tracking.Existing templates prior to initial onboarding will not have conversion metrics enabled.To reactivate unused templates for over 7 days: Send one message using the template and wait 10 minutes for Ad sync to re-activate. Understanding automatic objective setting In order to measure Conversion events, Marketing Messages API for WhatsApp automatically syncs Marketing templates to corresponding Ads entities (Campaigns, Message sets, and Ads) with configurations that allow for Conversion reporting of an assumed objective. This linking process happens automatically, to reduce the integration complexity of Marketing Messages API for WhatsApp for businesses. For those familiar with Meta’s Ads ecosystem, note that these Campaign and Ad Set parameters will not change how messages are delivered via Marketing Messages API for WhatsApp - they are only set so that reported events can be correctly attributed. The following table shows how Marketing templates are mapped to Ads entities. Campaign parameters Message Set parameters Marketing templates with no CTA URL button Objective:OUTCOME_SALES OptimizationGoal: Impression Marketing templates with a CTA URL button that points to a website or app without event reporting enabled. Objective:LINK_CLICKS OptimizationGoal: LinkClicks Marketing templates with a CTA URL button that points to a website or app with event reporting enabled. Objective:LINK_CLICKS OptimizationGoal: OffsiteConversion Event reporting is detected by whether the URL points to a website or app which the same business portfolio has enabled for event reporting via Pixel, Conversions API, or Meta SDK. While most changes to Templates will be automatically synced with Ads (for example, text content), Campaign and Message set parameters are synced only once when a business first onboards to Marketing Messages API for WhatsApp or creates a new Template, in order to maintain a consistent campaign and message set structure when reporting on clicks and conversions from messages sent using that Template. This means that if you wish to add, edit, or remove a URL from a CTA button on a Template, you must create a new Template in order to correctly capture click and conversion metrics for the updated URL. URL requirements for conversion measurement Meta appends a click ID to the URLs you send in CTA buttons on marketing template messages. The purpose of the click ID is to attribute events you report via Meta Pixel, Conversions API (web or app events), or the Meta SDK. The click ID is Meta-generated and is commonly attached as the fbclid query parameter. Example URL with fbclid query parameter: https://www.jaspersmarket.com/?fbclid=IwAR2F4-dbP0l7Mn1IawQQGCINEz7PYXQvwjNwB_qa2ofrHyiLjcbCRxTDMgk URL compatibility (short links, redirects, and URL rewriting) Some short-link and redirect services can interfere with conversion measurement if they strip, overwrite, or fail to forward query parameters that Meta appends. If you use a short-link provider or URL rewriting service, ensure it preserves all query parameters end-to-end. Example where fbclid is dropped: You configure your CTA destination as: https://www.jaspersmarket.com/checkout?campaign=whatsapp_templateYour link partner rewrites it to a short link that redirects to your site: https://www.example.com/jaspersmarketBefore sending, Meta appends a click ID to the short link: https://www.example.com/jaspersmarket?fbclid=xyz789When the user clicks, the short-link service redirects to your site but drops the query string, sending the user to: https://www.jaspersmarket.com/checkout?campaign=whatsapp_template (missing fbclid=xyz789) The click ID is not preserved through the redirect, which can reduce Meta’s ability to attribute conversions to the originating click. URL parameter ordering issues Appending additional query parameters after the fbclid parameter can cause redirection issues on some platforms. If your system adds custom parameters to a URL, ensure that the fbclid parameter is not disrupted or truncated by subsequent parameters. Test the full URL (with all parameters) to confirm that the destination resolves correctly and that fbclid is accessible to your site or app. Recommendations If you use short links or redirects: Test that the final URL retains all query parameters (including fbclid).Validate conversion reporting in Ads Manager and Insights API before sending production workloads.Avoid appending parameters after fbclid in ways that could disrupt the URL structure. If you experience issues, work with your partner to ensure query parameters are preserved, or reach out to Meta with details. Android deep links for conversion measurement Android routes deep links using intent filters declared by apps. A deep link URL has three parts: Scheme (for example, https, myapp) — helps determine which app can open the linkPath (for example, /product/123) — the route inside the appQuery parameters (for example, ?fbclid=...) — includes attribution data like fbclid, campaignId, al_applink_data, and others When a user taps a deep link, Android: Finds apps with intent filters that match the URL (scheme/host/path).Creates an implicit Intent.Delivers it to the target Activity (often via onCreate() and/or onNewIntent()), where the app must read the full URL (including query parameters). Android passes the URL, but your app must explicitly capture and persist attribution parameters. If you don’t, they can be effectively “lost” after the first screen. Attribution parameters like fbclid can be stripped, cached incorrectly, or not passed through as expected due to one or more of: Android intent resolution behavior (multiple handlers, re-launch behavior, or activity launch modes)How WhatsApp invokes app links (intermediary parsing and handoff to Android)Receiving app implementation gaps, for example: Only reading the URL in onCreate() but not onNewIntent()Not persisting the parameters for later use (install/deferred deep linking/session attribution)Redirecting internally and dropping query params when rebuilding a new URI Implementation checklist To ensure the click ID works correctly, the receiving Android app should: Read the full URI from the incoming Intent Handle both cold start ( onCreate()) and warm start/re-use ( onNewIntent())Extract attribution params (at minimum fbclid, and any others you rely on)Persist them for later conversion reporting/session attribution Store in a durable place (for example, SharedPreferences or a database) with a timestampRefresh if a newer value arrives (these identifiers can change over sessions)Do not drop query parameters when redirecting internally If your app converts a URI to an internal route, ensure you carry attribution params forward or persist them before routing Test deep link parameter preservation on Android When you open a deep link that includes fbclid, your app should be able to log (or otherwise confirm) that it received the URI including fbclid, and that it persisted it for subsequent events. Use a test link like: myapp://some/path?fbclid=TEST123&campaignId=TESTCAMPAIGN Or an https:// app link equivalent if you support it. Test using adb You can simulate what Android does by sending an Intent yourself: adb shell am start -W -a android.intent.action.VIEW \ -d "myapp://some/path?fbclid=TEST123&campaignId=TESTCAMPAIGN" Then confirm your app receives fbclid and persists it. Measure website conversions with Meta Pixel or Conversions API Businesses who are reporting events from their website using Meta Pixel or Conversions API for web, can measure when clicking on a URL in a marketing message sent via Marketing Messages API for WhatsApp leads to one of 3 conversion events. If a business is not yet reporting Offsite Conversion events from their website, see the following documentation to set up event reporting: Tutorial: Get started with the Meta Pixel and Conversions API⁠ Once a business is reporting events via Pixel or Conversions API, the following 3 standard events are automatically associated with website visitors who arrived at the site via a CTA URL from a marketing message sent via MM API for WhatsApp: Add to cartInitiate checkoutPurchasePurchase value When a user clicks a CTA URL in a Marketing Messages API for WhatsApp message and performs any of the above 3 events, Meta will automatically attribute the conversion event to the MM API for WhatsApp Campaign, and make those analytics available to you or your Partner via the Insights API, which your Partner may surface on their own reporting surfaces that you are accustomed to using. Note that if this conversion event is also being used to measure the efficacy of Ads on Facebook or Instagram, Meta will attribute the conversion to the ‘last touch’ interaction of the user. For example, if a user arrives at your website via an ad on Facebook, and then closes their browser window and later that day returns to your website via clicking a link from a MM API for WhatsApp message and purchases an item, that purchase conversion event will be attributed to the MM API for WhatsApp campaign (and not the ad on Facebook) as the most recent interaction. Tracking click events | Developer Documentation Tracking click events Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Available using Marketing Messages API for WhatsApp (MM API for WhatsApp) and Ads Manager only LimitationsAt the moment, this feature is not available for all usersClick events are only available for messages sent in the last 7 days Viewing metrics | Developer Documentation Viewing metrics Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Conversion metrics will be solely available in the WhatsApp Manager UI and WhatsApp Business Management API that businesses use with Cloud API in October 2025. As a result, the following conversion metrics will be depreciated: Viewing conversion metrics via Ads Manager UI (September 8th, 2025).Viewing conversion metrics via Ads Insights API (Q1 2026). Businesses that use Marketing Messages API for WhatsApp can view metrics from 4 surfaces: Via WhatsApp Business Platform surfaces WhatsApp Manager UIWhatsApp Business Management APIVia Ads surfaces (optional) Ads Manager UI “Marketing Messages” tabMarketing API “Insights API” ROI Reporting WhatsApp Business Management surfaces Ads surfaces Messages sent, delivered, read Y Y Total amount spent Y Y Cost per delivery Y Y CTA URL link clicks Y Y Cost per click Y Y CTA URL link click rate N Y Add to cart (Web + App) Y Y * Checkout initiated (Web + App) Y Y * Purchase, purchase value (Web + App) Y Y * App Activations Y Y * Quick Replies Y Y * Requires a business to report this conversion event via Meta Pixel or Conversions API for App Events see Get started with the Meta Pixel and Conversions API⁠. View metrics via UIs After sending Marketing Messages via Marketing Messages API for WhatsApp, view read-only metrics on sends, clicks, and conversions from two UIs: WhatsApp ManagerAds Manager “Marketing Messages” tab Marketing Messages API for WhatsApp metrics, can be viewed in WhatsApp Manager on both Phone Number and Template screens: Benchmarks and recommendations metrics Benchmark metrics provide insights into how your business is performing compared to similar businesses in your industry. These metrics are based on data from the past 30 days and take into account various factors that define similar businesses. Based on the benchmark metrics, we provide personalized recommendations to help you improve your template’s performance. If your template’s read rate or click rate falls below the benchmark, we provide suggestions to boost engagement. Calculating benchmarks To calculate benchmark metrics, we consider the following characteristics: Business Country or Region: We use the business country as the default cohort, but if the cohort size is too small, we switch to the business region.Business Industry: We compare your business with others in the same industry or vertical to provide relevant benchmarks.Template Categories: We only compare templates within the same category (e.g., marketing templates with other marketing templates) to ensure accurate and relevant benchmarks. We then calculate two key benchmark metrics: Read Rate Benchmark: We calculate this metric as the 75th percentile of read rates across similar businesses, representing the percentage of messages read out of total messages delivered.Click Rate Benchmark: We calculate this metric as the 75th percentile of click rates across similar businesses, representing the percentage of link clicks out of total messages delivered. Understanding your ranking and how to use benchmark metrics When you view your benchmark metrics, you will see a ranking that indicates how your template performs compared to templates in the same category. This ranking is calculated by comparing your template’s performance with the read rate or click rate performance of peer templates with high engagement over the past 30 days. Use the benchmark metrics to compare your template’s performance to templates from similar businesses over the past 30 days. Benchmarks are calculated daily, with a delay of up to 2 days. This ensures that you have access to updated and relevant data to inform your business decisions. To access the benchmark and recommendations metrics: Go to the WhatsApp Manager and select “Manage templates”.Choose the template you want to view.Select the “Marketing Messages API for WhatsApp” option from the dropdown menu highlighted in red.The benchmark metrics and recommendation cards will be displayed below the preview card in the left panel. Error metrics You can see a summary of error messages your template encountered within a given period of time by navigating to the WhatsApp Manager⁠ > Message templates > Manage templates panel and clicking on the template. Errors are displayed in the Error messages section. The period of time can be defined using the date selector dropdown at the top of the page. See Cloud API error codes for a list of error codes and their descriptions. The most frequently encountered message delivery errors are displayed in the Summary tab: This information is also displayed as trend lines in the Trend tab: Deep links | Developer Documentation Deep links Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. You can map an Android deep link? to a marketing template URL button that, when tapped, loads a particular location or content within your app. If you have not onboarded to the Marketing Messages API for WhatsApp (MM API for WhatsApp), your marketing templates will not display any conversion metrics. Learn more about how to measure conversion. Template creation via WhatsApp Manager To create a template with a button mapped to an Android deep link: Access WhatsApp Manager?.Navigate to the Message templates > Manage templates panel and click the Create template button.Select Marketing (tab) > Custom (radio button) and click the Next button.In the Buttons section, click the + Add buttons dropdown menu and select Visit website.Check the Track app conversions checkbox to reveal the deep link fields (pictured below).Complete each field using their tooltips or form field descriptions below as guidance.Add any additional components you'd like your template to use, name your template, and submit it for approval. Note that you can also use the Manage templates panel to edit an existing template and add a deep link-mapped button, but the template will have to undergo template review again. Form fields Field label Description Example value Android deep link Required. Android deep link URI. luckyshrub://deals/summer_solstice Android fallback URL Optional. Fallback URL. If the WhatsApp client cannot load the deep link URI, the client will load this URL in the device's default web browser. If omitted, the client will attempt to load the URL specified in the Website URL field instead. https://www.luckyshrub.com/deals/summer_solstice Button Text Required. Button label text. Maximum 25 characters. View deal Meta app ID Required. This is a list of the Meta app(s) associated with your business portfolio. Select the app whose access token you will use to send the template. Lucky Shrub (634974688087057) Type of Action Required. Must be set to Visit website. Visit website URL Type Required. Set to Static if your Android deep link or Android fallback URL has no dynamic values, otherwise set to Dynamic. Static Website URL Required. URL of a website to load if the WhatsApp user views the message on a non-Android device, or if the WhatsApp client cannot load your Android deep link URI and no Android fallback URL is specified. https://www.luckyshrub.com/ Viewing metrics See our Viewing metrics document. Send Marketing Messages | Developer Documentation Send Marketing Messages Updated: Mar 20, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Marketing Messages API for WhatsApp allows you to send marketing template messages only. To send other message types or receive messages, use Cloud API in parallel with Marketing Messages API for WhatsApp on the same business phone number. If you use a partner’s UI portals or APIs to configure and send marketing messages, you can continue to do so, and do not need to use any of the capabilities described in this document - your partner will take care of integrating with MM API for WhatsApp’s message sending functions on your behalf. Create marketing templates Marketing templates can be created in several ways:Via WhatsApp Business Manager UIVia the Business Management API “Message Templates” endpointIf you work with a partner, your partner may offer their own API or user interfaces for template creation, which leverage the “Message Templates” endpoint See documentation on how to Create and manage templates. When you create a new marketing template, it takes up to 10 minutes to sync with the corresponding Ad account. This sync allows messages to be optimized and enables measurement of clicks and downstream conversions. Templates inactive for longer than 7 days also require 10 minutes to sync after first use. Wait 10 minutes after creating new marketing templates before sending marketing traffic. The same applies after sending the first marketing message on a dormant template. Marketing Messages API for WhatsApp supports all marketing templates. In addition, Marketing Messages API for WhatsApp provides the following features that are not available to marketing templates on Cloud API:Time-To-Live (TTL) for Marketing template messages: If Meta is unable to deliver a message to a WhatsApp user, Meta will retry the delivery for a period of time known as a time-to-live, TTL, or the message validity period. TTL is available for Authentication and Utility template messages on Cloud API, but TTL for Marketing template messages is exclusively available on MM API for WhatsApp. See documentation on how to Create and Manage Templates via API or How to set a custom message validity period via UI⁠ for details on how to set TTLs for Marketing template messages. Other optimizations Text truncation Meta truncates text to a specific line-count to increase performance. No text content is changed, the original text is still accessible through the “Read more” button. The exact line count truncation rules are as follows:Messages without any CTA, but with a link in the message body (overrides the below rules): truncated to 5 linesMessages with a media header (Image, Video, Document, Location, and GIF): truncated to 3 linesMessages without a header (that is, Text messages): truncated to 4 lines Send marketing template messages Sending messages follows the same API payload syntax as Sending Messages on Cloud API, and requires the same permissions. The /marketing_messages endpoint supports only marketing template messages for MM API for WhatsApp and Cloud API. All other message types (freeform, Authentication, Service, Utility) are not supported, and will produce an error. Marketing messages will only be sent via MM API for WhatsApp when the business customer has met all onboarding requirements. If onboarding requirements are not met, the marketing messages will still be routed via Cloud API. You may disable the ability to route to Cloud API by setting the optional field product_policy to STRICT. Note: You may still use the /messages endpoint to send marketing messages through the Cloud API. Request syntax MM API for WhatsApp provides the following additional features that are not available to Marketing template messages on Cloud API: Product fallback policy: Set product_policy to CLOUD_API_FALLBACK to have the API send the outgoing message via Cloud API, if onboarding requirements have not been met. Set to STRICT if you do not want the API to fallback to sending the message via Cloud API. Message activity sharing:  message_activity_sharing is an optional parameter at the message level that enables or disables sharing message activities (for example, message read) for that specific marketing message to Meta to help optimize marketing messages. If this parameter is not provided, the default WABA-level setting will be applied. You can always edit your default setting in Business Settings (see Changelog for a screenshot of this). For details on message types, reference the Cloud API Message Types documentation, as MM API for WhatsApp uses the same message send formatting. Receiving message status webhooks MM API for WhatsApp triggers status messages webhooks (sent, delivered, read). In addition, status messages webhooks that describe a message sent via MM API for WhatsApp, and that include pricing information, will have pricing.category and conversation.type set to marketing_lite. If the message is routed via Cloud API, pricing.category will be set to marketing. Maintain logs of each outgoing message ID, and whether that ID was sent via Cloud API or MM API for WhatsApp, in order to use the unique message ID returned in message status webhooks to identify the origin of the sent message. Receiving incoming messages MM API for WhatsApp is a send-only API. It does not receive incoming messages from consumers. To receive incoming messages on a business phone number, use Cloud API in parallel with MM API for WhatsApp on the same phone number. Onboard business customers | Developer Documentation Onboard business customers Updated: Feb 10, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. The MM API for WhatsApp onboarding process is designed to be simple for you as a partner to adopt, making it quick and easy for solution providers (including Solution Partners, Tech Providers, and Tech Partners) to onboard current customers from Cloud API onto the MM API for WhatsApp. If your business directly integrates with Cloud API without a partner, follow the instructions below to accept the Terms of Service and onboard to the MM API for WhatsApp via WhatsApp Manager. Before you begin Your app must have advanced access for the following permissions: whatsapp_business_messaging: This permission allows the app to call the MM API for WhatsApp to send messages. whatsapp_business_management: This permission enables the app to manage WABAs, Phone Numbers, and Templates via WhatsApp Business Management API. ads_read (optional): This permission grants the app access to the Insights API, allowing partners to retrieve metrics on conversions. If your app does not already have advanced access for these permissions, request advanced access via App Review. Solution partner integration overview To assist your customers in using the MM API for WhatsApp, several steps are required: Step Notes 1: Onboard yourself Enroll via App Dashboard and follow instructions under the Onboarding yourself. 2: Send messages Same Template endpoint and message send payload as Cloud API - only the ‘send message’ endpoint changes. 3: View metrics New! Integrate with the Insights API to view the metrics as Cloud API (sent/read/delivered), plus new metrics like Website and App conversions. Onboarding yourself Register yourself for MM API for WhatsApp To enroll, a solution provider must: Navigate to the App Dashboard > WhatsApp > Quickstart panelOn the Quickstart page, locate the “Improve ROI with Marketing Messages API for WhatsApp” card and click the “Get started” buttonRequest any missing app review permissions by clicking the “Request permission” button. See “Submit for app review” for more informationClick on “Continue to integration guide” to accept the Terms of Service Submit for app review for Advanced App permissions Solution Providers must use an App with the following Advanced App permissions, when using the MM API for WhatsApp. If you do not already have an App with the following Advanced App Permissions, it is necessary for your App to go through App review: Advanced App Permission Required in order to do the following on behalf of your customer whatsapp_business_messaging Call the MM API for WhatsApp ‘send messages’ endpoint, to send messages via Marketing Messages API for WhatsApp whatsapp_business_management Call WABA, Phone Number, and Template endpoints, for managing WABAs, Phone Numbers, and Templates; and retrieve basic metrics via WhatsApp Business Management API ads_read (optional) This permission is optional, and is only required to call the Insights API, allowing a partner to fetch advanced metrics on conversions (e.g. Web conversions, App conversions) For the app review submission, prepare a screen recording of how each permission is used. It is recommended to show a sample of each action in the “Required in order to do …” column above, to demonstrate each permission in use. Help the business set up Conversion measurement See Setting up conversion measurement for details on how businesses can measure when a marketing message from MM API for WhatsApp leads to a conversion (e.g. add to cart, purchase). Partners are strongly recommended to work with their clients to set up Conversion reporting, so that they can take advantage of measuring the improved metrics and optimizations MM API for WhatsApp provides. Sending messages See Sending messages for documentation on how to send messages and receive webhooks on behalf of your customers via MM API for WhatsApp. Viewing metrics See the Guide to Viewing metrics for documentation on how to: Fetch the IDs of the Ad entities mapped to a business’ WABAs and Templates, in order to call Insights APIs.Fetch metrics for messages sent via MM API for WhatsApp. Partners are strongly recommended to fetch metrics using the Ads Insights APIs (not Business Management APIs), as these APIs provide richer metrics reporting, including conversion reporting from sources such as Web and App conversion events. After integrating with reporting APIs (Insights API recommended), surface these metrics in your dashboards and APIs for your customers to use. Reach out to your Partner Manager for suggestions on metrics best practices, including a copy of Meta’s “Business Messaging Reporting Dashboards Playbook” for partners. Set a max-price for marketing messages (BETA) | Developer Documentation Set a max-price for marketing messages (BETA) Updated: Mar 17, 2026 Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available. Amidst our introduction of the max-price feature on the Marketing Messages API for WhatsApp, there is no change to how we charge on the WhatsApp Business Platform. We continue to charge on a per-message basis, as outlined here. The max-price feature will become available via Limited Beta as of mid-May and be optional throughout 2026. What is a max-price? As announced in March 2026 -- in 2026, we're introducing new pricing features on the Marketing Messages API for WhatsApp to enable businesses to drive higher ROI and have more control to optimize spend for their marketing messaging campaigns. Our first pricing feature allows businesses to set a maximum price (max-price) per marketing message delivery; when a max-price is set, Meta will charge that max-price or lower for delivery. Businesses can choose to set a max-price the same as, lower than, or higher than the published rate to achieve their objectives per campaign.Lower costs while maintaining delivery rates similar to current WhatsApp campaigns, by setting max-prices the same as published rates.Target a broader range of customer cohorts on WhatsApp at lower cost, by setting max-prices lower than published rates.Increase delivery rates when customer engagement matters most, like during holidays and peak sales periods, by setting max-prices higher than published rates. The second pricing feature is the reach estimation tool, which helps businesses set the right max-price by helping them understand estimated delivery rates and costs at different max-prices. Max-price explainer The max-price feature allows you to set the maximum price you are willing to pay per message delivery. You are charged your max-price or lower. In the API, you express this as a bid_amount value per 1,000 deliveries within the bid_spec object.Max-price explainer PDF Phased roll-out of the max-price feature We plan to roll out our max-price feature in 3 phases:Limited Beta starting mid-May 2026 -- Any partner and any directly-integrated business can integrate and use the max-price feature and reach estimation tool. Each partner can enable these features for a limited number of clients.Open Beta starting October 2026 -- Any partner can enable these features for all their clients.General Availability (GA) as of Q2 2027 -- The max-price feature will become required in eligible geographies and fixed, published rates for marketing messages will only apply on the Cloud API. Before you begin To use the max-price feature, you must:Have an active WhatsApp Business Account that has been onboarded to the Marketing Messages API for WhatsApp.Be in a country eligible for MM API for WhatsApp. Recommendations Set your max-price at the template level. The bid_amount in bid_spec is what Meta's delivery system optimizes against. Setting the right max-price when you create the template gives the system the best signal for delivery optimization. The per_message_bid_multiplier scales the template's bid_amount up or down for individual messages, but the delivery system generally gives better performance optimizing based on the original template-level bid_amount on large amount. For example, if you set a template's bid_amount to 50,000 and then apply a multiplier of 2.0 on every message, delivery performance might differ from setting the template's bid_amount to 100,000 directly -- even though the effective max-price is the same. Hence we recommend setting up the bid at template level and update the template's bid_spec if needed rather than changing the message level multiplier as a workaround. Ramp up traffic gradually. When sending messages with a new max-price template for the first time, increase volume slowly before sending at scale. This aligns with Template pacing best practices and helps the delivery system optimize effectively. Create templates with max-price Request syntax If bid_spec is not included, the template uses standard rate card pricing. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. WhatsApp Business Account ID. 102290129340398 int Required. Maximum price per 1,000 message deliveries, expressed in your WABA currency's smallest unit (cents for USD, paise for INR, peso for MXN). See supported currencies for a list of currencies. 87000 Calculating max-price amounts The bid_amount represents your max-price per 1,000 deliveries in your WABA currency's smallest unit. To convert from your desired per-delivery price:Convert your desired per-delivery price to your WABA currency's smallest unitMultiply by 1,000 to express the value per 1,000 deliveries Example: To set a max-price of ?0.87 per delivery:Convert to paise: 0.87 Rupees = 87 paiseMultiply by 1,000: 87 x 1,000 = 87,000 Set bid_amount to 87000. Example: To set a max-price of $0.05 USD per delivery:Convert to cents: $0.05 = 5 centsMultiply by 1,000: 5 x 1,000 = 5,000 Set bid_amount to 5000. Metrics and billing Messages sent with or without the max-price feature use the same Marketing Lite product type (SKU) for billing purposes. Marketing messages sent with max-price appear in analytics with the following identifiers:Pricing Analytics /?fields=pricing_analytics: pricing_category = MARKETING_LITETemplate Analytics /?fields=template_analytics: product_type = MARKETING_MESSAGES_LITE_API Webhooks use lowercase marketing_lite for pricing.category, while analytics APIs use uppercase MARKETING_LITE for pricing_category. Pricing analytics response example Template analytics response example For more details on metrics, see Viewing metrics. Error codes Code Message Possible reasons and solutions 131061 Marketing templates containing bid_spec are not supported by the Cloud API. To use templates with bid_spec, please use the Marketing Messages API for WhatsApp. You are sending a template with bid_spec to the Cloud API /messages endpoint. Send to the /marketing_messages endpoint instead. 100 You need to sign the testing legal agreement before sending out messages. You have not signed the testing legal agreement. Please sign the agreement to gain access to this feature. For a full list of error codes, see Error codes. Messages Sending messages | Developer Documentation Sending messages Updated: Nov 4, 2025 This document describes how to use the API to send messages to WhatsApp users. Message types You can use the API to send the following types of messages. Address messages allow you to easily request a delivery address from WhatsApp users. Audio messages display an audio icon and a link to an audio file. When the WhatsApp user taps the icon, the WhatsApp client loads and plays the audio file. Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses. Document messages display a document icon, linked to a document that a WhatsApp user can tap to download. Image messages display a single image and an optional caption. Interactive CTA URL button messages allow you to map any URL to a button, so you don’t have to include lengthy or obscure raw URLs in the message body. Interactive voice call messages allow you to trigger WhatsApp call from users. Interactive Flow messages allow you to send structured messages that are more natural or comfortable for your customers. For example, you can use WhatsApp Flows to book appointments, browse products, collect customer feedback, get new sales leads, or anything else. Interactive Flow messages are documented in our WhatsApp Flows documentation set. Interactive list messages allow you to present WhatsApp users with a list of options to choose from. Interactive location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can use to share their location. Interactive reply buttons messages allow you to send up to three predefined replies for users to choose from. Location messages allow you to send a location’s latitude and longitude coordinates to a WhatsApp user. Sticker messages display animated or static sticker images in a WhatsApp message. Text messages are messages containing only a text body and an optional link preview. Template messages allow you to send marketing, utility, and authentication templates to WhatsApp users. Unlike all other message types, template messages do not require a 24-hour customer service window to be open between you and the message recipient before the message can be sent. Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user. Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received. Message quality Your message quality is based on how messages have been received by WhatsApp users over the past seven days and is weighted by recency. It is determined by a combination of user feedback signals like blocks, reports, mutes, archives, and reasons users provide when they block you. Guidelines for sending high-quality messages: Make sure your messages follow the WhatsApp Business Messaging Policy⁠.Only send messages to WhatsApp users who have opted into receiving messages from your business.Make the messages highly personalized and useful to users.Avoid sending open-ended welcome or introductory messages.Avoid sending customers too many messages a day.Optimize your messages for content and length. Your business phone number’s status, quality rating⁠, and messaging limits are displayed in the WhatsApp Manager⁠ > Account tools > Phone numbers panel. Note that it is normal for numbers with high traffic to experience quality changes within short intervals (even within minutes). Customer service windows Whenever a WhatsApp user messages you or calls you, a 24-hour timer called a customer service window starts (or refreshes if one has already been started). When a customer service window is open between you and a user, you can send any type of message to the user. If a window is not open between you and the user, you can only send template messages to the user, as template messages are the only type that can be sent outside of a customer service window. As a reminder, you can only send messages to users who have opted-in to receiving messages from you. Known issue: In rare cases, you may receive a message from a user but be unable to respond within the customer service window. We apologize for the inconvenience. Commerce messages Commerce messages are interactive messages used in conjunction with a product catalog. See Share Products With Customers to see how to use these types of messages. Read receipts You can let a WhatsApp user know you have read their message by marking it as read, which causes two blue check marks (called “read receipts”) to appear below the user’s message: Typing indicators If it may take you a few seconds or more to respond to a WhatsApp user, you can let them know that you are preparing a response by display a typing indicator and read receipts in the WhatsApp client: Contextual replies You can send a message to a WhatsApp user as a contextual reply, which quotes a previous message in a contextual bubble: This makes it easier for the user to know which specific message you are replying to. WhatsApp user phone number formats Plus signs ( +), hyphens ( -), parenthesis ( (, )), and spaces are supported in send message requests. We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number’s country calling code is prepended to the customer’s phone number. This can result in undelivered or misdelivered messages. For example, if your business is in India (country calling code 91) and you send a message to the following customer phone number in various formats: Number In Send Message Request Number Message Delivered To Outcome +16315551234 +16315551234 Correct number +1 (631) 555-1234 +16315551234 Correct number (631) 555-1234 +916315551234 Potentially wrong number 1 (631) 555-1234 +9116315551234 Potentially wrong number Note: For Brazil and Mexico, the extra added prefix of the phone number may be modified by the Cloud API. This is a standard behavior of the system and is not considered a bug. Media caching If you are using a link ( link) to a media asset on your server (as opposed to the ID ( id) of an asset you have uploaded to our servers), WhatsApp Cloud API internally caches the asset for a static time period of 10 minutes. We will use the cached asset in subsequent send message requests if the link in subsequent message send payloads is the same as the link in the initial message send payload. If you don’t want us to reuse the cached asset in a subsequent message within the 10 minute time period, append a random query string to the asset link in the new send message request payload. We will treat this as a new asset, fetch it from your server, and cache it for 10 minutes. For example: Asset link in 1st send message request: https://link.to.media/sample.jpg — asset fetched, cached for 10 minutesAsset link in 2d send message request: https://link.to.media/sample.jpg - use cached assetAsset link in 3rd send message request: https://link.to.media/sample.jpg?abc123 - asset fetched, cached for 10 minutes Delivery sequence of multiple messages When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a status messages webhook before sending the next message in your message sequence. Message Time-To-Live (TTL) If we are unable to deliver a message to a WhatsApp user, we will retry the delivery for a period of time known as a time-to-live, TTL, or the message validity period. Default TTL All messages except authentication templates: 30 days.Authentication templates: 10 minutes Customizing TTL for templates You can customize the default TTL for authentication and utility templates, and for marketing templates sent using the Marketing Messages API for WhatsApp. See our Time-to-live document to learn how. When TTL is Exceeded: Dropped messages Messages that are unable to be delivered within the default or customized TTL are dropped. If you do not receive a status messages webhook with status set to delivered before the TTL is exceeded, assume the message was dropped. If you send a message that fails ( status set to failed), there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming the message was dropped. Troubleshooting If you are experiencing problems with message delivery, see Message Not Delivered. Audio messages | Developer Documentation Audio messages Updated: Feb 17, 2026 On March 17th, 2026, voice messages will start receiving a “played” status webhook the first time a WhatsApp user plays a voice message shared by the business. You can use Cloud API to send voice messages and basic audio messages. Voice messages A voice message (sometimes referred to as a voice note, voice memo, or audio) is a recording of one or more persons speaking, and can include background sounds like music. Voice messages include features like automatic download, profile picture, and voice icon. These features are not available with basic audio messages. If the user sets voice message transcripts to Automatic, the message includes a text transcription. Voice messages require .ogg files encoded with the OPUS codec. If you send a different file type or a file encoded with a different codec, voice message transcription will fail.The play icon will only appear if the file is 512KB or smaller, otherwise it will be replaced with a download icon (a downward facing arrow).The message displays your business’s profile image with a microphone icon.The text transcription appears if the user has enabled Automatic voice message transcripts⁠. If the user has set this to Manual, the text “Transcribe” will appear instead, which will display the transcribed text once tapped. If the user has set voice message transcripts to Never, no text will appear. Basic audio messages Basic audio messages display a download icon and a music icon. When the WhatsApp user taps the play icon, the user manually download the audio message for the WhatsApp client to load and then play the audio file. The download icon will be replaced with a play icon if the WhatsApp user has enabled auto-download⁠ for audio media and conditions for auto-download are met (e.g. connected to wi-fi).If you send a .ogg file encoded with the OPUS code as a basic audio message, the music icon will be replaced with a microphone icon. In addition, if the user has enabled Automatic or Manual voice message transcripts⁠, a text transcription or the text “Transcribe” will accompany the message. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 Boolean Optional. Set to true if sending a voice message. Voice messages must be Ogg files encoded with the OPUS codec. To send a basic audio message, set to false or omit entirely. true String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 String Required if using hosted media, otherwise omit. URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. https://www.luckyshrub.com/media/ringtones/wind-chime.mp3 String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Supported audio formats Audio Type Extension MIME Type Max Size AAC .aac audio/aac 16 MB AMR .amr audio/amr 16 MB MP3 .mp3 audio/mpeg 16 MB MP4 Audio .m4a audio/mp4 16 MB OGG Audio .ogg audio/ogg (OPUS codecs only; base audio/ogg not supported; mono input only) 16 MB The most common errors associated with audio files are mismatched MIME types (MIME type doesn’t match the file type indicated by the file name) and invalid encoding for Ogg files (OPUS codec only). If you encounter an error when sending a media file, verify that your audio file’s MIME type matches its extension and is a supported type. For Ogg files, use the OPUS codec for encoding. Contacts messages | Developer Documentation Contacts messages Updated: Nov 3, 2025 Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses. When a WhatsApp user taps the message's profile arrow, it displays the contact's information in a profile view: Each message can include information for up to 257 contacts, although it is recommended to send fewer for usability and negative feedback reasons. Please be aware that a contact's metadata (e.g., addresses, birthdays, emails) may not be supported by the recipient, especially on their primary device. Please refer to this documentation? for the definitions of primary and linked devices. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Type of address, such as home or work. Home String Optional. Graph API version. v25.0 String Optional. Contact's birthday. Must be in YYYY-MM-DD format. 1999-01-23 String Optional. City where the contact resides. Menlo Park String Optional. Name of the company where the contact works. Lucky Shrub String Optional. ISO two-letter country code. US String Optional. Country name. United States String Optional. Department within the company. Legal String Optional. Email address of the contact. bjohnson@luckyshrub.com String Optional. Type of email, such as personal or work. Work String Optional. Contact's first name. Barbara String Required. Contact's formatted name. This will appear in the message alongside the profile arrow button. Barbara J. Johnson String Optional. Contact's job title. Lead Counsel String Optional. Contact's last name. Johnson String Optional. Contact's middle name. Joana String Optional. WhatsApp user phone number. +16505559999 String Optional. Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. Home String Optional. Prefix for the contact's name, such as Mr., Ms., Dr., etc. Dr. String Optional. Two-letter state code. CA String Optional. Street address of the contact. 1 Lucky Shrub Way String Optional. Suffix for the contact's name, if applicable. Esq. String Optional. Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. Company String Optional. Website URL associated with the contact or their company. https://www.luckyshrub.com String Optional. WhatsApp user ID. If omitted, the message will display an Invite to WhatsApp button instead of the standard buttons. See Button Behavior below. 19175559999 String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 String Optional. Postal or ZIP code. 94025 Button behavior If you include the contact's WhatsApp ID in the message (via the wa_id property), the message will include a Message and a Save contact button: If the WhatsApp user taps the Message button, it will open a new message with the contact. If the user taps the Save contact button, they will be given the option to save the contact as a new contact, or to update an existing contact. If you omit the wa_id property, both buttons will be replaced with an Invite to WhatsApp button: Document messages | Developer Documentation Document messages Updated: Nov 3, 2025 Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Media asset caption text. Maximum 1024 characters. Lucky Shrub Invoice String Optional. Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension. lucky-shrub-invoice.pdf String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 String Required if using hosted media, otherwise omit. URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Supported document types Document Type Extension MIME Type Max Size Text .txt text/plain 100 MB Microsoft Excel .xls application/vnd.ms-excel 100 MB Microsoft Excel .xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 100 MB Microsoft Word .doc application/msword 100 MB Microsoft Word .docx application/vnd.openxmlformats-officedocument.wordprocessingml.document 100 MB Microsoft PowerPoint .ppt application/vnd.ms-powerpoint 100 MB Microsoft PowerPoint .pptx application/vnd.openxmlformats-officedocument.presentationml.presentation 100 MB PDF .pdf application/pdf 100 MB Only the above listed document types are officially supported and guaranteed to display correctly in the WhatsApp client. Other file types may be sent via the API, but they are not supported and may not be handled as expected. Image messages | Developer Documentation Image messages Updated: Nov 3, 2025 Image messages are messages that display a single image and an optional caption. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Media asset caption text. Maximum 1024 characters. The best succulent ever? String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 String Required if using hosted media, otherwise omit. URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. https://www.luckyshrub.com/assets/succulents/aloe.png String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Supported image formats Images must be 8-bit, RGB or RGBA. Image Type Extension MIME Type Max Size JPEG .jpeg image/jpeg 5 MB PNG .png image/png 5 MB Interactive Call-to-Action URL Button Messages | Developer Documentation Interactive Call-to-Action URL Button Messages Updated: Nov 3, 2025 WhatsApp users may be hesitant to tap raw URLs containing lengthy or obscure strings in text messages. In these situations, you may wish to send an interactive call-to-action (CTA) URL button message instead. CTA URL button messages allow you to map any URL to a button so you don't have to include the raw URL in the message body. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required if using a header with a media asset. Asset URL on a public server. https://www.luckyshrub.com/assets/lucky-shrub-banner-logo-v1.png String Required. Body text. URLs are automatically hyperlinked. Maximum 1024 characters. Tap the button below to see available dates. String Required. Button label text. Must be unique if using multiple buttons. Maximum 20 characters. See Dates Required. URL to load in the device's default web browser when tapped by the WhatsApp user. https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4 String Required if using a footer. Footer text. URLs are automatically hyperlinked. Maximum 60 characters. Dates subject to change. String Required if using a text header. Header text. Maximum 60 characters. New workshop dates announced! String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Interactive list messages | Developer Documentation Interactive list messages Updated: Nov 3, 2025 Interactive list messages allow you to present WhatsApp users with a list of options to choose from (options are defined as rows in the request payload): When a user taps the button in the message, it displays a modal that lists the options available: Users can then choose one option and their selection will be sent as a reply: This triggers a webhook, which identifies the option selected by the user. Interactive list messages support up to 10 sections, with up to 10 rows for all sections combined, and can include an optional header and footer. Request parameters Placeholder Description Sample Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Button label text. When tapped, reveals rows (options the WhatsApp user can tap). Supports a single button. Maximum 20 characters. Shipping Options String Required. Message body text. Supports URLs. Maximum 4096 characters. Which shipping option do you prefer? String Optional. Message footer text. Maximum 60 characters. Lucky Shrub: Your gateway to succulentsT String Optional. The header object is optional. Supports text header type only. Maximum 60 characters. Choose Shipping Option String Optional. Row description. Maximum 72 characters. Next Day to 2 Days String Required. At least one row is required. Supports up to 10 rows. Maximum 200 characters. priority_express String Required. Row title. At least 1 row is required. Supports up to 10 rows. Maximum 24 characters. Priority Mail Express String Required. Section title text. At least 1 section is required. Supports up to 10 sections. Maximum 24 characters. I want it ASAP! String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Interactive media carousel messages | Developer Documentation Interactive media carousel messages Updated: Dec 22, 2025 Interactive media carousel messages display a set of horizontally scrollable media cards. Each card can display an image or video header, body text, and either quick-reply buttons or a URL button. For example, this is an interactive media card carousel message showing three cards in a scrollable area (highlighted by a dotted rectangle), each with an image header, body text, and URL button: This is the same message, but using quick-reply buttons instead of URL buttons: Components Messages must include between 2 and 10 cards.Main message body text is required.Main message headers, footers, and interactive components are not supported.Cards must include either an image or video header. Other header types are not supported.Card body text is optional.Cards must include either one URL button, or one or more quick-reply buttons. Button types and numbers must match across all cards (for example, if you define a card with 2 quick-reply buttons, all cards must define exactly 2 quick-reply buttons). Request parameters Placeholder Description Example value String Required. Access token. EAAJB... String Optional. API version. v23.0 Integer Required. Business phone number ID. 106540352242922 String Optional. Card body text. Max 160 characters, and up to 2 line breaks. *Blue Echeveria*\n\nA rosette-shaped succulent with powdery blue leaves, perfect for brightening up any space. Integer Required. Zero-index card index. Cards will appear left to right in scrollable view, starting from 0. 0 String Required. Header type. Value can be: image - Indicates a card image header. video - Indicates a card video header. See Supported media types. image String Required. Publicly available media asset URL. https://www.luckyshrub.com/assets/blue-echeveria.jpeg String Required. Main message body text. Maximum 1024 characters. Of course! Here are three of our latest arrivals, each under $25: String Required if using a quick-reply button. Quick-reply button ID. Maximum 256 characters. learn-blue-echeveria String Required if using a quick-reply button. Quick-reply button label text. Maximum 20 characters. Learn more String Required if using a URL button. URL button label text. Maximum 20 characters. Buy now String Required if using a URL button. URL to load in the device's default web browser when tapped by the user. https://shop.luckyshrub.com/latest/blue-echeveria String Required. WhatsApp user phone number. 16505551234 Location messages | Developer Documentation Location messages Updated: Nov 3, 2025 Location messages allow you to send a location's latitude and longitude coordinates to a WhatsApp user. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Location address. 101 Forest Ave, Palo Alto, CA 94301 String Required. Location latitude in decimal degrees. 37.44216251868683 String Required. Location longitude in decimal degrees. -122.16153582049394 String Optional. Location name. Philz Coffee String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Location request messages | Developer Documentation Location request messages Updated: Nov 3, 2025 Location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can then use to share their location. Once the user shares their location, a messages webhook is triggered, containing the user's location details. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Message body text. Supports URLs. Maximum 1024 characters. Let's start with your pickup. You can either manually *enter an address* or *share your current location*. String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Webhook syntax When a WhatsApp user shares their location in response to your message, a messages webhook is triggered containing the user's location details. Webhook parameters Placeholder Description Example Value String Location address. This parameter will only appear if the WhatsApp user chooses to share it. 1071 5th Ave, New York, NY 10128 Number Location latitude in decimal degrees. 40.782910059774 Number Location longitude in decimal degrees. -73.959075808525 String Location name. This parameter will only appear if the WhatsApp user chooses to share it. Solomon R. Guggenheim Museum String UNIX timestamp indicating when our servers processed the WhatsApp user's message. 1702920965 String WhatsApp Business Account ID. 102290129340398 String WhatsApp business phone number's display number. 15550783881 String WhatsApp business phone number. 15550783881 String WhatsApp business phone number ID. 106540352242922 String WhatsApp message ID of message that the user is responding to. wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1QjJGRjI1RDY0RkE4Nzg4QzcA String WhatsApp message ID of the user's message. wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTRCRDcwNzgzMTRDNTAwRTgwRQA= String WhatsApp user's WhatsApp ID. 16505551234 String WhatsApp user's name. Pablo Morales Reaction messages | Developer Documentation Reaction messages Updated: Nov 3, 2025 Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received. Limitations When sending a reaction message, only a sent message webhook ( status set to sent) will be triggered; delivered and read message webhooks will not be triggered. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Unicode escape sequence of the emoji, or the emoji itself, to apply to the user message. Unicode escape sequence example: \uD83D\uDE00 Emoji example: ?? String Required. WhatsApp message ID of message you want to apply the emoji to. If the message you are reacting to is more than 30 days old, doesn't correspond to any message in the chat thread, has been deleted, or is itself a reaction message, the reaction message will not be delivered and you will receive a messages webhook with error code 131009. wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA= String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Template Messages | Developer Documentation Template MessagesUpdated: Nov 4, 2025Template messages are used to send templates to WhatsApp users. Templates can cover customer care messages, appointment reminders, payment and shipping updates, and much more. Templates are reusable and can be sent to WhatsApp users outside of a customer service window, however they must be approved before they can be sent in a template message. Templates are also subject to multiple processes that can affect your ability to send them to users, such as quality scores, pausing, and pacing.Because there’s a lot to know about templates, we have dedicated Templates documentation that explains how to use them effectively. Text messages | Developer Documentation Text messages Updated: Nov 3, 2025 Text messages are messages containing only a text body and an optional link preview. Link preview You can have the WhatsApp client attempt to render a preview of the first URL in the body text string, if it contains one. URLs must begin with http:// or https://. If multiple URLs are in the body text string, only the first URL will be rendered. If omitted, or if unable to retrieve a link preview, a clickable link will be rendered instead. Video Messages | Developer Documentation Video Messages Updated: Nov 3, 2025 Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user. Supported Video Formats Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only. Note that videos encoded with the H.264 “High” profile and B-frames are not supported by Android WhatsApp clients. We recommend that you use H.264 “Main” profile without B-frames, or the H.264 “Baseline” profile when encoding (or re-encoding with a tool like ffmpeg), and place moov boxes before mdat boxes, for broader compatibility. If you are using ffmpeg, you can use the -movflags faststart flag to place moov boxes before mdata boxes. Video Type Extension MIME Type Max Size 3GPP .3gp video/3gpp 16 MB MP4 Video .mp4 video/mp4 16 MB Mark messages as read | Developer Documentation Mark messages as read Updated: Nov 3, 2025 When you get a messages webhook indicating an incoming message, you can use the message.id value to mark the message as read. It's good practice to mark an incoming messages as read within 30 days of receipt. Marking a message as read will also mark earlier messages in the thread as read. Request parameters Placeholder Description Example value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp message ID. This ID is assigned to the messages.id property in received message messages webhooks. wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQjZCMzlEQUE4OTJBMTE4RTUA Contextual replies | Developer Documentation Contextual replies Updated: Oct 21, 2025 Contextual replies are a special way of responding to a WhatsApp user message. Sending a message as a contextual reply makes it clearer to the user which message you are replying to by quoting the previous message in a contextual bubble: Limitations You cannot send a reaction message as a contextual reply. The contextual bubble will not appear at the top of the delivered message if: The previous message has been deleted or moved to long term storage (messages are typically moved to long term storage after 30 days, unless you have enabled local storage).You reply with an audio, image, or video message and the WhatsApp user is running KaiOS.You use the WhatsApp client to reply with a push-to-talk? message and the WhatsApp user is running KaiOS.You reply with a template message. Address Messages | Developer Documentation Address Messages Updated: Nov 7, 2025 This feature is only available for businesses based in India and their India customers. Address messages give your users a simpler way to share the shipping address with the business on WhatsApp. Address messages are interactive messages that contain the 4 main parts: header, body, footer, and action. Inside the action component business specifies the name “address_message” and relevant parameters. Below table outlines the fields that are supported by the address message. Field Name Display Label Input Type Supported Countries Limitations name Name text India None phone_number Phone Number tel India Valid phone numbers only in_pin_code Pin Code text India Max length: 6 house_number Flat/House Number text India None floor_number Floor Number text India None tower_number Tower Number text India None building_name Building/Apartment Name text India None address Address text India None landmark_area Landmark/Area text India None city City text India None state State text India None Error Handling If the area code of the phone number for the given country is not correct, businesses will be unable to request the address message from the recipient. For example, businesses will be unable to request an address message from a recipient that has the country as “India” but has a phone number with an area code of “65”. Once the address message is sent, the business waits for the user to fill in the address and send it back. The user entered address is shared through the webhook registered in the setup process. Address Message Steps The steps involved in an Address Message are the following:Business sends an address message with the action name address_message to the userUser interacts with the message by clicking on the CTA, which brings up an Address Message screen. The user fills out their address and submits the formAfter the address message form is submitted by the user, the partner receives a webhook notification, which contains the details of the address submitted by the user Sample India Address Message The following sequence diagram shows a typical integration flow for an address message. Check Your Response A successful response includes a messages object with an ID for the newly created message. An unsuccessful response contains an error message. See Error and Status Codes for more information. Feature Not Supported In the case where the client does not support address_message, messages are silently dropped and an error message is sent back to the business in a webhook. The webhook notification that would be sent back is shown below: Messaging Limits Messaging Limits | Developer Documentation Messaging Limits Updated: Nov 26, 2025 The messaging_limit_tier field, which used to return a business phone number's messaging limit, has been deprecated. Request the whatsapp_business_manager_messaging_limit field instead. This document describes messaging limits for the WhatsApp Business Platform. Messaging limits are the maximum number of unique WhatsApp user phone numbers your business can deliver messages to, outside of a customer service window, within a moving 24-hour period. Messaging limits are calculated and set at the business portfolio level and are shared by all business phone numbers within a portfolio. This means that if a business portfolio has multiple business phone numbers, it's possible for one number to consume all of the portfolio's messaging capability within a given period. Newly created business portfolios have a messaging limit of 250, but this limit can be increased to:2,000 (by completing a scaling path)10,000 (via automatic scaling)100,000 (via automatic scaling)Unlimited (via automatic scaling) Increasing your limit You can increase your messaging limit to 2,000 by completing one of the scaling paths below. After that, we will automatically increase your limit to the next higher limit if you meet our automatic scaling criteria. Scaling pathsVerify your business?Have your solution provider verify your business (if you were onboarded by one)Send 2,000 delivered messages outside of customer service windows to unique WhatsApp user phone numbers within a 30-day moving period, using templates with a high quality rating. Once you complete one of these paths, we will analyze your message quality. Based on this analysis, your number's eligibility for automatic scaling will either be approved or denied. Approvals If your request is approved, we will immediately increase your business phone number's messaging limit to 2,000 and notify you by email and developer alert. In addition, a business_capability_update webhook will be triggered with max_daily_conversations_per_business (for webhooks v24.0 and newer) and max_daily_conversation_per_phone (for v23.0 and older, until February, 2026) set to the new limit. Additional messaging limit increases for your number can now happen automatically, via automatic scaling. Denials If your request is denied, we will maintain your business phone number's messaging limit at its current level and notify you via email and developer alert. In addition, an account_alerts webhook will be triggered, with the alert_type and alert_description properties indicating alternate methods you can pursue to increase your limit. `alert_type` Value Action you can take INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED Send 2,000 delivered messages outside of customer service windows to unique WhatsApp user phone numbers in a 30-day moving period, using templates with a high quality rating. INCREASED_CAPABILITIES_ELIGIBILITY_FAILED Send 2,000 delivered messages outside of customer service windows to unique WhatsApp user phone numbers within a 30-day moving period, using templates with a high quality rating. INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO Verify your identity?, or send 2,000 delivered messages outside of customer service windows to unique WhatsApp user phone numbers within a 30-day moving period, using templates with a high quality rating. Automatic scaling Once your business portfolio's messaging limit has been increased to 2,000, we will determine if it should be increased further according to the following criteria:You are sending high-quality messages across all of your business phone numbers and templatesIn the last 7 days, your business has utilized at least half of your current messaging limit If these criteria are met, we will increase your portfolio's limit by one level within 6 hours. Checking your limit Via Meta Business Suite Your business phone number's current messaging limit is displayed in the WhatsApp Manager? > Account tools > Messaging limits panel: Via API Note that the messaging_limit_tier, which used to return the phone number's messaging limit, has been deprecated. No Storage No Storage | Developer Documentation No Storage Updated: Dec 1, 2025 “No Storage” is a custom configuration of Cloud API local storage, where the data in-transit is kept for up to an hour in Meta data centers and the data is not persisted at rest (that is to say, not in Meta data centers nor in AWS In-Country stores).Outgoing/incoming messages are stored for a maximum of 1 hour in Meta data centers.Outgoing/incoming media blobs are stored for a maximum of 1 hour in Meta data centers.You can pass a custom time-to-live (TTL) — from 1 hour to 30 days — when uploading media to override the 1 hour expiration (particularly useful for marketing campaigns which reuse the same media) Limitations When the No Storage feature is enabled, message content is not stored at rest for 30 days as is typical with Cloud API. This introduces the following limitations, which can put a small fraction of your total messaging volume at risk of non-delivery.Message decryption failures — If a message fails to decrypt on the consumer side, Cloud API can only retry sending the message within a 1-hour TTL window. After this 1-hour window, Cloud API cannot retry the message. You will receive an error webhook indicating the failure. See: Retry Receipt Failures.Webhook delivery failures — Normally, Cloud API retries undelivered webhooks (such as incoming messages or receipts) for up to 7 days. With No Storage enabled, webhook retries are limited to 1 hour. If your webhook server is unavailable beyond this window, the webhook (including incoming messages, receipts, etc.) will be permanently lost. See: Failure to Deliver Webhooks.Incoming media messages — Media attached to incoming messages will be available for download for up to 1 hour. After 1 hour, the media is permanently deleted and cannot be retrieved. Disable No Storage Error webhooks Retry receipt failures In the case of WhatsApp client decryption failures, we will stop attempting to deliver an undelivared message from a No Storage-enabled number once the TTL is reached. In these cases, a status messages webhook is triggered with error code 131036: Example payload Notes:This error is sent only if we fail to honor a retry receipt sent by the primary device. If the retry fails for a secondary device, we ignore it, as the message will be delivered when syncing with the primary device.It is possible that the message has been successfully delivered to secondary devices but not the primary device. In this case, the webhook will be sent. Failure to deliver webhooks By default, Cloud API retries for up to 7 days to deliver incoming messages webhooks. For No Storage-enabled business phone numbers, if we fail to deliver an incoming message webhook, we will drop it and instead send an errors messages webhook with error code 131035: Official Business Accounts Official Business Accounts | Developer Documentation Official Business Accounts Updated: Dec 12, 2025 An Official Business Account (“OBA”) is a business phone number owned by a business that has been verified as an authentic and notable brand according to specific criteria. Official Business Account business phone numbers have a blue checkmark beside their name in the contacts view. You can request OBA status for a business phone number using WhatsApp Manager or API. Once we’ve reviewed your request, you will receive a notification letting you know if your business phone has been granted OBA Number status or not. If your request is rejected, you can submit a new request after 30 days. We do not grant OBA status to business employees, test accounts, and WhatsApp Business app phone numbers. Eligibility To be eligible for OBA, the following criteria must be met: The business must comply with the WhatsApp Business Messaging Policy⁠.The business must be registered on the WhatsApp Business Platform for at least 30 days.The business represents a notable, well-known, and frequently searched for business, brand, or entity.The business portfolio that owns the number has been verified through Business Verification⁠.The business phone number has enabled two-step verification.The business phone number’s display name has been approved. If you meet the above criteria but do not see an option to apply for OBA in WhatsApp Manager⁠, please reach out to your Meta point-of-contact, Solution Provider support, or Meta Support to check if you are eligible for the application process. Note: If a business phone number is not an Official Business Account (OBA), it will not appear in search results when users search for it within the WhatsApp application. However, if a user adds the number to their contacts, the display name will appear in their search results. For improved discoverability, we recommend applying for OBA status. Notability Notability requires a business to represent a well-known, often searched brand or entity. This should not be taken as a signal of the authenticity of the business. Notability, on the other hand, reflects substantial presence in online news articles. Notability is assessed based on an account’s presence in news articles from publications with sizable audiences. We do not consider paid or promotional content as sources for review, including business or app listings. OBA Number status is issued at the business phone number and display name level. We assess notability for the display name of the business phone number that is requesting OBA status. If the display name is changed after receiving OBA Number status, we will need to re-assess the new display name for notability and display name compliance⁠. Additionally, previous OBA status approvals for other business phone numbers owned by a given Whatsapp Business Account do not guarantee approval for all business phone numbers owned by the WABA. If the WABA contains one main parent brand and the phone number associated with that brand meets notability requirements, we suggest updating the display names for the child brands as follows: {{sub-brand name}} by {{notable name}} Denied Requests If your request has been denied, it means our team has carefully reviewed your account and determined that it is not eligible for OBA Number status at that time. Currently, these decisions cannot be appealed. You can continue to grow their business presence and wait 30 days before submitting another request. In the meantime, this decision does not limit your ability to share your business details. Each business phone number also has a business profile which includes the profile picture, email, website, and business description. These are fields that you can edit at any time. Requesting OBA status via WhatsApp Manager Access WhatsApp Manager⁠ > Overview, and click the business phone number: Enable two-step verification if it isn’t enabled already. Click on the Submit Request button and fill out the form. You can submit up to 5 supporting links especially from renowned publications (e.g., India Today, Economic times, Wall Street Journal, Reuters, Wikipedia, Business Insider) to show that the business is notable, which helps us determine notability.Fields like Country(s) of operation, parent business or brand (esp. if it is a well known brand) and Primary language helps us to further understand your brand and eligibility for OBA. Payments Payments API — India | Developer Documentation Payments API — IndiaUpdated: Nov 26, 2025The Payments API enables you to accept payments from your customers through all UPI apps installed on their devices and other payment methods like cards, NetBanking, and wallets via WhatsApp.You can send invoice ( order_details) messages to your customers, then get notified about payment status updates through webhook notifications from the payment gateway. Know the differences in the models of integrationThe integration model you use depends on your payment gateway. The two models differ in the following ways: UPI Intent Mode: This mode can be used with any Payment Gateway provided they support UPI Intent generation.Payment Gateway Deep Integration Mode: Currently supported for Razorpay, PayU, Billdesk and Zaakpay only. User Experience UPI Intent Mode Payment Gateway Deep Integration Mode Native support for “Other payment methods”For example: Netbanking, cards, wallets ❌Alternative: Send payment links ✅ Native support for UPI Intent ✅ ✅ Native Payment Status Notification ❌ ✅ Integration Features UPI Intent Mode Payment Gateway Deep Integration Mode Refunds from WhatsApp APIs ❌ ✅ Payment Status from WhatsApp webhooks ❌ ✅ Prerequisites for integration Essential Payments APIs are available at SP/TPAccess to merchant order trigger APIs / CSVs needed to trigger an order. (for example, amount, goods or service details)Access to payment posting APIs needed to close an order (for example, ticket generation APIs to create tickets once payment is received) Full payment gateway deep integration mode Find out payment gateway account owner: This authorizes linking the account to WhatsApp Business Manager. UPI Intent mode Find out VPA IDs, MCC, and PC for your business from the merchant’s payment gateway.Access to payment gateway API docs:UPI Intent S2S callsWebhook configuration for payment status Example use cases and features needed Use case Essential Feature Set Buying TicketsFor example: Metro, bus, event tickets Order Details MessagePayment Status Webhook/APIOrder Status MessageRefund Payment RemindersExample: Bill payments, subscription renewals, insurance renewals Order Details TemplatePayment Status Webhook/APIOrder Status MessageRefund Support In case you run into an issue, reach out to direct support⁠. Make sure to choose the correct case type: “WaBiz: Business Payments API” so you get a faster resolution.Sign up for office hours⁠. Make sure to write down your issues in the form provided Onboarding APIs | Developer Documentation Onboarding APIs Updated: Nov 14, 2025 To receive payments on WhatsApp, you must have a payment configuration linked to the corresponding WhatsApp Business Account. Each payment configuration is associated with a unique name. As part of the order_details message, you can specify the payment configuration to use for a specific checkout. Onboarding APIs allows you to programatically perform certain operations:Get all payment configurations linked to a WhatsApp Business Account.Get a specific payment configuration linked to a WhatsApp Business Account.Create a payment configuration.Regenerate payment gateway OAuth link to link payment configuration to a payment gateway.Remove a payment configuration. Payment Configuration Webhook Businesses receive updates via WhatsApp webhooks when the status of the payment configuration changes. To receive webhook, Businesses must subscribe to “payment_configuration_update” event for their respective application. Webhook contains the following fields: Field Description configuration_name string Required. The name of the payment configuration to be used in the Order Details message. provider_name string Required. Provider name of the payment configuration. Must be one of [“razorpay”, “payu”, “zaakpay”]. provider_mid string Required. Payment gateway account merchant ID. status string Required. Status of the payment configuration. Must be one of [“Active”, “Needs_Connecting”, “Needs_Testing”]. created_timestamp integer Required. Time when payment configuration was created. updated_timestamp integer Required. Time when payment configuration was last updated. Sample Payment Configuration Webhook Errors WhatsApp Payments Terms of Service Acceptance Pending If you see the following error, accept the WhatsApp Payments terms of service using the link provided in the error message before trying again. For all other errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes. Receive UPI Payments Through WhatsApp(Recommended) | Developer Documentation Receive UPI Payments Through WhatsApp(Recommended) Updated: Mar 11, 2026 For businesses working with Billdesk or Zaakpay payment gateways, use the deeper integration with these PGs. Refer to Payment Gateway Integration Guide For businesses working with Razorpay, PayU, or Cashfree payment gateways, use a faster integration path. Refer to Enhanced Payment Links This is the recommended UPI Intent integration. Using the older payment configuration method? See previous docs and plan to migrate to dynamic VPA. Your business can enable customers to pay for their orders using all the UPI Apps installed on their devices via WhatsApp. Businesses can send customers invoice ( order_details) messages, then get notified about payment status updates via webhook notifications from Payment Gateway. Overview Currently, customers browse business catalogs, add products to cart, and send orders in with our set of commerce messaging solutions, which includes Single Product Message, Multi Product Message, and Product Detail Page. With the WhatsApp Payments API, businesses can send customers a bill so the customer can complete their order with all the UPI Apps. How It Works The business must send an order_details message for the consumer to initiate payment. This type of message is a new type of interactive message, which always contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment. An order_details message contains the following fields that are worth noting: upi_intent_link - Fields that will be supplied by your payment gateway and denote where a payment will be sent. reference_id - This is used to track the lifecycle of the order. Payment statuses are published against this ID. This could be order-id or transaction-id used to create the upi-intent at payment gateway. Once the message is sent, the business waits for a payment or transaction status updates directly from Payment Gateway. Upon receiving payment signal for an order, Business should relay this payment signal to consumer through interactive order status ( order_status) message. Updating users about the payment signal is important as this message updates the order details message and order details view for the consumer reflecting the order confirmation from the merchant. This is shown with an example in subsequent sections. Purchase Flow in App In the WhatsApp customer app, the purchase flow has the following steps: Customer sends an order with selected products to the business, or the business identifies the products that the customer has shown interest to purchase. After receiving the order/identifying the product, if a merchant accepts payment methods other than UPI, such as credit cards and payment wallets, then the merchant will send a message to the user to get their preferred payment method for the order. When consumers want to pay using UPI payment method, then merchants should retrieve the UPI payment intent by calling Payment Gateway. Merchant needs to use UPI intent to construct order details messages and send it to the consumer. When the consumer taps the Pay now/continue button, they will be given the option to choose UPI payment Apps - WhatsApp or any other UPI payments apps. Consumers may choose any UPI option to pay for the order. Consumer pays for the order and the payment method is saved for the future and automatically selected for the next payment transaction. Also, one quick note is the order details screen order-status will continue to show “Order pending” until the merchant sends order status interactive message. Once the payment is complete, the business receives a notification from Payment Gateway and the merchant needs to send order status updates to the consumer client notifying consumers about the progress to the order, this will update the order details message CTAs and order details screen - order status description. Integration Steps The steps outlined below assume that the business is about to send order details message to the consumer client. The following sequence diagram demonstrates the typical integration flow for WA Payments API: Step 1: Get UPI Intent from Payment Gateway Once the consumer has expressed their interest to purchase an item using UPI payment method, merchant needs to call payment gateway to create a UPI intent, the following is the sample UPI intent link: upi://pay?pa=abc@psp&pn=ABC&tr=877376394&   am=10.00&cu=INR&mode=00&purpose=00&mc=5399&tn=877376394 Merchant/Partner could send the entire UPI intent as it is in the upi_intent_link type payload. These will be discussed in detail below. Step 2: Assemble the Interactive Object To send an order_details message, businesses must assemble an interactive object of type order_details with the following components: Object Description type object Required. Must be “order_details”. header object Optional. Header content displayed on top of a message. If a header is not provided, the API uses an image of the first available product as the header body object Required. An object with the body of the message. The object contains the following field: text stringRequired if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters footer object Optional. An object with the footer of the message. The object contains the following fields: text stringRequired if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters action object Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name stringRequired. Must be “review_and_pay” parameters objectSee Parameters Object for information Parameters Object Object Description reference_id string Required. Unique identifier for the order or invoice provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The reference_id must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, “BM345A-12”) to ensure reference_id uniqueness. type object Required. The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods beneficiaries array Required for shipped physical-goods. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. It contains the following fields: Beneficiary information isn’t shown to users but is needed for legal and compliance reasons. name stringRequired. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters address_line1 stringRequired. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters address_line2 stringOptional. Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters city stringRequired. Name of the city. state stringRequired. Name of the state. country stringRequired. Must be “India”. postal_code stringRequired. 6-digit zip code of shipping address. currency Required. The currency for this order. Currently the only supported value is INR. total_amount object Required. The total_amount object contains the following fields: offset integerRequired. Must be 100 for INR. value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value. payment_settings object Required. See Payment Settings object for more information. order object Required. See order object for more information. Payment Settings Object You can pass UPI intent as it is or parse the UPI intent parameters and pass them in a json structure. We support both the formats, so following are the two variants of payments settings objects: Payment Settings Object for UPI intent link Object Description type string Required. Must be set to “upi_intent_link” upi_intent_link object Required. An object that describes payment account information: link stringRequired. The UPI intent that is generated from Payment gateway. The UPI intent only supports the following “ &” separated attributes- pa, pn, mc, purpose and tr Example: upi://pay?pa=merchant_vpa&pn=Merchant_Name&mc=merchant_category_code&purpose=purpose_code&tr=pg_generated_id Order Object Object Description status string Required. Only supported value in the order_details message is pending. In an order_status message, status can be: pending, captured, or failed. type string Optional. Only supported value is quick_pay. When this field is passed in we hide the “Review and Pay” button and only show the “Pay Now” button in the order details bubble. items object Required. An object with the list of items for this order, containing the following fields: retailer_id stringOptional. Content ID for an item in the order from your catalog. name stringRequired. The item’s name to be displayed to the user. Cannot exceed 60 characters image objectOptional. Custom image for the item to be displayed to the user. See item image object for information Using this image field will limit the items array to a maximum of 10 items and this cannot be used with retailer_id or catalog_id. amount amount object with value and offset -- refer total amount field aboveRequired. The price per item sale_amount amount objectOptional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount quantity integerRequired. The number of items in this order, this field cannot be decimal, has to be integer. country_of_origin stringRequired if catalog_id is not present. The country of origin of the product importer_name stringRequired if catalog_id is not present. Name of the importer company importer_adress stringRequired if catalog_id is not present. Address of importer company subtotal object Required. The value must be equal to sum of order.amount.value * order.amount.quantity. Refer to total_amount description for explanation of offset and value fields The following fields are part of the subtotal object: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 tax object Required. The tax information for this order which contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters shipping object Optional. The shipping cost of the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount object Optional. The discount for the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount_program_name stringOptional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters catalog_id object Optional. Unique identifier of the Facebook catalog being used by the business. If you do not provide this field, you must provide the following fields inside the items object: country_of_origin, importer_name, and importer_address expiration object Optional. Expiration for that order. Business must define the following fields inside this object: timestamp string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds description string – Text explanation for expiration. Max character limit is 120 characters Item Image Object Object Description link string Required. A link to the image that will be shown to the user. Must be an image/jpeg or image/png and 8-bit, RGB or RGBA. Follows same requirements as image in media By the end, the interactive object should look something like this for a merchant upi intent type catalog-based integration: Step 3: Add Common Message Parameters Once the interactive object is complete, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive. These are parameters common to all message types. Step 4:Make a POST Call to Messages Endpoint Make a POST call to the /[PHONE_NUMBER_ID]/messages endpoint with the JSON object you have assembled. If your message is sent successfully, you get the following response: Errors WhatsApp Payments Terms of Service Acceptance Pending If you see the following error, accept the WhatsApp Payments terms of service using the link provided in the error message before trying again. For all other errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes. Step 5: Consumer Pays for the Order Consumers can pay using WhatsApp payment method or using any UPI supported app that is installed on the device. Step 6: Get Notified About Transaction Status Updates from payment gateway Businesses receive updates to the invoice via payment gateway webhooks, when the status of the user-initiated transaction changes. The unique identifier reference-id passed in order_details message can be used to map the transaction to the consumer invoice or interactive order details message. Please refer to our PG integration guide for the exact payment signals. Cashfree and CCAvenue Step 7: Update order status Upon receiving transaction signals from payment gateway through webhook, the business must update the order status to keep the user up to date. Currently we support the following order status values: Value Description pending User has not successfully paid yet processing User payment authorized, merchant/partner is fulfilling the order, performing service, etc. partially-shipped A portion of the products in the order have been shipped by the merchant shipped All the products in the order have been shipped by the merchant completed The order is completed and no further action is expected from the user or the partner/merchant canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message Typically businesses update the order_status using either the WhatsApp payment status change notifications or their own internal processes. To update order_status, the partner sends a order_status message to the user. The following table describes the returned values: Value Description reference_id The ID provided by the partner in the order_details message status The new order status description Optional text for sharing status related information in order_details. Could be useful while sending cancellation. Max character limit is 120 characters Merchant should always post this order-status message to the consumer after receiving transaction updates for an order. As the order_details message and order details screen experience is tied to to the order status updates. Security Considerations Businesses should comply with local security and regulatory requirements in India. They should not rely solely on the status of the transaction provided in the webhook and must use payment lookup API to retrieve the statuses directly from WhatsApp. Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks. Checklist for Integrated Merchants Ensure that an order_status message is send to consumer informing them about updates to an order after receiving transaction updates for an order. Ensure the merchant is verified and WABA contact is marked with a verified check. Verify the WABA is mapped to appropriate merchant initiated messaging tier(1k, 10k and 100k per day) Merchant should list the customer support information in the profile screen in case the consumer wants to report any issues. Cashfree Payment Gateway Integration Guide | Developer Documentation Cashfree Payment Gateway Integration Guide Updated: Oct 31, 2025 Purpose The purpose of this document is to lay down the payment integration with Cashfree that is required for a merchant or Solution Partner that has setup a chatbot using WhatsApp Business APIs and needs to receive payments from WhatsApp users. This document covers the set of APIs that need to be integrated and how the integration works in tandem with the WhatsApp Business API integration. For additional details regarding Cashfree payment integration, please refer to the Cashfree documentation. Where this fits into the entire flow in terms of integration to the WA P2M product : The following document covers the requests, responses in red in the flow diagram below. Handling Special cases Order Expiry Cashfree allows setting the expiry time for an order in the Create Order API. Use that to set preferred expiry time.Post order expiry, if no webhook was received, do a status check to ensure that the order expired and then cancel the order at WhatsApp to update the user. Handling failed payments The Payment message sent to the user via WhatsApp allows for multiple retries upon failure (ie the Pay button is available until successful payment). However Cashfree requires the reference id (“tr” field in the url received in Order Pay response) to be unique for each payment.So when a failed payment response is received from Cashfree, update the status of order at WhatsApp to cancelled. Post that a new payment message can be sent to the user to retry the payment.In case, there is a delay in cancellation and the user ends up making a successful payment, Cashfree will not send a webhook to the merchant but does an auto-refund, without any additional action required by the merchant. In the case of a customer query in such a scenario (where they claim the transaction was successful but the payment cannot be found at Cashfree), suggest to the user that refund will be processed in a few days. Canceling Order for successful transaction There may arise a scenario where Cashfree shared a successful payment signal but the order cannot be fulfilled by the merchant. In such scenario, process refund for the payment via one of the following mechanisms: Use Refund API.Use Cashfree dashboard for merchants. Billdesk Payment Gateway Integration Guide | Developer Documentation Billdesk Payment Gateway Integration Guide Updated: Nov 14, 2025 The purpose of this document is to lay down the payment integration with Billdesk that is required for a merchant, or a Solution Partner, that has implemented a chatbot using WhatsApp Business APIs and needs to accept payments from WhatsApp users. This document outlines the necessary APIs that must be integrated and how the integration works in conjunction with the WhatsApp Business API integration. While not a comprehensive guide, it serves as a general overview to assist in understanding the payment gateway integration process. Any specific or unique details related to the payment gateway must be determined by the merchant or Solution Partner. In terms of integrating with the WA P2M product, this document covers the requests and responses highlighted in red in the flow diagram. Billdesk payment integration Setup To authenticate with Billdesk's API, a client must be created and an authentication method must be selected between HMAC and Javascript Object Signing and Encryption (JOSE) with JOSE being the preferred method. These methods are used to encrypt/decrypt the request/response from Billdesk's APIs. To simplify the explanation, the following examples will only address the body of final payload that will ultimately be included in the final object required for successful authentication with their API. It is important to consult Billdesk's documentation for guidance on how this final object must be structured. You must have the following details before you can proceed: Client ID and secret key from BilldeskDetails from the payment configuration you already configured on the WhatsApp Business Account Merchant category codeMerchant's VPAMerchant Name Parse the response Use the value of wa_txnid on the response and pass it as the reference_id while setting up the parameters object to send for the order details message using the API. Make sure to verify the values in the intent you receive: The intent key has the base64 encoded value of the intentDecoding the intent should give a value that should be similar to this: upi://pay?pa=billdesk@hdfcbank&pn=SIDDHIVINKamp;mc=6300&tr=XHD50477676443&tn=Pay&am=2.00&malORSThe value of pa is the merchant VPA. This value must match the VPA on the payment_configuration you send in the parameters object Status webhook Billdesk will post a transaction object to the return URL ( ru) you specified in the initiate payment API. Key Data type Description objectid (Mandatory) string String representing the object's type. This value will be fixed as transaction transactionid string Unique transaction ID generation by BillDesk for the transaction orderid string Unique orderid generated by merchant to for the transaction mercid string Unique identifier as defined by BillDesk for each merchant transaction_date timestamp BillDesk transaction date and time in YYYY-MM DDThh:mm:ssTZD format amount string Transaction amount in two decimals surcharge string Customer surcharge in two decimals applied to the transaction amount, if any discount string Customer discount in two decimals applied to the transaction amount, if any charge_amount string Total charge to the customer currency integer ISO currency of the transaction amount txn_process_type string Indicates transaction processing type. Intent for payment_method_type is upi and the method of payment is UPI intent bankid string BillDesk defined unique identifier for bank or acquirer txn_process_type string Indicates transaction processing type. Intent for payment_method_type is upi and the method of payment is UPI intent. ru string Merchant return url additional_info object Array of 10 additional_info values that can be attached to the transaction. Note: Merchant is advised to not pass customer PII information in additional info fields. itemcode string Itemcode value provided by BillDesk, with a default value of DIRECT bank_ref_no string Transaction reference number generated by bank or acquirer auth_status string Represents the authorization status of the transaction with the possible values: 0300 - transaction is successful 0002 - transaction is pending for authorization 0399 - transaction failed settlement_lob string Settlement line of business pre-configured by BillDesk for funds settlement to merchant account customer object Customer object device object Device object transaction_error_code string Represents the error code for a transaction with 0399 status transaction_error_type string Represents the standard error category for a transaction with 0399 status transaction_error_desc string Represents the description of the error code for a transaction with 0399 status authcode string Authorization code received from the acquirer for a successfully authorized card transaction eci string eci value for the authentication taken for the card transaction payment_method_type string Represents the method of payment e.g. upi card Object Payment method object (applicable when payment method is card) customer_refid string Unique customer identifier as per merchant links object Associated links with the object Parsing the response Use the auth_status retrieved from the response above and transmit the corresponding status message via the WhatsApp API. CCAvenue Payment Gateway Integration Guide | Developer Documentation CCAvenue Payment Gateway Integration Guide Updated: Dec 10, 2025 The purpose of this document is to lay down the payment integration with CCAvenue that is required for a merchant (or BSP) that has implemented a chatbot using WhatsApp Business APIs and needs to accept payments from WhatsApp users. This document outlines the necessary APIs that must be integrated and how the integration works in conjunction with the WhatsApp Business API integration. While not a comprehensive guide, it serves as a general overview to assist in understanding the payment gateway integration process. Any specific or unique details related to the payment gateway must be determined by the merchant (or BSP). In terms of integrating with the WA P2M product, this document covers the requests and responses highlighted in red within the flow diagram. Accept Payments via Payment Links | Developer Documentation Accept Payments via Payment Links Updated: Nov 14, 2025 This feature is not publicly available yet. Please reach out to whatsappindia-bizpayments-support@meta.com to know more. Your businesses can enable customers to pay for their orders by bringing in all the payment methods supported on your platform to WhatsApp. Businesses can send customers invoice( order_details) messages, then get notified about payment status updates via webhook notifications from Payment Gateway. Overview Currently, customers browse business catalogs, add products to cart, and send orders in with our set of commerce messaging solutions, which includes Single Product Message, Multi Product Message, and Product Detail Page. With the WhatsApp Messaging API, businesses can send customers a bill to complete the order with one of the supported payment instrument. How It Works The business must send an order_details message for the consumer to initiate payment. This type of message is a new type of interactive message, which always contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment. Each order_details message contains a unique reference_id provided by the business, and that unique number is used throughout the flow to track the order. This reference_id is used to generate the payment link from Payment Gateway. Once the message is sent, the business waits for a payment or transaction status updates directly from Payment Gateway. Upon receiving payment signal for an order, business should relay this payment signal to consumer client through interactive order status( order_status) message. Updating user about the payment signal is important as this message updates the order details message and order details view for the consumer reflecting the order confirmation from merchant. This is shown with an example in subsequent sections. Purchase Flow in App In the WhatsApp customer app, the purchase flow has the following steps: Customer sends an order with selected products to the business or business identifies the products that the customer has shown interest to purchase. After receiving the order or identifying the product, if a business accepts payment methods other than UPI, such as credit cards and payment wallets, etc. then business will send a message to the user to get their preferred payment method for the order. When consumers want to pay using other payment method option, the business should generate the payment link by calling Payment Gateway by providing the unique “reference-id” and other information like amount, validity etc, then business can use the generated payment link to construct the order details message and send to the consumer. When the consumer taps the Pay now/continue button, consumer will be redirected to the payment link within specially designed In-App browser to present with the list of supported payment options such as credit card, debit card, wallet or UPI apps. Consumers can choose any one of the payment option to pay for the order. The following is a sample payment link redirect within In-App Browser accepting various payment methods like credit, debit, wallet and UPI apps. Once the payment is complete, the business will receive a notification from Payment Gateway and the business needs to send order status updates to the consumer client notifying consumers about the progress on their order, this will update the order details message CTAs, Order details screen and Order status. The order status should contain the matching “reference-id” of order details. Integration Steps The steps outlined below assume that the business is about to send order details message to consumer client. The following sequence diagram demonstrates the typical integration flow for WA Payments API: Step 1: Get Payment Link from Payment Gateway Once the consumer has expressed their interest to purchase an item using payment link. Business needs to call payment gateway with necessary information like reference-id, amount and validity to generate the payment link. Following is a sample payment link: https://rzp.io/i/rNiAagU8y Business needs to use the same reference-id, amount and expiration in invoice( order_details) interactive message. Step 2: Assemble the Interactive Object To send an order_details message, businesses must assemble an interactive object of type order_details with the following components: Object Description type object Required. Must be “order_details”. header object Optional. Header content displayed on top of a message. If a header is not provided, the API uses an image of the first available product as the header body object Required. An object with the body of the message. The object contains the following field: text stringRequired if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters footer object Optional. An object with the footer of the message. The object contains the following fields: text stringRequired if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters action object Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name stringRequired. Must be “review_and_pay” parameters objectSee Parameters Object for information Parameters Object Object Description reference_id string Required. Unique identifier for the order or invoice provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The reference_id must be unique for each order_details message for the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id (for example, -) to ensure reference_id uniqueness. type object Required. The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods beneficiaries array Required for shipped physical-goods. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. It contains the following fields: Beneficiary information isn’t shown to users but is needed for legal and compliance reasons. name stringRequired. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters address_line1 stringRequired. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters address_line2 stringOptional. Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters city stringRequired. Name of the city. state stringRequired. Name of the state. country stringRequired. Must be “India”. postal_code stringRequired. 6-digit zipcode of shipping address. payment_type Required. Must be “upi”. payment_settings Required. See Payment Settings Object for more details. currency Required. The currency for this order. Currently the only supported value is INR. total_amount object Required. The total_amount object contains the following fields: offset integerRequired. Must be 100 for INR. value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value. order object Required. See order object for more information. Payment Setting Object Object Description type string Required. Must be payment_link. payment_link object Required. Refer Payment Link Object for more information. Payment Link Object Object Description uri string Required. A valid payment link generated through payment gateway. Generated payment links domains needs to be enabled to accept payments. Please reach out to whatsappindia-bizpayments-support@meta.com to know more. success_url string Optional. The flow terminated with success status, when success_url is hit. cancel_url string Optional. The flow ends with failure, when the cancel_url is triggered. Order Object Object Description status string Required. Only supported value in the order_details message is pending. In an order_status message, status can be: pending, captured, or failed. type string Optional. Only supported value is quick_pay. When this field is passed in we hide the “Review and Pay” button and only show the “Pay Now” button in the order details bubble. items object Required. An object with the list of items for this order, containing the following fields: retailer_id stringOptional. Content ID for an item in the order from your catalog. name stringRequired. The item’s name to be displayed to the user. Cannot exceed 60 characters image objectOptional. Custom image for the item to be displayed to the user. See item image object for information Using this image field will limit the items array to a maximum of 10 items and this cannot be used with retailer_id or catalog_id. amount amount object with value and offset -- refer total amount field aboveRequired. The price per item sale_amount amount objectOptional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount quantity integerRequired. The number of items in this order, this field cannot be decimal has to be integer. country_of_origin stringRequired if catalog_id is not present. The country of origin of the product importer_name stringRequired if catalog_id is not present. Name of the importer company importer_adress stringRequired if catalog_id is not present. Address of importer company subtotal object Required. The value must be equal to sum of order.amount.value * order.amount.quantity. Refer to total_amount description for explanation of offset and value fields The following fields are part of the subtotal object: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 tax object Required. The tax information for this order which contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters shipping object Optional. The shipping cost of the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount object Optional. The discount for the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount_program_name stringOptional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters catalog_id object Optional. Unique identifier of the Facebook catalog being used by the business. If you do not provide this field, you must provide the following fields inside the items object: country_of_origin, importer_name, and importer_address expiration object Optional. Expiration for that order. Business must define the following fields inside this object: timestamp string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds description string – Text explanation for expiration. Max character limit is 120 characters Item Image Object Object Description link string Required. A link to the image that will be shown to the user. Must be an image/jpeg or image/png and 8-bit, RGB or RGBA. Follows same requirements as image in media The parameters value is a stringified JSON object. By the end, the interactive object should look something like this for a catalog-based integration: The parameters value is a stringified JSON object. For a non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows: Step 3: Add Common Message Parameters Once the interactive object is complete, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive. These are parameters common to all message types. Step 4:Make a POST Call to Messages Endpoint Make a POST call to the /[PHONE_NUMBER_ID]/messages endpoint with the JSON object you have assembled. If your message is sent successfully, you get the following response: Errors WhatsApp Payments Terms of Service Acceptance Pending If you see the following error, accept the WhatsApp Payments terms of service using the link provided in the error message before trying again. For all other errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes. Step 5: Consumer Pays for the Order Consumers can pay using WhatsApp payment method or using any UPI supported app that is installed on the device. Step 6: Get Notified About Transaction Status Updates from payment gateway Businesses receive updates to the invoice via payment gateway webhooks, when the status of the user-initiated transaction changes. The unique identifier reference-id passed in order_details message can be used to map the transaction to the consumer invoice or interactive order details message. Step 7: Update order status Upon receiving transaction signals from payment gateway through webhook, the business must update the order status to keep the user up to date. Currently we support the following order status values: Value Description pending User has not successfully paid yet processing User payment authorized, merchant/partner is fulfilling the order, performing service, etc. partially-shipped A portion of the products in the order have been shipped by the merchant shipped All the products in the order have been shipped by the merchant completed The order is completed and no further action is expected from the user or the partner/merchant canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message Typically businesses update the order_status using either the WhatsApp payment status change notifications or their own internal processes. To update order_status, the partner sends an order_status message to the user. The following table describes the returned values: Value Description reference_id The ID provided by the partner in the order_details message status The new order status description Optional text for sharing status related information in order_details. Could be useful while sending cancellation. Max character limit is 120 characters Merchant should always post this order-status message to consumer after receiving transaction updates for an order. As the order_details message and order details screen experience is tied to to the order status updates. Step 8: Reconcile Payments Businesses should use their bank statements to reconcile the payments using the reference_id provided in the order_details messages. Checklist for Integrated Merchants Ensure that order_status message is send to consumer informing them about updates to an order after receiving transaction updates for an order. Ensure the merchant is verified and WABA contact is marked with a verified check. Verify the WABA is mapped to appropriate merchant initiated messaging tier(1k, 10k and 100k per day) Merchant should list the customer support information in the profile screen incase consumer wants to report any issues. Enhanced Payment Links | Developer Documentation Enhanced Payment Links Updated: Dec 12, 2025 Overview Enhanced Payment Links is a feature that transforms existing payment gateway URLs into rich, native payment experiences within WhatsApp. It converts existing payment links into an in-app checkout flow - no changes to your payment backend, reconciliation, or callback setup are required. When a supported payment link is sent through a message template, it automatically renders as a structured payment bubble featuring: Amount and currency clearly displayed“Pay Now” CTA for seamless checkoutIn-app checkout via UPI Intent or hosted payment page This feature significantly improves payment conversion rates by reducing checkout friction and increasing consumer trust. Superfast Setup: Merchants can independently create the required WhatsApp templates and embed payment links from supported payment gateways - no BSP involvement is needed. This feature is not publicly available yet. To request access, please reach out to your BSP or Meta representative with your WABA ID, sample payment link, and preferred Payment Gateway (Razorpay, PayU, or Cashfree). User Experience On supported WhatsApp versions, the payment link renders as an enhanced bubble: Rich Payment Card: Displays Amount, currency, and CTA buttonIn-App Checkout: UPI: Direct app-switch to UPI apps (Google Pay, PhonePe, Paytm, etc.)Other methods: In-app browser for cards, net banking, or walletsAutomatic Status Updates: The payment card automatically updates to reflect the payment status on completion or expiry, and disables the “Pay Now” button to prevent duplicate payments. Prerequisites Enhanced Payment Links is an experience that works with both existing BSP APIs and WhatsApp Business Cloud API. Neither BSPs nor merchants need to make any backend, API, reconciliation, or callback changes to enable this feature. Your existing payment gateway integration remains completely unchanged. To use Enhanced Payment Links: Requirement Description Allowlisted WABA Your WABA ID must be enabled for Enhanced Payment Links. Submit a request to your BSP or Meta representative with your WABA ID, preferred payment gateway(s), and sample payment links for validation. Supported Payment Gateway An active account with Razorpay, PayU, or Cashfree Compliant Template A message template configured with no header and a dynamic URL button (see Template Requirements) Supported Payment Gateways Payment Gateway Status Razorpay ✅ Supported PayU ✅ Supported Cashfree ✅ Supported Integration Flow The following diagram illustrates the end-to-end flow, from sending an Enhanced Payment Link to payment completion and callbacks: Steps: Generate payment link - Your server calls the payment gateway API (Razorpay, PayU, or Cashfree) to create a payment link for the transaction.Receive payment link URL - The payment gateway returns a URL (for example, https://rzp.io/i/abc123XYZ).Send template message - Your server sends a template message via the Cloud API or your BSP, embedding the dynamic portion of the payment link (the suffix) in the button component.Message delivered on WhatsApp - The consumer receives an enhanced payment bubble with the amount, currency, and a “Pay Now” button for in-app checkout.Consumer completes payment - The consumer taps “Pay Now” and pays via UPI apps, cards, net banking, or wallets within WhatsApp.Payment gateway sends callback to merchant - Your existing webhook endpoint receives the payment status callback with the same payload format as before. No changes to your webhook URL, payload handling, or reconciliation logic are needed.WhatsApp updates the payment card - The payment card automatically reflects the payment status (success, or expiry) and disables the “Pay Now” button to prevent duplicate payments. This happens independently and requires no merchant action. Template Requirements Enhanced Payment Link templates must follow these constraints: Component Requirement Header None — templates must not include a media header (image, video, or document) Button Exactly one dynamic URL button with a supported PG link prefix Merchants can independently create these templates without involving their BSP. Templates can be created using any one of the following methods: Template Library (recommended)WhatsApp Manager⁠Business Management APIBSP Dashboard Example Template Configuration Your business can enable customers to pay using their favorite UPI apps or other payment methods accepted by supporting Payment Gateways without leaving WhatsApp. Body:"Hi 1, reminder to pay for your insurance renewal #2. Amount: ₹3"Button:-Type of Action:"Visit website"-ButtonText:"Pay Now"- URL Type:Dynamic-Website URL: https://pg.io/i/ Important: The button URL must be configured as dynamic to pass the payment link at send time. Dynamic URL Prefix Configuration When creating your template, the dynamic URL button requires a URL prefix that matches your payment gateway’s domain. Use one of the following prefixes based on your PG: Razorpay URL Prefix https://rzp.io/rzp/ https://rzp.io/i/ PayU URL Prefix https://pmny.in/PAYUMN/ https://api.payu.in/ https://u.payu.in/PAYUMN/ Cashfree URL Prefix https://payments.cashfree.com/links https://payments.cashfree.com/link/ https://cfre.in/CSHFRE/ Note: The URL prefix you configure in your template must match the format of payment links generated by your PG. When sending the message, pass only the dynamic portion (e.g., the link ID) in the button parameter. Payment Link Requirements Requirement Details Environment Must be from production environment (not sandbox/test mode) Status Link must be active and not expired Gateway Must be from a supported PG (see Supported Payment Gateways) URL Format Must match one of the supported URL prefixes for your PG Using wrapped or redirected payment links? Enhanced Payment Links requires direct payment gateway URLs that match the supported URL prefixes. If your implementation wraps payment gateway links under your own domain (e.g., yourdomain.com/pay/...) or redirects to the payment gateway from a hosted page, the enhanced experience will not render automatically. In such cases, you will need to update your workflow to pass the direct payment gateway link in the template button instead of your wrapped or redirected URL. Generating Payment Links Refer to your payment gateway’s documentation: Razorpay: Create Payment Link (API)⁠Dashboard⁠PayU: Payment Links⁠Cashfree: Payment Links⁠ Payment Reconciliation and Callbacks Enhanced Payment Links does not modify your existing payment processing or backend infrastructure. This means: Aspect Impact Payment callbacks/webhooks No change. Your existing webhook endpoints and callback flows from your payment gateway continue to work as-is. Reconciliation No change. Reconciliation remains the same as configured on your payment gateway (Razorpay, PayU, or Cashfree). Settlement No change. Settlement flows and timelines are unaffected. No backend integration changes are required to adopt Enhanced Payment Links. Reporting Reporting for Enhanced Payment Links is split across two sources: Metric Source Details Link clicks WhatsApp Click metrics on payment gateway links are available from WhatsApp analytics. Payment status, success/failure rates, refunds, settlements Payment gateway All payment-level reporting remains on your payment gateway (Razorpay, PayU, or Cashfree). Use your existing dashboards and reports. No additional reporting setup is required. WhatsApp provides visibility into link engagement, while your payment gateway continues to be the source of truth for all payment and transaction metrics. Best Practices Practice Details Use production links Sandbox/test links will not render enhanced bubbles Set reasonable expiry 24-48 hours balances conversion and security Include context Add amount and order details in the message body One button only Multiple buttons are not supported Match URL prefix Ensure template URL prefix matches your PG’s link format Limitations Only one payment link per template messageNo header components allowedSingle button requiredEnhanced rendering depends on recipient’s WhatsApp versionCurrently available for India onlyPayment metrics behavior: Enhanced Payment Links create a UPI intent on every “Pay now” tap. This means: Total payment attempt counts will be higher than pre-EPLExpired intents are reported as failures, which may inflate failure rates (eg: Razorpay webhooks for expired UPI intents: “Payment was unsuccessful as you could not complete it in time”)Recommendation: Exclude payment expiry errors when calculating your success metrics. Troubleshooting Payment link not rendering as enhanced bubble Check Action WABA allowlisted? Confirm with your BSP or Meta representative Supported PG? Must be Razorpay, PayU, or Cashfree URL prefix correct? Template URL prefix must match your PG’s supported formats Link active? Verify link hasn’t expired Template compliant? No header, single dynamic URL button Note: If your template gets miscategorized, you can appeal the assigned category. See the Template Categorization Guide for details on the appeal process. To avoid categorization uncertainty altogether, consider using a Utility Template from the template library, this ensures correct categorization and provides guidance on template content structure. Getting Help Direct API users or Meta Managed Businesses: Contact your Meta representativeBSP partners: Reach out to your BSP for integration supportPayment gateway issues: Consult your PG’s documentation or support team See also: Message Templates, Cloud API Messages, Payments Overview Send order details template message | Developer Documentation Send order details template message Updated: Oct 31, 2025 Overview Order details message template is a template with interactive components that extends the call-to-action button to support sending order details and provides a richer experience compared to templates with only text components. Once your Order details message templates have been created and approved, you can use the approved template to send the template message with order or bill information to prompt them to make a payment. Before sending an order details template message, businesses need to create a template with an “open order details” call-to-action button. See Create Message Templates for Your WhatsApp Business Account⁠ for more information on prerequisites and how to create a template. Creating an order details template on WhatsApp Manager To create an order details template, business needs a business portfolio with a WhatsApp Business Account. In WhatsApp Manager > Account tools:Click on create templateSelect Utility category to expand Order details message optionEnter the desired template name and supported locale Depending on the number of locales selected there will be an equal number of template variants and businesses need to fill in the template details in respective locale.Please fill in template components such as Header, Body and optional footer text and submit.Once submitted, templates will be categorized as per the guidelines and undergo the approval process refrain from having marketing content as part of template components.The template will be approved or rejected after the template components are verified by the system. If business believe the category determined is not consistent with our template category guidelines, please confirm there are no common issues that leads to rejections and if you are looking for further clarification you may request a review of the template via Business Support⁠Once approved template status will be changed to ACTIVE Please be informed that template’s status can change automatically from ACTIVE to PAUSED or DISABLED based on customer feedback and engagement. We recommend that you monitor status changes and take appropriate actions whenever such change occurs. Sending order details template message Order details template message allows the businesses to send invoice(order_details) message as predefined Open order details call-to-action button component parameters. It supports businesses to send all payment integration (such as UPI Intent, Payment Gateway or Payment Links) integration as button parameters. To send an order details template message, make a POST call to /PHONE_NUMBER_ID/messages endpoint and attach a message object with type=template. Then, add a template object with a predefined Open order details call-to-action button. For example following sample describes how to send UPI Intent in order details template message parameters to prompt the consumer to make a payment. The below example shows an example payload with upi as the payment type. For other variants of the payment_settings block (for example, for the type payment_gateway type), refer to this document. Once the order details template message is delivered, a successful response will include an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status. Post order details template message flow After the order details template message delivery the rest of the payment flow is the same as “Sending invoice in customer session window” and depends on the chosen payment integration order details parameters. For more details refer UPI Intent, Payment Gateway and Payment Links post payments flows. Send order status template message | Developer Documentation Send order status template message Updated: Nov 14, 2025 Overview An Order status template is a template with interactive components that extends the call-to-action button to support updating order status through a template. It allows the businesses to update the order status outside of the customer session window in use cases such as charging the card for past order and updating about a shipment on order placed in the past. Upon receiving the payment signals, the businesses must update the order status to keep the user up to date. Currently we support the following order status values Value Description pending User has not successfully paid yet processing User payment authorized, merchant/partner is fulfilling the order, performing service, etc. partially-shipped A portion of the products in the order have been shipped by the merchant shipped All the products in the order have been shipped by the merchant completed The order is completed and no further action is expected from the user or the partner/merchant canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message Creating an order status template To create an order status template, the business needs a business portfolio with a WhatsApp Business Account, and access to the WhatsApp Manager. In WhatsApp Manager > Account tools:Click on create templateSelect Utility category to expand Order details message optionEnter the desired template name and supported locale Depending on the number of locales selected there will be an equal number of template variants and businesses need to fill in the template details in respective locale.Please fill in template components such as Body and optional footer text and submit.Once submitted, templates will be categorized as per the guidelines and undergo the approval process refrain from having marketing content as part of template components.The template will be approved or rejected after the template components are verified by the system. If business believe the category determined is not consistent with our template category guidelines, please confirm there are no common issues that leads to rejections and if you are looking for further clarification you may request a review of the template via Business Support?Once approved template status will be changed to ACTIVE Please be informed that template's status can change automatically from ACTIVE to PAUSED or DISABLED based on customer feedback and engagement. We recommend that you monitor status changes and take appropriate actions whenever such change occurs. Sending order status template message Order status template message allows the businesses to send update on the status of the order as template component parameters. To send an order status template message, make a POST call to //messages endpoint and attach a message object with type=template. Then, add a template object with a order_status component and parameters with latest status on order with order reference-id. For example, the following sample describes how to send shipped status on the placed order. Upon sending an order_status message with an invalid transition, you will receive an error webhook with the error code 2046 and message New order status was not correctly transitioned. Canceling an order An order can be canceled by sending an order_status message with the status canceled. The customer cannot pay for an order that is canceled. The customer receives an order_status message and the order details page is updated to show that the order is canceled and the Continue button removed. The optional text shown below Order canceled on the order details page can be specified using the description field in the order_status message. An order can be canceled only if the user has not already paid for the order. If the user has paid and the business sends a order_status message with canceled status will receive an error webhook with error code 2047 and message Could not change order status to 'canceled'. Checkout button templates | Developer Documentation Checkout button templates Updated: Dec 12, 2025 Checkout button templates are marketing templates that can showcase one or more products along with corresponding checkout buttons that WhatsApp users can use to make purchases without leaving the WhatsApp client. Single products Checkout button templates can show a single product image or video header, along with message body text, message footer, a single checkout button, and up to 9 quick-reply buttons. WhatsApp users who tap the button will see details of the order: Users can proceed by selecting shipping information provided by you (if you know their information and supplied it in the send message payload)... ... or can add their own shipping information: Enabling coupons, realtime inventory, and pricing updates Enabling coupons, realtime inventory and pricing updates is currently in beta and only available to India businesses and WhatsApp users with an India country calling code. Please reach out to whatsappindia-bizpayments-support@meta.com to know more. To enable coupons, realtime inventory and pricing updates, you can set up a checkout endpoint that can exchange data in real time to update the order on the WhatsApp client. It enables businesses to receive the shipping address and offers coupons based on the order and allows users to apply the coupon. It also enables businesses to validate inventory and serviceability on the order before the user completes the checkout. Setting up the checkout endpoint consists of the following steps and it's the same method that WhatsApp Flows endpoint uses to share the data with WhatsApp clients.Create a key pair and upload and sign the public key using the Cloud API.Setup the endpointImplement Payload Encryption/DecryptionLink the checkout endpoint with payment configurationImplement checkout endpoint logic Set up the endpoint WhatsApp client makes a HTTPS request to exchange the data with the business endpoint. You should make sure the endpoint is configured probably to accept the request and link the endpoint url with the payment configuration: https://business.com/checkout Your server must be enabled to receive and process POST requests, use HTTPS and have a valid TLS/SSL certificate installed. This certificate does not have to be used in payload encryption/decryption. Implement Encryption/Decryption The body of each request contains the encrypted payload and has the following form: Sample endpoint request syntax {   encrypted_flow_data: "",   encrypted_aes_key: "",   initial_vector: "" } Parameter Description encrypted_flow_data string Required. The encrypted request payload. encrypted_aes_key string Required. The encrypted 128-bit AES key. initial_vector string Required. The 128-bit initialization vector. After processing the decrypted request, create a response and encrypt it before sending it back to the WhatsApp client. Encrypt the payload using the AES key received in the request and send it back as a Base64 string. You can refer to examples of how to decrypt and encrypt. If a request can not be decrypted, the endpoint should return HTTP 421 response status code (see Business Endpoint Error Codes for more details). Link the checkout endpoint with payment configuration The business should have payment gateway based payment configuration and reach out to whatsappindia-bizpayments-support@meta.com to enable the WhatsApp business account for checkout endpoint linking with with payment configuration. Prior to linking the checkout endpoint, you should create a payment configuration and link with the payment gateway account. We advise you to use the linked payment configuration only with checkout button template integration. You can achieve the endpoint linking with payment configuration by following Onboarding API's - Link data endpoint Implement checkout endpoint logic WhatsApp checkout endpoint integration inherits the 'data_exchange' similar to Flows and supports a set of subactions based on the user interaction and passes the relevant information in each of these actions to allow businesses to provide user specific coupons and enable businesses to update the pricing information accordingly. Sub Action Method Description get_coupons Request When users click on a savings offer CTA, WhatsApp passes order parameters excluding the payment settings. It also passes the user phone number as an input parameter. Refer get coupons request example to understand the order and input parameters Response Checkout endpoint expected to pass the list of coupon information, such as code, id and description. Refer get coupons response example to understand the expected response. apply_coupon Request When users select or enter a coupon, WhatsApp passes order parameters excluding the payment settings. It also passes the user phone number and information about the coupon to be applied as an input parameter. Refer apply coupon request example to understand the order and input parameters Response Checkout endpoint expected to update the item and order pricing in order parameters and attach the coupon with the order Refer to apply coupon response example to understand the expected response. remove_coupon Request When users try to remove an applied coupon, WhatsApp passes order parameters excluding the payment settings. It also passes the user phone number as an input parameter. Refer remove coupon request example to understand the expected response. Response Checkout endpoint expected to update the item and order pricing in order parameters and remove the coupon attached with the order. Refer remove coupon response example to understand the expected response. apply_shipping Request When users try to submit a shipping address, WhatsApp passes order parameters excluding the payment settings. It also passes the user phone number and shipping information as an input parameter. Refer to the apply shipping request example to understand the expected response. Response Checkout endpoint expected to update the item and shipping pricing in order parameters. Refer to the apply shipping response example to understand the expected response. We have created a checkout endpoint example? in Node.js that you can clone (remix) on Glitch to create your own endpoint and quickly prototype your checkout logic. Follow the instructions in the README.md? file to get started. Using Glitch is entirely optional. You can clone the example code from Glitch and run it in any environment you prefer. Upon completing the above steps, when business sends the checkout template with the linked payment configuration, WhatsApp enables the coupons, realtime inventory and pricing updates and allows users to apply coupons and share shipping addresses. When enabled the Apply a savings offer will appear in the order summary screen User can click on Apply a savings offer to explore the coupons, at this point WhatsApp makes get_coupons request to fetch the list coupons based on the passed order and user phone number information. When the user tries to apply a coupon, WhatsApp makes apply_coupon and allow businesses to update the order or item pricing based on the selected coupon. Similar to coupons, user can share the shipping address by clicking on Add shipping address and select the addresses saved with the businesses or add new address. WhatsApp makes apply_shipping request when user tries to submit the address and allow businesses to check inventory and logistics based on the address provided. Users can then continue to place the order using their preferred payment method set up in the WhatsApp client: Once the order is processed, a payment webhook is triggered. Multiple products You can create a media card carousel template that showcases up to 10 products in a card carousel, each with their own checkout button. To do this, simply create a media card carousel template as you normally would, but replace one of the buttons with a checkout button, and make sure that it is the first button in the card. Checkout buttons in media card carousel templates trigger the same order and payment flow as checkout buttons in templates that showcase a single product. Checkout buttons Each checkout button in a template must correspond to a single product. Checkout buttons, when creating a template, must have the following non-customizable syntax: Note that this is simply a button definition. The actual details about the product that maps to this button are included when you send the template in a template message. For example: If you are sending a media card carousel template (which can have two or more products), each checkout button must be defined in the template, and the item details that map to each button must be included when sending the template. Send a checkout button template Once your checkout button template or carousel template has been approved, you can send it in a template message. Post body This post body syntax is for a checkout button template. See Sending Media Card Carousel Templates for media card carousel template post body payload syntax. Post body parameters Placeholder Description Example Value Integer Required if using a discount. Discount amount, multiplied by discount.offset value. For example, to represent a discount of ?2, the value would be 200. Discount amount applies to the order subtotal. 15000 String Optional. Discount description. Maximum 60 characters. Additional 10% off String Required if using an order expiration. UTC timestamp indicating when we should disable the Buy now button. The timestamp will be used to generate a text string that appears at the bottom of the Order details window. For example: This order expires on September 30, 2024 at 12:00 PM. WhatsApp users who view the message after this time will be unable to purchase the item using the checkout button. Values must represent a UTC time at least 300 seconds from when the send message request is sent to us. 1726692927 String Required. Importer address, line 1 (door, tower, number, street, etc.). Maximum 100 characters. One BKC String Optional. Importer address, line 2 (landmark, area, etc.). Maximum 100 characters. Bandra Kurla Complex String Required. Importer city. Maximum 120 characters. Mumbai String Required. Importer name. Maximum 200 characters. Lucky Shrub Imports and Exports String Required. Importer 6-digit postal index number. Maximum 6 digits. 400051 String Required. Importer two-letter zone code. MH String Required. Item's country of origin. Maximum 100 characters. India String Required. Item name. Maximum 60 characters. Blue Elf Aloe Integer Required. Individual item price (price per item), multiplied by amount.offset value. For example, to represent an item price of ?12.99, the value would be 1299. 200000 Integer Required. Number of items in order, if order is placed. Maximum 100 integers. 1 Object Required if template message body text uses variables, otherwise omit. Object describing a message variable. If the template uses multiple variables, you must define an object for each variable. Supports text, currency, and date_time types. See Messages Parameters. There is no maximum character limit on this value, but it does count against the message body text limit of 1024 characters. String Required. 1558081531584829 String Required. Indicates header type and a matching property name. Note that the placeholder appears twice in the post body example above, as it serves as a placeholder for the type property's value and its matching property name. Value can be image or video. image String Required. Configuration name of payment gateway you have configured on your WhatsApp Business Account. prod-razor-pay-config-05 String Required. Name of payment gateway you have configured on your WhatsApp Business Account. Values can be: razorpay payu zaakpay razorpay String Required. Product type. Value can be digital-goods or physical-goods. digital-goods String Optional. Value to be included in messages webhooks ( messages.button.payload) when the button is tapped. opt-out String Required. Your unique order or invoice reference ID. Case-sensitive. Cannot be empty. Will be preceded by a hash (#) symbol in the checkout flow. Value must be unique for each checkout button template message. If sending a carousel template, each checkout button must have a unique reference ID. If you need to send multiple messages for the same order/invoice, it is recommended to append a sequence number to the value (for example, -1). Values can only contain English letters, numbers, underscores, dashes, or dots. Maximum 35 characters. abc.123_xyz-1 Integer Required if using a sale amount. Sale price, multiplied by sale.offset value. For example, to represent a sale price of ?10, the value would be 1000. 150000 Integer Required. Order shipping cost, multiplied by shipping.offset value. For example, to represent a shipping cost of ?.99, the value would be 99. 20000 String Required if you know the recipient's shipping information. Product recipient's address. Maximum 512 characters. Bandra Kurla Complex String Optional. Product recipient's building name. Maximum 128 characters. One BKC String Required if you know the recipient's shipping information. Full name of product recipient's city. Maximum 100 characters. Mumbai String Optional. Product recipient's floor number. Maximum 10 characters. 2 String Optional. Product recipient's house number. Maximum 8 characters. 12 String Required if you know the recipient's shipping information. Product recipient's postal index number. Maximum 6 characters. 400051 String Optional. Product recipient's landmark area. Maximum 128 characters. Near BKC Circle String Required if you know the recipient's shipping information. Product recipient's full name. Maximum 256 characters. Nidhi Tripathi String Required if you know the recipient's shipping information. Product recipient's WhatsApp phone number. Maximum 12 characters. 919000090000 String Required if you know the recipient's shipping information. Full name of product recipient's state. Maximum 100 characters. Maharastra String Optional. Product recipient's tower number. Maximum 8 characters. 2 Integer Required. Order subtotal. Calculate by multiplying by by subtotal.offset. For example, if the template is for placing a single order containing 2 items priced at ?12.99, the value would be 2598. 150000 Integer Required. Tax amount, multiplied by tax.offset. For example, to represent a tax amount of ?5, the value would be 500. 10000 String Optional. Tax description. Maximum 60 characters. Sales tax String Required. Template language and locale code. en_US String Required. Template name. Maximum 512 characters. item_back_in_stock_v1 Integer Required. Total amount of order, multiplied by total_amount.offset value. For example, to represent a total amount of ?18, value be 1800. Must be a sum of: order.subtotal.value order.shipping.value order.tax.value Minus: order.discount.value 165000 String Required. WhatsApp user phone number. +16505551234 Example request The following sample request and responses are only supported with Enabling coupons, realtime inventory and pricing updates feature and it is currently in beta and only available to India businesses and WhatsApp users with an India country calling code. Please reach out to whatsappindia-bizpayments-support@meta.com to know more. Payments API - Brazil | Developer Documentation Payments API - BrazilUpdated: Nov 14, 2025Payments API enable businesses to accept payments from their customers via WhatsApp. Businesses send order_details messages (Orders API) to their customers, then get notified about payment status updates via webhook notifications.Based on the selected use case, businesses can collect payment from the customers using one of the following integrations: Dynamic Pix CodesPayment LinksBoletoOne-click offsite card paymentOrder Details Template How It WorksFirst, the business composes and sends an order_details message, which is a new type of interactive message. It contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment.Each order_details message must contain a unique reference_id provided by the business. This reference id is used throughout the flow to track the order.Once the message is sent, the business waits for a payment or transaction status update. The type of the update depends on the integration type (e.g.: Pix, Payment Links, etc.). WhatsApp does NOT support payment reconciliations. The business must reconcile the payment with their payment service provider (PSP) using the reference_id of the order. Purchase Flow in AppIn the WhatsApp customer app, the purchase flow has the following steps: Buyers communicate with businesses and select a product.Businesses send an order_details message to the buyer.Buyers pay the order. For Pix, they will switch to their bank app and use the Pix Copy and Paste functionality. For Payment Links, the payment/checkout link opens in the web browser, and they complete the payment there.Businesses send an order_status message indicating that the order is now processing. Orders | Developer Documentation Orders Updated: Mar 25, 2026 Payments API introduces two new types of interactive messages: order_details and order_status. They are the entrypoint to collect payment in WhatsApp. order_details messages are sent to create an order in the buyer’s WhatsApp client app. This message includes the payment settings used to collect payment and can optionally include an order object with itemized products, fees, and discounts. Without the order object, you can send a simplified order details message with just the total amount and payment settings. The payment settings will vary depending on the integration type (Pix, payment links, Boleto, One Click Payments). order_status messages are sent when businesses update the order status either based on the WhatsApp payment status change notification or based on their internal processes. You can also send a simplified status update without the order object. When attached to an order details message, orders start in pending status. When the merchant has fully fulfilled the order and the buyer should not expect any further updates, it must be marked as completed. Full API Reference Order Details To send an order_details message, businesses must assemble an interactive object of type order_details with the following components: Interactive Object Field Name Optional? Type Description type Required String Must be order_details. header Optional Object Thumbnail image for order details message. It has the following fields: type: Must be image. image: See Image Object. If the header is not present, the API finds the first product with an image and uses that for the thumbnail image. body Required Object An object with the body of the message. The object contains the following field: text string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters. footer Optional Object An object with the footer of the message. The object contains the following field: text string: Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters. action Required Action Object See Action Object below. Image Object Field Name Optional? Type Description link Required String Url of the image. provider Optional String Name of the url provider. Action Object Field Name Optional? Type Description name Required String Must be review_and_pay. parameters Required Parameters Object See Parameters Object. Parameters Object Field Name Optional? Type Description reference_id Required String Unique identifier for the order or invoice provided by the business. This cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 60 characters. The reference_id must be unique for each order_details message for the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id to ensure reference_id uniqueness. type Required String Must be one of digital-goods or physical-goods. payment_type Required String Must be br. payment_settings Optional Payment Settings Object List of payment related configuration objects. currency Required String ISO 4217 currency code for the order. Must be BRL (Brazilian Real). total_amount Required Amount Object See Amount Object. total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value order Optional Order Object See Order Object. Payment Settings Field Name Optional? Type Description type Required String One of pix_dynamic_code, payment_link, boleto. One of the following objects: pix_dynamic_code, payment_link, boleto. Required Object Payment instructions which will be displayed to buyers during the checkout process. Order Object Field Name Optional? Type Description status Required String Status of the order. Only supported value here is pending. catalog_id Optional String Unique identifier of the Facebook catalog being used by the business. expiration Optional Expiration Object Expiration for that order. The CTA for payment will be disabled after expiry on the user end. See Expiration Object. items Required List of Item Objects List must have at least one item. See Item Object. subtotal Required Amount Object See Amount Object. The value must be equal to sum of ( item.amount.value or item.sale_amount.value) * item.quantity. The following fields are part of the subtotal object: offset string Required. Must be 100 for BRL. value string Required. Positive integer representing the amount value multiplied by offset. For example, S$12.34. has value 1234 tax Required Amount With Description Object The tax information for this order. Even though the object is required, the amount can be zero. When zero is used, the tax line is not rendered in the client. See Amount With Description Object. shipping Optional Amount With Description Object See Amount Object. discount Optional Discount Object The discount for the order. See Discount object. Expiration Object Field Name Optional? Type Description timestamp Required String UTC time in seconds. Minimum threshold is 300 seconds. description Required String Text explanation for when the order will expire. Max character limit is 120 characters. Item Object Field Name Optional? Type Description retailer_id Required String Content ID for an item in the order from your catalog. name Required String The item’s name to be displayed to the user. Cannot exceed 60 characters. amount Required Amount Object The price per item. See Amount Object. quantity Required Integer Number of items in this order. sale_amount Optional Amount Object The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount. See Amount Object. Discount Object Field Name Optional? Type Description value Required Integer Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. offset Required Integer Must be 100 for BRL. description Optional String Max character limit is 60 characters. discount_program_name Optional String Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Amount Object Field Name Optional? Type Description value Required Integer Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. offset Required Integer Must be 100 for BRL. Amount Object (With Description) Field Name Optional? Type Description value Required Integer Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. offset Required Integer Must be 100 for BRL. description Optional String Max character limit is 60 characters. Order Status To send an order_status message, businesses must assemble an interactive object of type order_status with the following components: Interactive Object Field Name Optional? Type Description type Required String Must be order_status. header Optional Object Optional object for the message’s header for the message. body Required Object An object with the body of the message. The object contains the following field: text string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters. footer Optional Object An object with the footer of the message. The object contains the following field: text string: Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters. action Required Action Object See Action Object below. Action Object Field Name Optional? Type Description name Required String Must be review_order. parameters Required Parameters Object See Parameters Object. Parameters Object Field Name Optional? Type Description reference_id Required String The unique ID provided in the order_details message. order Optional Order Object See Order Object. payment Optional Payment Object See Payment Object. Order Object Field Name Optional? Type Description status Required String The new order status. See supported order status. description Optional String Optional text for sharing status related information in order-details page. Could be useful while sending cancellation. Length should not exceed 120 characters. Payment Object Field Name Optional? Type Description status Required String The new payment status. See supported payment status. timestamp Optional Integer Optional epoch timestamp in seconds Supported Order Status Currently we support the following order status values: Value Description pending Order is pending / not processed yet. processing Merchant/partner is fulfilling the order, performing service, etc. partially-shipped Part of the products in order have been shipped by the merchant. shipped All the products in order have been shipped by the merchant. completed The order is completed and no further action is expected from the user or the partner/merchant. canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message. Supported Payment Status Currently we support the following payment status values: Value Description pending Payment is pending. captured Payment was successfully captured. Receiving this payment status will update the order bubble to include the “paid” label (with green checkmark). failed Payment failed. Errors and Statuses These are the relevant errors for the WhatsApp Payments API: Error Code Description 2040 - Message is not supported The message you are trying to send cannot be received by this user 2046 - Order status invalid transition The order status cannot be updated from the existing value to the new one 2047 - Order cancellation failure The order could not be cancelled For a comprehensive list with detailed descriptions of error codes and HTTP status codes, please refer to our Error Codes document. Offsite Pix payments | Developer Documentation Offsite Pix payments Updated: Nov 14, 2025 Payments API also enables businesses to collect payments from their customers via WhatsApp using dynamic Pix codes. When using this integration, WhatsApp only facilitates the communication between merchants and buyers. Merchants are responsible for integrating with a bank or PSP in order to generate dynamic Pix codes, and confirm their payment. Before you start Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp.You will need an existing integration with a bank or PSP to generate dynamic Pix codes and do automatic reconciliation when a payment is made. You must be able to update the order status as soon as a payment is made. Payment links | Developer Documentation Payment links Updated: Nov 14, 2025 Payments API also enables businesses to collect payments from their customers via WhatsApp using Payment Links. When using this integration, WhatsApp only facilitates the communication between merchants and buyers. Merchants are responsible for integrating with a PSP from which they can generate Payment Links, and confirm their payment. Before You Start Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp.You will need an existing integration with a PSP to generate Payment Links and do automatic reconciliation when a payment is made.You must update the order status as soon as a payment is made. Boleto | Developer Documentation Boleto Updated: Nov 14, 2025 Payments API also enables businesses to collect payments from their customers via WhatsApp using Boleto. When using this integration, WhatsApp only facilitates the communication between merchants and buyers. Merchants are responsible for integrating with a PSP from which they can generate Boleto codes, and confirm their payment. Before you start Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp.You will need an existing integration with a PSP to generate Boleto codes and do automatic reconciliation when a payment is made.You must update the order status as soon as a payment is made. One-Click Payments | Developer Documentation One-Click Payments Updated: Nov 14, 2025 This feature is not publicly available yet and is only available for businesses based in Brazil and their Brazilian customers. To enable payments for your businesses, please contact your Solution Partner. Payments API also enables businesses to collect payments from their customers via WhatsApp using One-Click Payments. When using this integration, WhatsApp facilitates communication between merchants and buyers. Merchants are responsible for storing payment credentials and integrating with a payment service provider (PSP) to submit these credentials, completing and confirming their payments. Before you start Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp.You will need an existing integration with a PSP and do automatic reconciliation when a payment is made.You must update the order status as soon as a payment is made. Send order details template message | Developer Documentation Send order details template message Updated: Nov 4, 2025 Overview Order details message template is a template with interactive components that extends the call-to-action button to support sending order details and provides a richer experience compared to templates with only text components. Once your Order details message templates have been created and approved, you can use the approved template to send the template message with order or bill information to prompt customers to make a payment. Before sending an order details template message, businesses need to create a template with an “order details” call-to-action button. See Create Message Templates for Your WhatsApp Business Account⁠ for more information on prerequisites and how to create a template. Creating an order details template on WhatsApp Manager To create an order details template, business needs a business portfolio with a WhatsApp Business Account. In WhatsApp Manager > Account tools:Click on create templateSelect Utility or Marketing category to see the Order details template format option.Select Order details template format, and click NextEnter the desired template name and supported locale Depending on the number of locales selected there will be an equal number of template variants and businesses need to fill in the template details in respective locale.Fill in template components such as Header, Body and optional footer text. For the Header, you can choose one of three media types: Text, Image or Document. Choose Document if you want to send PDF files in the header of this template.Click submit.Once submitted, templates will be categorized as per the guidelines and undergo the approval process.The template will be approved or rejected after the template components are verified by the system. If business believe the category determined is not consistent with our template category guidelines, please confirm there are no common issues that leads to rejections and if you are looking for further clarification you may request a review of the template via Business Support⁠Once approved template status will be changed to ACTIVE Please be informed that template’s status can change automatically from ACTIVE to PAUSED or DISABLED based on customer feedback and engagement. We recommend that you monitor status changes and take appropriate actions whenever such change occurs. Sending order details template message Order details template message allows the businesses to send invoice (order_details) message as predefined order details call-to-action button component parameters. It supports businesses to send all payment integration (such as Dynamic Pix code, Payment Links, Boleto, etc) integration as button parameters. To send an order details template message, make a POST call to /PHONE_NUMBER_ID/messages endpoint and attach a message object with type=template. Then, add a template object with a predefined order details call-to-action button. You can optionally include a PDF file as attachment in the header component of the template message. To do so, you use type=document in the parameter object of the header component object, as described in our Components document. For example following sample describes how to send Copy Pix code in order details template message parameters to prompt the consumer to make a payment. Post order details template message flow After the order details template message delivery the rest of the payment flow is the same as “Sending invoice in customer session window” and depends on the chosen payment integration order details parameters. Receive UPI Payments Through WhatsApp | Developer Documentation Receive UPI Payments Through WhatsApp Updated: Nov 14, 2025 This is NOT the recommended UPI Intent integration. Migrate to dynamic VPA. With dynamic VPA, you can rotate VPAs on UPI intents without requiring any configuration changes on your end - simplifying integration and ongoing maintenance. Your business can enable customers to pay for their orders using all the UPI Apps installed on their devices via WhatsApp. Businesses can send customers invoice( order_details) messages, then get notified about payment status updates via webhook notifications from Payment Gateway. Overview Currently, customers browse business catalogs, add products to cart, and send orders in with our set of commerce messaging solutions, which includes Single Product Message, Multi Product Message, and Product Detail Page. With the WhatsApp Payments API, businesses can send customers a bill so the customer can complete their order with all the UPI Apps. How It Works The business must send an order_details message for the consumer to initiate payment. This type of message is a new type of interactive message, which always contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment. Each order_details message contains a unique reference_id provided by the business, and that unique number is used throughout the flow to track the order. This reference_id is fetched from UPI intent link(tr value from the UPI payment intent) generated for a business order from Payment Gateway. Once the message is sent, the business waits for a payment or transaction status updates directly from Payment Gateway. Upon receiving payment signal for an order, Business should relay this payment signal to consumer through interactive order status( order_status) message. Updating user about the payment signal is important as this message updates the order details message and order details view for the consumer reflecting the order confirmation from merchant. This is shown with an example in subsequent sections. Purchase Flow in App In the WhatsApp customer app, the purchase flow has the following steps: Customer sends an order with selected products to the business or Business identifies the products that the customer has shown interest to purchase. After receiving the order/identifying the product, if a merchant accepts payment methods other than UPI, such as credit cards and payment wallets, then merchant will send a message to the user to get their preferred payment method for the order. When consumers want to pay using UPI payment method, then merchants should retrieve the UPI payment intent by calling Payment Gateway. Merchant needs to use UPI intent to construct order details messages and send it to the consumer. When the consumer taps the Pay now/continue button, they will be given the option to choose UPI payment Apps - WhatsApp or any other UPI payments apps. Consumers may choose any UPI option to pay for the order. Consumer pays for the order and the payment method is saved for the future and automatically selected for the next payment transaction. Also, one quick note is the order details screen order-status will continue to show “Order pending” until merchant sends order status interactive message. Once the payment is complete, the business receives a notification from Payment Gateway and the merchant needs to send order status updates to the consumer client notifying consumers about the progress to the order, this will update the order details message CTAs and order details screen - order status description. Before You Start To receive UPI payments on WhatsApp merchants have to set up their VPA on WhatsApp Business Manager using the direct payment methods option. Each configuration must have a unique name, merchant categorization code (mcc), purpose code, and VPA handles as shown below. A business can have multiple payment configurations, but for each order merchant must specify a specific configuration to be used for payment. See payment_configuration field in order_details message. name for each payment type must be unique. name will be used to reference the specific configurations for each payment type. If WA is unable to find a payment configuration name, the user will not be able to make the payment upon receiving the order_details message. mcc refers to a merchant categorization code⁠ for the items in the order. upi_pc refers to the purpose of the transaction. Some sample codes are below: Code Title 00 Default 01 SEMI 02 AMC 03 Travel 04 Hospitality 05 Hospital 06 Telecom 07 Insurance 08 Education 09 Gifting 10 Others If merchant/partner is not sure of the MCC and purpose code, then they may contact Payment Gateway to get this information as Payment Gateway sets up these values based on the type of business while generating business VPAs. Manage Your Payment Methods (Beta Feature) Self-service Payment Configuration allows you to add multiple payment configurations to your WhatsApp Manager profile. Each payment configuration will have its own UPI handle(VPA), MCC, and purpose code (for physical goods) so that merchants can accept payments for different categories with different UPI accounts. After setup, merchant can send invoice( order_details) messages to users with the corresponding payment configuration to collect payments. Pre-requisites Manage Payment Methods feature is in Beta, so please contact Business Engineering team to allow merchants/partners access the page in WhatsApp Business Manager portal. Steps to link Payment Configuration for a Business Service Provider You can create a payment configuration for a WhatsApp Business Account using the ‘Payment configurations’ page and under ‘India’ in WhatsApp Business Manager⁠. After linking your payment configuration, you must integrate with the Payments APIs below. This will allow you to send an order_details message to customers with the payment configuration to receive payments. Steps to unlink Payment Configuration Note: Make sure no new order messages requesting payment from consumer are sent with the payment config your are trying to remove before you perform the unlink action. Integration Steps The steps outlined below assume that the business is about to send order details message to consumer client. The following sequence diagram demonstrates the typical integration flow for WA Payments API: Step 1: Get UPI Intent from Payment Gateway Once the consumer has expressed their interest to purchase an item using UPI payment method. Merchant needs to call payment gateway to create a UPI intent, the following is the sample UPI intent link: upi://pay?pa=cfsukoonaa@yesbank&pn=Sukoon&tr=877376394&   am=10.00&cu=INR&mode=00&purpose=00&mc=5399&tn=877376394 Merchant needs to parse the tr value from the above URI and use this as the reference id in invoice( order_details) interactive message. Step 2: Assemble the Interactive Object To send an order_details message, businesses must assemble an interactive object of type order_details with the following components: Object Description type object Required. Must be “order_details”. header object Optional. Header content displayed on top of a message. If a header is not provided, the API uses an image of the first available product as the header body object Required. An object with the body of the message. The object contains the following field: text stringRequired if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters footer object Optional. An object with the footer of the message. The object contains the following fields: text stringRequired if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters action object Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name stringRequired. Must be “review_and_pay” parameters objectSee Parameters Object for information Parameters Object Object Description reference_id string Required. Unique identifier for the order or invoice provided by the business. This cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The reference_id must be unique for each order_details message for the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id (for example, -) to ensure reference_id uniqueness. type object Required. The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods beneficiaries array Required for shipped physical-goods. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. It contains the following fields: Beneficiary information isn’t shown to users but is needed for legal and compliance reasons. name stringRequired. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters address_line1 stringRequired. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters address_line2 stringOptional. Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters city stringRequired. Name of the city. state stringRequired. Name of the state. country stringRequired. Must be “India”. postal_code stringRequired. 6-digit zipcode of shipping address. payment_type Required. Must be “upi”. payment_configuration Required. The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters. currency Required. The currency for this order. Currently the only supported value is INR. total_amount object Required. The total_amount object contains the following fields: offset integerRequired. Must be 100 for INR. value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value. order object Required. See order object for more information. Order Object Object Description status string Required. Only supported value in the order_details message is pending. In an order_status message, status can be: pending, captured, or failed. type string Optional. Only supported value is quick_pay. When this field is passed in we hide the “Review and Pay” button and only show the “Pay Now” button in the order details bubble. items object Required. An object with the list of items for this order, containing the following fields: retailer_id stringOptional. Content ID for an item in the order from your catalog. name stringRequired. The item’s name to be displayed to the user. Cannot exceed 60 characters image objectOptional. Custom image for the item to be displayed to the user. See item image object for information Using this image field will limit the items array to a maximum of 10 items and this cannot be used with retailer_id or catalog_id. amount amount object with value and offset -- refer total amount field aboveRequired. The price per item sale_amount amount objectOptional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount quantity integerRequired. The number of items in this order, this field cannot be decimal has to be integer. country_of_origin stringOptional if catalog_id is not present. The country of origin of the product importer_name stringOptional if catalog_id is not present. Name of the importer company importer_adress stringOptional if catalog_id is not present. Address of importer company subtotal object Required. The value must be equal to order.amount.value multiplied by order.amount.quantity. Refer to total_amount description for explanation of offset and value fields The following fields are part of the subtotal object: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 tax object Required. The tax information for this order which contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters shipping object Optional. The shipping cost of the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount object Optional. The discount for the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount_program_name stringOptional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters catalog_id object Optional. Unique identifier of the Facebook catalog being used by the business. expiration object Optional. Expiration for that order. Business must define the following fields inside this object: timestamp string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds description string – Text explanation for expiration. Max character limit is 120 characters Item Image Object Object Description link string Required. A link to the image that will be shown to the user. Must be an image/jpeg or image/png and 8-bit, RGB or RGBA. Follows same requirements as image in media By the end, the interactive object should look something like this for a catalog-based integration: For a non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows: Step 3: Add Common Message Parameters Once the interactive object is complete, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive. These are parameters common to all message types. Step 4:Make a POST Call to Messages Endpoint Make a POST call to the /[PHONE_NUMBER_ID]/messages endpoint with the JSON object you have assembled. If your message is sent successfully, you get the following response: For all errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes. Step 5: Consumer Pays for the Order Consumers can pay using WhatsApp payment method or using any UPI supported app that is installed on the device. Step 6: Get Notified About Transaction Status Updates from payment gateway Businesses receive updates to the invoice via payment gateway webhooks, when the status of the user-initiated transaction changes. The unique identifier tr(reference-id passed in order_details message) can be used to map the transaction to the consumer invoice or interactive order details message. Please refer to your PG’s documentation for the exact payment signals. If you are not receiving webhooks from your PG, then work with them to enable it. Step 7: Update order status Upon receiving transaction signals from payment gateway through webhook, the business must update the order status to keep the user up to date. Currently we support the following order status values: Value Description pending User has not successfully paid yet processing User payment authorized, merchant/partner is fulfilling the order, performing service, etc. partially-shipped A portion of the products in the order have been shipped by the merchant shipped All the products in the order have been shipped by the merchant completed The order is completed and no further action is expected from the user or the partner/merchant canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message Typically businesses update the order_status using either the WhatsApp payment status change notifications or their own internal processes. To update order_status, the partner sends an order_status message to the user. The following table describes the returned values: Value Description reference_id The ID provided by the partner in the order_details message status The new order status description Optional text for sharing status related information in order_details. Could be useful while sending cancellation. Max character limit is 120 characters Merchant should always post this order-status message to consumer after receiving transaction updates for an order. As the order_details message and order details screen experience is tied to to the order status updates. Step 8: Reconcile Payments Businesses should use their bank statements to reconcile the payments using the reference_id provided in the order_details messages. Merchant Preferred UPI Payment Method Now merchants can specify up to one UPI Payment app to showup in checkout flow. Merchant preferred payment app will be shown on top of the list of available UPI apps in - “Choose payment method” screen. To enable this capability we require partners to specify the external app-id in the Order Details or order-invoice message. Note: This feature is available on consumer apps on and above version: 2.24.21.0 Updates to Order Details Payload List of supported apps: UPI Application Application ID to be passed in Order Details payload Google Pay gpay PhonePe phonepe PayTm paytm Amazon Pay amazonpay CRED cred Mobikwik mobikwik Checklist for Integrated Merchants Ensure that order_status message is send to consumer informing them about updates to an order after receiving transaction updates for an order. Ensure the merchant is verified and WABA contact is marked with a verified check. Verify the WABA is mapped to appropriate merchant initiated messaging tier(1k, 10k and 100k per day) Merchant should list the customer support information in the profile screen incase consumer wants to report any issues. Receive payments via payment gateways on WhatsApp | Developer Documentation Receive payments via payment gateways on WhatsApp Updated: Dec 12, 2025 Your business can enable customers to pay for their orders through our partner payment gateways without leaving WhatsApp. Businesses can send customers order_details messages, then get notified about payment status updates via webhook notifications. Overview Currently, customers browse business catalogs, add products to cart, and send orders with our set of commerce messaging solutions, which includes Single Product Message, Multi Product Message, and Product Detail Page. Now, with the Payments API, businesses can send customers a bill, so the customer can complete their order by paying the business without having to leave WhatsApp. Our payments solution is currently enabled by BillDesk, Razorpay, PayU and Zaakpay, a third-party payments service provider. You must have a BillDesk, Razorpay, PayU or Zaakpay account in order to receive payments on WhatsApp. We expect more payment providers to be added in the future. How it works First, the business composes and sends an order_details message. An order_details message is a new type of interactive message, which always contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment. Each order_details message contains a unique reference_id provided by the business, and that unique ID is used throughout the flow to track the order. Once the message is sent, the business waits for a payment status update via webhooks. Businesses get notified when the payment status changes, but they must not solely rely on these webhooks notifications due to security reasons. WhatsApp also provides a payment lookup API that can be used to retrieve the payment statuses directly anytime. Purchase flow in app In the WhatsApp Messenger App, the purchase flow has the following steps: Customers send an order with selected products to the business either through simple text messages or using other interactive messages such as Single Product Message, Multi Product Message, and Product Detail. Once the business receives the order, they send an order_details message to the user. When the user taps on Review and Pay, they will see details about the order and total amount to be paid. When the user taps the Continue button, they are able to choose to pay natively on WhatsApp or any other UPI app. Checkout with WhatsApp Pay: [image removed - too large for import] Checkout on other UPI Apps: [image removed - too large for import] Once the payment has been confirmed by your payment gateway (PG) or payment service provider, the business can start processing the order. Businesses can then send an order_status message to the consumer informing them about the status of the order. Each message will result in a message bubble (as shown below) that refers to the original order details message and also updates the status displayed on the order details page. Link your payment account To receive payments on WhatsApp, you must add a payment configuration to the corresponding WhatsApp Business Account. A payment configuration allows you to link a payment gateway account to WhatsApp. Each payment configuration is associated with a unique name. As part of the order_details message, you can specify the payment configuration to use for a specific checkout. WhatsApp will then generate a checkout flow using the associated payment gateway account. [image removed - too large for import] After linking your payment partner account, you must integrate with the Payments APIs below. This will allow you to send an order_details message to customers with the payment configuration to receive payments. Steps to unlink Payment Configuration Note: Make sure no new order messages requesting payment from consumer are sent with the payment config your are trying to remove before you perform the unlink action. Integration Steps The steps outlined below assume that the business already knows what the user is interested in through earlier chat threads. The Payments API is a standalone API and hence can work with various messages such as List Messages, Reply Buttons, Single or Multi-Product Messages. Sequence Diagram The following sequence diagram demonstrates the typical integration flow for Payments API. The steps highlighted in green are the key integration steps. [image removed - too large for import] Step 1: Send Order Details Interactive Message To send an order_details message, businesses must assemble an interactive object of type order_details with the following components: Object Description type object Required. Must be “order_details”. header object Optional. Header content displayed on top of a message. If a header is not provided, the API uses an image of the first available product as the header body object Required. An object with the body of the message. The object contains the following field: text stringRequired if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters footer object Optional. An object with the footer of the message. The object contains the following fields: text stringRequired if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters action object Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name stringRequired. Must be “review_and_pay” parameters objectSee Parameters Object for information Parameters Object Object Description reference_id string Required. Unique identifier for the order or invoice provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The reference_id must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, “BM345A-12”) to ensure reference_id uniqueness. type object Required. The type of goods being paid for in this order. Current supported options are digital-goods and physical-goods. beneficiaries array Required for shipped physical-goods. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. It contains the following fields: Note: Beneficiary information isn’t shown to users but is needed for legal and compliance reasons. name stringRequired. Name of the individual or business receiving the physical goods. Cannot exceed 200 characters address_line1 stringRequired. Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters address_line2 stringOptional. Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters city stringRequired. Name of the city. state stringRequired. Name of the state. country stringRequired. Must be “India”. postal_code stringRequired. 6-digit zipcode of shipping address. currency Required. The currency for this order. Currently the only supported value is INR. total_amount object Required. The total_amount object contains the following fields: offset integerRequired. Must be 100 for INR. value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value. UPI transactions are limited to ₹5,00,000. For higher amounts, set enabled_payment_options to ["web"]. See Restrict Available Payment Options. payment_settings object Required. See Payment Settings object for more information. order object Required. See order object for more information. Payment settings object Object Description type string Required. Must be set to “payment_gateway” payment_gateway object Required. An object that describes payment account information: type stringRequired. Unique identifier for an item in the order. You must set this to “billdesk” or “razorpay” or “payu” or zaakpay, if you have linked your BillDesk or Razorpay or PayU or Zaakpay payment gateway to accept payments configuration_name stringRequired. The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters. This value must match with a payment configuration set up on the WhatsApp Business Manager. When configuration_name is invalid, the customer will be unable to pay for their order. We strongly advise businesses to conduct extensive testing of this setup during the integration phase. billdesk/razorpay/payu/zaakpay objectOptional. For merchants/partners that want to use additional_info1/7(for BillDesk), notes and receipt(for Razorpay) and UDF fields(for PayU) and extra1/2(for Zaakpay), they can now pass these values in Order Details message and we would use these to create transaction/order at respective PGs. Please refer Payment Gateway specific UDF object for more information. BillDesk, RazorPay, PayU and Zaakpay fields We now have support for partners and merchants to pass notes, receipt and udf fields in Order Details message and receive this data back in payment signals. Here we will take a look at merchants can pass additional_info for BillDesk, notes and receipt fields for Razorpay, udf for PayU, extra for Zaakpay PGs. Object Description notes object Optional.Only supported for Razorpay payment gateway The object can be key value pairs with maximum 15 keys and each value limits to 256 characters. receipt String Optional.Only supported for Razorpay payment gateway Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters supported with minimum length greater than 0 characters. udf1-4 String Optional.Only supported for PayU payment gateway User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255. extra1-2 String Optional.Only supported for Zaakpay payment gateway User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 180. additional_info1-7 String Optional.Only supported for BillDesk payment gateway User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 120. Order object Object Description status string Required. Only supported value in the order_details message is pending. In an order_status message, status can be: pending, captured, or failed. type string Optional. Only supported value is quick_pay. When this field is passed in we hide the “Review and Pay” button and only show the “Pay Now” button in the order details bubble. items object Required. An object with the list of items for this order, containing the following fields: retailer_id stringOptional. Content ID for an item in the order from your catalog. name stringRequired. The item’s name to be displayed to the user. Cannot exceed 60 characters image objectOptional. Custom image for the item to be displayed to the user. See item image object for information Using this image field will limit the items array to a maximum of 10 items and this cannot be used with retailer_id or catalog_id. amount amount object with value and offset -- refer total amount field aboveRequired. The price per item sale_amount amount objectOptional. The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount. quantity integerRequired. The number of items in this order, this field cannot be decimal has to be integer. country_of_origin stringRequired if catalog_id is not present. The country of origin of the product importer_name stringRequired if catalog_id is not present. Name of the importer company importer_adress stringRequired if catalog_id is not present. Address of importer company subtotal object Required. The value must be equal to sum of order.amount.value * order.amount.quantity. Refer to total_amount description for explanation of offset and value fields The following fields are part of the subtotal object: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 tax object Required. The tax information for this order which contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters shipping object Optional. The shipping cost of the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount object Optional. The discount for the order. The object contains the following fields: offset integerRequired. Must be 100 for INR value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234 description stringOptional. Max character limit is 60 characters discount_program_name stringOptional. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters catalog_id object Optional. Unique identifier of the Facebook catalog being used by the business. If you do not provide this field, you must provide the following fields inside the items object: country_of_origin, importer_name, and importer_address expiration object Optional. Expiration for that order. Business must define the following fields inside this object: timestamp string – UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds description string – Text explanation for expiration. Max character limit is 120 characters Item Image Object Object Description link string Required. A link to the image that will be shown to the user. Must be an image/jpeg or image/png and 8-bit, RGB or RGBA. Follows same requirements as image in media The parameters value is a stringified JSON object. By the end, the interactive object should look something like this for a BillDesk catalog-based integration: The parameters value is a stringified JSON object. By the end, the interactive object should look something like this for a RazorPay catalog-based integration: The parameters value is a stringified JSON object. For a PayU non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows: For a Zaakpay non-catalog based integration i.e. when catalog-id is not present, an example payload looks as follows: Step 2: Add Common Message Parameters Once the interactive object is complete, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive. These are parameters common to all message types. Step 3:Make a POST Call to Messages Endpoint Make a POST call to the /[PHONE_NUMBER_ID]/messages endpoint with the JSON object you have assembled. If your message is sent successfully, you get the following response: For all errors that can be returned and guidance on how to handle them, see WhatsApp Cloud API, Error Codes. Product Experience The customer receives an order_details message similar to the one below (left). When they click on “Review and Pay”, it opens up the order details screen as shown below (middle). Customer can then pay for their order using “Continue” button that opens up a bottom sheet with the payment options (right). [image removed - too large for import] [image removed - too large for import] [image removed - too large for import] Step 4: Receive Webhook about Transaction Status Businesses receive updates via messages webhooks when the status of the user-initiated transaction changes in a status of type “payment”. It contains the following fields: Object Description id string Required. Webhook ID for the notification. recipient_id string Required. WhatsApp ID of the customer. type string Required. For payment status update webhooks, type is “payment”. status string Required. captured/ pending: captured - when the payment is successfully completed, pending when the user attempted but yet to receive success transactions signal payment object Required. Contains the following field: reference_id string Unique reference ID for the order sent in order_details message. amount object Has value and offset fields corresponding to total amount that user has paid. currency string currency is always INR. transaction object Transaction attempt for this payment. Transaction object contains the following fields: id string Required. The alpha-numeric payment gateway order ID. pg_transaction_id string Optional. The alpha-numeric payment gateway payment ID. type string Required. The payment type for this transactions. Only, billdesk or razorpay or payu or zaakpay are supported. status string Required. The status of the transaction. Can be one of pending or success or failed. created_timestamp integer Required. Time when transaction was created in epoch seconds. updated_timestamp integer Required. Time when transaction was last updated in epoch seconds. method object (Optional. the payment method information might not be available for failed payments) type string Required. The describes the type of payment method used by consumer to pay for the order. Can be one of upi or card or wallet or netbanking. error object (Optional. the payment error details might not be available for all payments attempts) code string Required. The describes the payment failure reason that is generated by payment gateway and Meta returns this to partners. reason string Required. The describes the payment failure reason in plain text that is generated by payment gateway and Meta returns this to partners. additional_info1-7 string Optional. Only sent for billdesk payment gateway when the value is sent in order details message. Each of the keys additional_info1-4 has string values in them. notes object Optional. Only sent for razorpay payment gateway when the value is sent in order details message. This contains key-value pair as passed in the Order Details message. receipt string Optional. Only sent for razorpay payment gateway when the value is sent in order details message. udf1-4 string Optional.Only sent for payu payment gateway when the value is sent in order details message. Each of the keys udf1-4 has string values in them. extra1-2 string Optional.Only sent for zaakpay payment gateway when the value is sent in order details message. Each of the keys extra1-2 has string values in them. refunds array Optional. The list of refunds for this order. Each refund object contains the following fields: id string Required. The alpha-numeric ID of the refund. amount object Required. The total amount of the refund. speed_processed string Required. Speed by which refund was processed. Can be one of instant or normal. status string Required. The status of the refund. Can be one of pending, success or failed. created_timestamp integer Required. Time when refund was created in epoch seconds. updated_timestamp integer Required. Time when refund was last updated in epoch seconds. timestamp string Required. Timestamp for the webhook. Here is an example status webhook of type payment: For more information about other statuses, see Messages Webhooks. Step 5: Confirm Payment After receiving the payment status webhook, or at any time, the business can look up the status of the payment for the order. To do that, businesses must make a GET call to the payments endpoint as shown here: GET /payments// where payment_configuration and reference_id are same as that sent in the order_details message. Businesses should expect a response in the same HTTP session (not in a webhook notification) that contains the following fields: Field Description reference_id string Required. The ID sent by the business in the order_details message status string Required. Status of the payment for the order. Can be one of pending or captured Refer the table below for what these statuses mean. currency string Required. The currency for this payment. Currently the only supported value is INR. amount object Required. The amount for this payment. It contains the following fields: offset integerRequired. Must be 100. value integerRequired. Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. transactions array Optional. The list of transactions for this payment. This field is only present when at least one payment attempt has been made. If the payment status is pending and no payment attempt has occurred, this field will not be returned. Each transaction object contains the following fields: id stringRequired. The alpha-numeric payment gateway order ID. pg_transaction_id stringRequired. The alpha-numeric payment gateway payment ID. type stringRequired. The payment type for this transactions. Only, billdesk or razorpay or payu or zaakpay are supported. status stringRequired. The status of the transaction. Can be one of pending or success or failed. At most one transaction can have a success status. created_timestamp integerRequired. Time when transaction was created in epoch seconds. updated_timestamp integerRequired. Time when transaction was last updated in epoch seconds. method object Optional. the payment method information might not be available for failed payments type string Required. The describes the type of payment method used by consumer to pay for the order. Can be one of upi or card or wallet or netbanking. error object Optional. the payment error details might not be available for all payments attempts code string Required. The describes the payment failure reason that is generated by payment gateway and Meta returns this to partners. reason string Required. The describes the payment failure reason in plain text that is generated by payment gateway and Meta returns this to partners. refunds array Optional. The list of refunds for this order. Each refund object contains the following fields: id string Required. The alpha-numeric ID of the refund. amount object Required. The total amount of the refund. speed_processed string Required. Speed by which refund was processed. Can be one of instant or normal. status string Required. The status of the refund. Can be one of pending, success or failed. created_timestamp integer Required. Time when refund was created in epoch seconds. updated_timestamp integer Required. Time when refund was last updated in epoch seconds. additional_info1-7 string Optional. Supported for only BillDesk PG, this contains string values sent as part of Order Details message. receipt string Optional. Supported for only Razorpay PG, this contains the receipt-value sent as part of Order Details message. notes object Optional. Supported for only Razorpay PG, this contains the key-value pairs sent as part of Order Details message. udf1-4 string Optional. Supported for only PayU PG, this contains string values sent as part of Order Details message. extra1-2 string Optional. Supported for only Zaakpay PG, this contains string values sent as part of Order Details message. Payment Status Status Description pending The order has been created but payment has not yet been captured. This status covers two scenarios:No payment attempt yet: The transactions array will not be present in the response.Payment attempted but failed: The transactions array will contain one or more entries with status set to failed. captured The payment was successfully captured. The transactions array will contain an entry with status set to success. An example successful response looks like this: Shown here is an example for a generic error: Response by Payment Stage The response payload varies depending on the payment stage. Below are examples for each stage. No payment attempted — The user has not yet attempted payment. Only order-level fields are returned; the transactions array is not present. Payment successful — The user completed payment and the payment gateway confirmed capture. The transactions array contains the successful transaction with payment method details. Payment failed — The user attempted payment but it failed. The overall payment status remains pending (the order is still awaiting successful payment), but the transactions array contains the failed attempt with error details. Step 6: Update Order Status Businesses must send updates to their order using the order_status message instead of text messages since the latest status of an order displayed on the order details page is only based on order_status messages. To notify the customer with updates to an order, you can send an interactive message of type order_status as shown below. The following table describes the fields in the order_status interactive message: Object Description type string Required. Must be “order_status” body object Required. An object with the body of the message. The object contains the following field: text stringRequired if body is present. The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters. footer object Optional. An object with the footer of the message. The object contains the following field: text stringRequired if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters. action object Required. An action object you want the user to perform after reading the message. This action object contains the following fields: name stringRequired. Must be “review_order”. parameters objectSee Parameters Object for information. Parameters object The parameters object contains the following fields: Value Description reference_id string Required. The ID sent by the business in the order_details message. order object Required. This object contains the following fields: status stringRequired. The new order status. Must be one of processing, partially_shipped, shipped, completed, canceled. description stringOptional. Text for sharing status related information in order_details. Could be useful while sending cancellation. Max character limit is 120 characters. order_status message introduces two new errors that are summarized below. Error Code Description 2046 - Invalid status transition The order status transition is not allowed. 2047 - Cannot cancel order Cannot cancel the order since the user has already paid for it. Product Experience Customers receive each order_status update as a separate message in their chat thread, that references their original order_details message as shown below (left). The order details page always displays the latest valid status communicated to the customer using the order_status message as shown below (right). [image removed - too large for import] [image removed - too large for import] Supported Order Status and Transitions Currently we support the following order status values: Value Description pending User has not successfully paid yet processing User payment authorized, merchant/partner is fulfilling the order, performing service, etc. partially-shipped A portion of the products in the order have been shipped by the merchant shipped All the products in the order have been shipped by the merchant completed The order is completed and no further action is expected from the user or the partner/merchant canceled The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message Order status transitions are restricted for consistency of consumer experience. Allowed status transitions are summarized below:Initial status of an order is always pending, which is sent in order_details message. canceled and completed are terminal status and cannot be updated to any other status. pending can transition to any of the other statuses including processing, shipped, partially-shipped. processing, shipped and partially-shipped are equivalent statuses and can transition between one another or to one of the terminal statuses. [image removed - too large for import] Upon sending an order_status message with an invalid transition, you will receive an error webhook with the error code 2046 and message “New order status was not correctly transitioned.” Canceling an Order An order can be canceled by sending an order_status message with the status canceled. The customer cannot pay for an order that is canceled. The customer receives an order_status message and order details page is updated to show that the order is canceled and the “Continue” button removed. The optional text shown below “Order canceled” on the order details page can be specified using the description field in the order_status message. An order can be canceled only if the user has not already paid for the order. If the user has paid and you send an order_status message with canceled status, you will receive an error webhook with error code 2047 and message “Could not change order status to ‘canceled’”. Step 7: Reconcile Payments WhatsApp does not support payment reconciliations. Businesses should use their payment gateway account to reconcile the payments using the reference_id provided in the order_details messages and the id of the transactions returned as part of the payment lookup query. Merchant Preferred UPI Payment Method Now merchants can specify up to one UPI Payment app to showup in checkout flow. Merchant preferred payment app will be shown on top of the list of available UPI apps in the “Choose payment method” screen. To enable this capability we require partners to specify the external app-id in the Order Details or order-invoice message. Note: This feature is available on consumer apps on and above version: 2.24.21.0 Updates to Order Details Payload List of supported apps: UPI Application Application ID to be passed in Order Details payload Google Pay gpay PhonePe phonepe PayTm paytm BHIM bhim Amazon Pay amazonpay CRED cred Mobikwik mobikwik Restrict Available Payment Options Merchants can specify which payment options to show in checkout flow between UPI and Web options. This will allow merchants to enable only UPI or credit card(any PG available option) to accept payments for invoices. UPI transactions are limited to ₹5,00,000. For higher amounts, set enabled_payment_options to ["web"] to use your payment gateway’s web checkout. Payments with UPI enabled above this limit will fail. Note: This feature is available on consumer apps on and above version: 2.24.22.4 Updates to Order Details Payload List of payment options Enabled Option Experience in checkout flow upi Only UPI apps are show in checkout flow web Payment gateway webpage is loaded and merchant payment gateway account configured payment options will be shown in the checkout flow. Some Payment Gateways allow customization of payment options that are shown in payment link or web based checkout flow. Please contact Payment Gateway to restricting payment options in payment link or web page. Third Party Validation with Razorpay and PayU Payment Gateways We now support TPV for RazorPay and PayU merchants, this allows merchants to specify the consumer accounts from which orders needs to be paid. Since, the consumer bank account information is sensitive, please work with Payment Gateways to procure public encryption key and pass the encryption information as part of Order details message. To use this feature which is in alpha testing, please reach out to Meta payments team - whatsappindia-bizpayments-support@meta.com Updates to Order Details Payload to support TPV for Razorpay merchants The raw value before encryption should look something like the following: Updates to Order Details Payload to support TPV for PayU merchants The raw value before encryption should look like the following: Note please closely work with Meta and Payment Gateway teams(RazorPay or PayU) to unlock this feature as we are still in alpha testing phase. Security Considerations Businesses should comply with local security and regulatory requirements in India. They should not rely solely on the status of the transaction provided in the webhook and must use payment lookup API to retrieve the statuses directly from WhatsApp. Businesses must always sanitize/validate the data in the API responses or webhooks to protect against SSRF attacks. Checklist for Integrated Merchants Ensure that order_status message is send to consumer informing them about updates to an order after receiving transaction updates for an order. Ensure the merchant is verified and WABA contact is marked with a verified check. Verify the WABA is mapped to appropriate merchant initiated messaging tier(1k, 10k and 100k per day) Merchant should list the customer support information in the profile screen incase consumer wants to report any issues. Migrate to “payment_settings” in place of “payment_type” and “payment_configuration”. This is the recommended way, and gives access to features likes “notes” and “udf” fields. For an example, view the payloads above. Permissions Permissions | Developer Documentation Permissions Updated: Nov 5, 2025 Platform endpoints are gated by permissions. References for each endpoint indicated which permissions it requires, but in general, you will need the following: whatsapp_business_management - needed to access metadata on your WhatsApp Business Account, template management, getting business phone numbers associated with your WABA, all analytics, and to receive webhooks notifying you of changes to your WhatsApp Business Accountwhatsapp_business_messaging - needed to send any type of message to a WhatsApp users, and to receive incoming message and message status webhooks Depending on your business needs, you may also need these permission: business_management - only needed if you need to programmatically access your business portfolio (this is rarely needed, since you can access your portfolio using Meta Business Suite?.whatsapp_business_manage_events - only needed if you are sending marketing templates with Marketing Messages API for WhatsApp, in conjunction with the Conversions API, for event tracking.ads_read - only needed if you are using Marketing Messages API for WhatsApp in conjunction with the Insights API to get conversion metrics App Review If you are a solution provider and other businesses will be using your app to access their data, your app must undergo App Review, and you must be approved for advanced access for any permissions your app needs. If you aren't approved for advanced access for a given permission, your app users will be unable to grant your app that permission. If you are a direct developer and will only be accessing your own business data, you do not need to under App Review and do not need advanced access for any permissions. How to get permissions App users must grant your app individual permissions. If you are a direct developer and are using a system token, when you create a system token, you must create a system user and use it to grant your app individual permissions as part of the system token creation process: If you are a solution provider using business tokens, the Embedded Signup authorization screen allows the user to grant your app permissions for which you have advanced access approval: Policy Enforcement WhatsApp Business Platform policy and spam enforcement | Developer Documentation WhatsApp Business Platform policy and spam enforcementUpdated: Nov 4, 2025To maintain high-quality experiences at scale on the WhatsApp Business Platform, WhatsApp will enforce on WhatsApp Business Accounts that repeatedly violate the WhatsApp Business Messaging Policy⁠, the WhatsApp Commerce Policy⁠, or the WhatsApp Business Terms of Service⁠.The goal of this guide is to educate businesses on how this enforcement system works and the product experience.This document does not include information on messaging limits based on quality rating. How it worksInitially, WhatsApp Business Accounts will get a warning with information on the policy they violated.If Business Accounts repeatedly violate the WhatsApp Business Terms of Service⁠, such as sending spam, template misclassifications, or high-risk policy categories such as adult content, sale of alcohol and tobacco, drugs, gambling and unsafe supplements, they might start seeing messaging restrictions that gradually increase in duration.These restrictions can look like: 1 or 3 day block on sending marketing, utility, and authentication template messages and adding additional phone numbers to the account5, 7, or 30 day block on sending any messages and adding additional phone numbers to the accountAn account lock, which is an indefinite block on sending any messages; can only be removed via an appealEventually be permanently disabled from the WhatsApp Business Platform, if the business does not make changes after multiple warnings and feature limits or blocksIn some cases, where there is evidence of a policy violation that causes severe harm to our users, such as child exploitation, scams, terrorism, or the sale of illegal drugs, WhatsApp will immediately offboard these Business accounts.We might also limit or offboard your business from WhatsApp if your account receives excessive negative feedback from users.Violations might be appealed or acknowledged, based on violation type and eligibility. Product experienceWe have a comprehensive product experience so that businesses and Solution Providers can access transparent, granular and actionable information about violations via multiple channels. Business Support HomeWhen a business account violates a policy, additional detail can be found by reviewing the violation in the Business Support Home⁠ section of Meta Business Suite or Business Manager.To access Business Support Home in Meta Business Suite: Sign into Meta Business Suite⁠.Click All tools in the left-side menu, then click Business Support Home.Click Account Overview (the speedometer icon) in the left-side menu, if necessary.To access Business Support Home in Business Manager: Sign into Business Manager⁠.Click the All tools icon (three horizontal lines) at the top of the page, then click Business Support Home.Click Account Overview (the speedometer icon) in the left-side menu, if necessary. Understanding violationsViolation updates include the following information: Summary of policy violated and link to the policy itself.Examples of which content is allowed or disallowed based on that policy.Whether there are any active restrictions on the account and what happens if the violation happens again.How to avoid future policy violations and links to helpful resources.How to appeal.Notifications about violations are also: Surfaced in the Business Manager Notifications Center and as a banner in WhatsApp Manager.Sent as an email to all admins set in Business Manager. To ensure proper delivery of notifications, please ensure admin information displayed in Business Manager is accurate and up-to-date.Sent as a webhook notification to those subscribed. Enforcement actionsAccounts can become restricted or disabled depending on the number and severity of issues. Specific restrictions can be viewed in Business Support Home along with information on next steps and requesting a review for a particular policy issue.Restricted or disabled accounts can still appeal or acknowledge issues. If issues are reversed following the appeal or acknowledgment, the account returns to its previous status. WebhooksIntegrate with webhooks to receive real-time notifications about changes to a WhatsApp Business Account (WABA). Subscribe to the account_update webhook to receive real-time notifications whenever a WhatsApp Business Account has violated a policy, and when applicable, messaging restriction type and duration. This ensures businesses can quickly adjust behavior to avoid additional warnings and/or enforcement actions. AppealsIf a business believes it is actually compliant with WhatsApp policies, it can appeal the violation by requesting a review. When a business appeals a violation, the WhatsApp team reviews the appeal against the violation policy to make a decision on if the violation should be reconsidered. This review might result in WhatsApp reversing the violation.Note: Not all spam violations might be appealed. Businesses might have to wait until the restriction period ends to begin messaging again.This is how you request a decision review: From the Business Support Home page, select the relevant WhatsApp Business Account.Choose from the list of violations and click Request Review.A new dialog opens in Business Manager. Enter supporting details and click Submit.After submission, the request and the issue are moved to the In Review tab.The appeal review decision will be sent via Business Manager and typically takes 24 to 48 hours. The appealed violation will either remain Unchanged or be set as Reversed. Preventing future violations Read the Commerce⁠ and Business⁠ Policies and review this article⁠ that answers frequently asked questions about these policies.Subscribe to the account_update webhook to receive real-time notifications whenever a Business Account has violated a policy, and when applicable, messaging restriction type and duration.Adjust behavior on the platform quickly to avoid additional warnings and/or enforcement actions.Review best practices for sending high-quality messages on WhatsApp defined in the WhatsApp Business Messaging Policy⁠. Policy Enforcement Violations WhatsApp Business Platform Policy Violations | Developer Documentation WhatsApp Business Platform Policy ViolationsUpdated: Nov 14, 2025We are announcing a structured, consistent approach to how the Commerce and Business Policies are enforced on the WhatsApp Business Platform. See this guide for an overview of how this enforcement system works and the product experience.The list below outlines specific policy violations a business could receive. We may adjust this list over time. Subscribe to the account_update webhooks to get real-time notifications about these policy violations. Violation Description (Click the arrow in the left column for examples, if available) ADULT Businesses may not transact in the sale or use of adult products or services. Examples: Products promoting family planning and contraception, which focus on the contraceptive features of the product, and not on sexual pleasure or sexual enhancementSex toysVideos or live shows for adult entertainmentSexual enhancement productsSexually suggestive services ALCOHOL Businesses may not transact in the sale of alcohol. Examples: Books or DVDs about alcoholAlcohol-related items, including glasses, coolers, and wine bottle holdersAlcoholic beveragesKits for producing alcohol ANIMALS Businesses may not transact in the sale of any animals.Examples: Animal cagesProducts for animals (toys, collars, etc.)Veterinary servicesGrooming services Boarding servicesPet adoption servicesLive animalsLivestockProhibited animal parts, including but not limited to bone, teeth, horn, ivory, taxidermy, organs, external limbs, secretions, or carcassesAny product or part, including but not limited to leather, skin, hide, fur, wool, or hair from any dogs, cats, and endangered or threatened animals BODY_PARTS_FLUIDS Businesses may not transact in the sale of human body parts or fluids. Examples: Blood donation centersBloodHair extensions and wigsUrineBody partsOrgansHuman tissueTeeth DATING Businesses may not transact in or facilitate online dating services. DIGITAL_SERVICES_PRODUCTS Businesses may not transact in the sale, including links to or processing of any subscription sales, renewals, or upgrades, etc., of digital content, digital subscriptions, or digital accounts. Examples: Authentic audio or video CDs, DVDs, and Blu Ray Digital devices, including Smartphones, video game consoles, and TVsDownloadable content, including PDFs, music, games, movies, etc.Digital accounts, including games accountsDigital subscriptions and internet streaming services, including TV, Mobile, etc.Digital coupons DRUGS Businesses may not transact in the sale of illegal, prescription, or recreational drugs. Manufacturers and healthcare services who do not engage in direct sale are allowed. Examples: Drugs, including marijuana and marijuana productsDrug paraphernalia, including pipes and bongsPrescription drugs GAMBLING Businesses may not transact in or facilitate gambling, games of skill, or lotteries, including online casinos, sports books, bingo, or poker if it costs money. HEALTHCARE Businesses may not transact in certain healthcare products, including medical devices, and smoking cessation products containing nicotine. Manufacturers and healthcare services who do not engage in direct sale are allowed. Examples: Medical DevicesLifestyle and fitness accessoriesContact lenses, bandages and braces for physical injuriesThermometersTesting kits for medical conditions or diseasesBreast pumpsFirst-aid kitsSmoking Cessation Products Nicotine patches Nicotine gum ILLEGAL_PRODUCTS Businesses may not transact in the operation or exchange of illegal products or services. MISLEADING WhatsApp prohibits business models, goods, items, or services that we determine may be or are fraudulent, misleading, offensive, or deceptive, or that may be or are exploitative, inappropriate, or exert undue pressure on targeted groups. Examples: Multilevel marketingPenny auctionsICOs and binary optionsPayday loans, paycheck advances, P2P lending, debt collection, and bail bondsDiet, weight loss, or other health related products that imply or attempt to generate negative self-perception OVERTLY_SEXUALIZED_POSITIONING Businesses may not position products or services in a sexually suggestive manner. Examples: Implied nudityImplied sexual actsZoomed-in sexual images REAL_FAKE_CURRENCY Businesses may not transact in the sale of real, virtual, or fake currency. Examples: Real money (cash or cash equivalent instruments and coins)Replica or prop moneyDigital or cryptocurrencyActive bank credit or debit cardsStore credit cards or couponsPre-paid credit or debit cardsChecks or checkbooksEquipment to create counterfeit currency or financial instruments SCAM Businesses may not transact in any activities that promote or facilitate scams. SUPPLEMENTS Businesses may not transact in the sale of unsafe ingestible supplements, as determined by WhatsApp in its sole discretion. Examples: Anabolic steroidsChitosanComfreyDehydroepiandrosteroneEphedraHuman growth hormones THIRD_PARTY_INFRINGEMENTS Transactions may not contain content that infringes upon or violates the intellectual property rights of any third party, including copyright or trademark. This includes, but is not limited to, the sale of counterfeit products, such as goods that copy the trademark (name or logo) and/or distinctive features of another company’s products to imitate a genuine product. Examples: Counterfeits, knockoffs, or replicas of branded goods, or posts offering goods that are likely to confuse consumers about the source, sponsorship or affiliation of those goods.Unauthorized or pirated copies of copyrighted works, such as videos, movies, TV shows and broadcasts, video games, CDs or other musical works, books, etc. TOBACCO Businesses may not transact in the sale of tobacco products or tobacco paraphernalia. Examples: Apparel featuring a tobacco brand logoCigarettes, cigars, and chewing tobaccoTobacco pipes and paraphernalia Tobacco rolling machinesHookahsBongsRolling papersElectronic cigarettes (E-cigarettes) or tobacco devices UNAUTHORIZED_MEDIA Businesses may not transact in the sale of devices that facilitate or encourage streaming digital content in an unauthorized manner or interfering with the functionality of electronic devices. Examples: Add-on equipment for streaming devices such as keyboards and remotesSale of streaming devices loaded with software that facilitates unauthorized access to contentJailbroken or loaded devicesJamming or descrambling devicesWiretapping devices WEAPONS Businesses may not transact in the sale or use of weapons, ammunition, or explosives. Examples: Promoting safety training or licenses for legal weaponsFirearms and firearm partsPaintball gunsBB GunsFireworksPepper sprayTasersGun rangesGun shows Qr Codes QR Codes and Short Links | Developer Documentation QR Codes and Short Links Updated: Oct 31, 2025 WhatsApp QR codes and short links create a digital doorstep for businesses, enabling them to stay connected with their existing customers and connect with new ones. This way, customers can simply scan QR codes with their mobile device camera or type in a short link to begin a chat thread, without needing to input a phone number. You can view, create, edit and delete QR codes and short links in the WhatsApp Business Management API or in the Business Manager UI⁠. Limitations A single WABA phone number cannot be associated with more than 2,000 QR codes and short links. A QR code scan can initiate a pre-filled message containing up to 140 characters of text. Analytics are not available for QR Codes and Short Links as we limit the amount of data we log to protect user privacy. Prefilled messages QR codes and short links can be programmed to populate a prefilled message. Prefilled messages can contain up to 140 characters of text. These messages are fully customizable and can be updated or deleted at any time. User experience User Scenario Expected Behavior User tries to access a code or link that has been deleted. User sees an error message saying “This QR code [short link] has expired”. User scans the QR code or types in the short link of a business they previously blocked. User gets a prompt asking if they would like to unblock the business to continue messaging them. User clicks a short link on a desktop browser. Desktop client launches with message populated in chat thread. If there is no client installed, user is prompted to install it. Best practices Format We recommend outputting the QR code as a scalable vector graphic ( .svg) file. You can resize your QR Code to develop product packaging, signage, etc. Appearance While we do not offer the capability to natively customize QR codes, you can do so by downloading and editing QR codes with the software of your choice. We recommend you do not customize the color or look and feel of the code itself in order to preserve readability. FAQs How do I create a QR code or short link? You can view, create, edit and delete QR codes and short links in the WhatsApp Business Management API or in the Business Manager UI⁠. How many QR codes and short links can I create? A single WABA phone number cannot be associated with more than 2,000 QR codes and short links. What is the best format to use to optimize print quality of a QR code? We recommend the .svg file format for the best quality in print materials. How do short links improve on the existing wa.me links? The new short links enable prefilled messages associated with a link to be edited or deleted at any time. They also reduce the syntax of the URL to a random code, which eliminates the need to embed messages in the URL and masks the phone number. What happens if a user clicks a short link on a desktop? If the user has the WhatsApp desktop client installed, it will launch a chat thread with your business. If not, the user will be prompted to install the WhatsApp desktop client. What happens when a user scans a QR code or clicks a short link that has been deleted? If a user tries to access a QR code or short link that has been deleted, they will see an error message indicating the QR code/short link has expired. How does this differ from QR codes I am already generating in my own development environment today? QR codes can now be generated and managed directly within the WhatsApp Business Management API and users can scan them with their WhatsApp, iOS, or Android camera. In addition, with WhatsApp QR codes Prefilled messages are fully customizable and can be changed or deleted at any time,Users will always go directly to the app without any interstitial page, andThe in-app experience for an expired code sends the user a clear message. How can I ensure the code is scanned by users in the right language? You will be responsible for using the appropriate QR code based on expected location and language of users. Will analytics be available to track QR code scans? Analytics are not available for QR Codes and Short Links as we limit the amount of data we log to protect user privacy. Reference Meta Graph API - Application Connected Client Businesses | Developer Documentation Meta Graph API - Application Connected Client Businesses Copy for LLM View as Markdown Version API for retrieving connected client businesses associated with a Meta application. This endpoint allows applications to retrieve information about businesses that have established client connections through the application. This is essential for managing business relationships and understanding client business configurations. GET /{Version}/{Application-ID}/connected_client_businesses Retrieve a list of client businesses connected to the specified application. Use Cases: Monitor application-business client relationships Verify connected business configurations Retrieve business connection status and details Manage client business access and permissions Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Business connection data can be cached for moderate periods, but status information may change. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Application-IDstring·required Your Meta Application ID. This ID is provided when you create the application and can be found in your App Dashboard. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name, verification_status, business_status). Available fields: id, name, verification_status, business_status, created_time, updated_time limitinteger [min: 1, max: 100] Maximum number of connected client businesses to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. beforestring Cursor for pagination. Use this to get the previous page of results. Responses Retrieve a list of client businesses connected to the specified application. Use Cases: Monitor application-business client relationships Verify connected business configurations Retrieve business connection status and details Manage client business access and permissions Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Business connection data can be cached for moderate periods, but status information may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved connected client businesses Content Type: application/json Schema: ConnectedClientBusinessesResponse Show child attributes ConnectedClientBusinessesResponse dataarray of ConnectedClientBusiness Array of connected client businesses Show child attributes data[]ConnectedClientBusiness Connected client business information and configuration Show child attributes idstring·required Unique identifier for the connected client business namestring·required Name of the connected client business verification_statusBusinessVerificationStatus Verification status of the connected client business business_statusBusinessStatus Current status of the connected client business created_timestring (date-time) Timestamp when the business connection was created updated_timestring (date-time) Timestamp when the business connection was last updated pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data afterstring Cursor pointing to the end of the page of data previousstring URL for the previous page of results nextstring URL for the next page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Application ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Management - Add Phone Numbers API | Developer Documentation WhatsApp Business Management - Add Phone Numbers API Copy for LLM View as Markdown Version API for adding phone numbers to a WhatsApp Business Account. This endpoint allows businesses to add phone numbers to their WhatsApp Business Account for messaging purposes. POST /{Version}/{Business-ID}/add_phone_numbers Add a preverified phone number to a WhatsApp Business Account. This endpoint is used by Partners to create a pool of Partner owned numbers that end clients can purchase. Use Cases: Add new phone numbers to scale messaging operations Set up phone numbers for different business locations Manage phone number inventory for business messaging Configure phone numbers for specific messaging workflows Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Phone Number Requirements: Must be in E.164 format (e.g., +1234567890) Must not be already registered to another WhatsApp Business Account Must be capable of receiving SMS for verification Must comply with WhatsApp's business messaging policies Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your WhatsApp Business Account ID. This ID can be found in your Business Manager or through business management APIs. Required Phone number to add to the business account Content Type: application/json Schema: AddPhoneNumbersRequest Show child attributes AddPhoneNumbersRequest phone_numberstring·required Phone number to add to the business account. Accepts E.164 format or formatted numbers with spaces, hyphens, and parentheses (e.g., +1234567890, +1 (631) 555-1000, +1-631-555-1000). The phone number will be normalized and validated by the endpoint. Responses Add a preverified phone number to a WhatsApp Business Account. This endpoint is used by Partners to create a pool of Partner owned numbers that end clients can purchase. Use Cases: Add new phone numbers to scale messaging operations Set up phone numbers for different business locations Manage phone number inventory for business messaging Configure phone numbers for specific messaging workflows Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Phone Number Requirements: Must be in E.164 format (e.g., +1234567890) Must not be already registered to another WhatsApp Business Account Must be capable of receiving SMS for verification Must comply with WhatsApp's business messaging policies 200 Phone number successfully added Content Type: application/json Schema: AddPhoneNumbersResponse Show child attributes AddPhoneNumbersResponse idstring·required Unique identifier for the preverified phone number entity that was created 400 Bad Request - Invalid parameters, malformed request, or phone number already registered Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Business Account API | Developer Documentation WhatsApp Cloud API - Business Account API Copy for LLM View as Markdown Version Retrieve Meta Business Portfolio information by Business ID. Returns business name, timezone, and other account details for managing WhatsApp Business Account configurations. Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Management API - Owned WhatsApp Business Accounts | Developer Documentation WhatsApp Business Management API - Owned WhatsApp Business Accounts Copy for LLM View as Markdown Version API for retrieving WhatsApp Business Accounts owned by a specific business. This endpoint allows businesses to retrieve comprehensive information about their owned WhatsApp Business Accounts, including account details, status, and configuration. GET /{Version}/{Business-ID}/owned_whatsapp_business_accounts Retrieve WhatsApp Business Accounts owned by the specified business. This endpoint provides comprehensive information about all WABAs owned by the business, including account details, configuration, and status information. Use Cases: Retrieve all WhatsApp Business Accounts owned by a business Filter accounts by business type Find specific accounts by ID Monitor business portfolio of WhatsApp Business Accounts Manage account access and permissions across multiple WABAs Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Account information can be cached for short periods, but status and configuration may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your Business ID. This ID represents the business portfolio that owns the WhatsApp Business Accounts and can be found in your Business Manager settings. Query Parameters business_typearray of WhatsAppBusinessType Filter accounts by business type. Can specify multiple types as comma-separated values. Use this to filter between enterprise and small-medium business accounts. afterstring Cursor for forward pagination. Use the cursor from the previous response to get the next page of results. firstinteger [min: 1, max: 100] Number of results to return in forward pagination. Maximum value is 100. Use with 'after' cursor for forward pagination. beforestring Cursor for backward pagination. Use the cursor from the previous response to get the previous page of results. lastinteger [min: 1, max: 100] Number of results to return in backward pagination. Maximum value is 100. Use with 'before' cursor for backward pagination. findstring Find a specific WhatsApp Business Account by ID within the owned accounts. Use this to quickly locate a specific account. Responses Retrieve WhatsApp Business Accounts owned by the specified business. This endpoint provides comprehensive information about all WABAs owned by the business, including account details, configuration, and status information. Use Cases: Retrieve all WhatsApp Business Accounts owned by a business Filter accounts by business type Find specific accounts by ID Monitor business portfolio of WhatsApp Business Accounts Manage account access and permissions across multiple WABAs Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Account information can be cached for short periods, but status and configuration may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved owned WhatsApp Business Accounts Content Type: application/json Schema: WhatsAppBusinessAccountsConnection Show child attributes WhatsAppBusinessAccountsConnection dataarray of WhatsAppBusinessAccount·required Array of owned WhatsApp Business Account records Show child attributes data[]WhatsAppBusinessAccount WhatsApp Business Account owned by the business Show child attributes idstring·required Unique identifier for the WhatsApp Business Account namestring·required Human-readable name of the WhatsApp Business Account message_template_namespacestring·required Namespace identifier for message templates associated with this account timezone_idstring·required Timezone identifier for the WhatsApp Business Account pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring URL for the next page of results previousstring URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Accounts API | Developer Documentation WhatsApp Business Accounts API Copy for LLM View as Markdown Version API for managing WhatsApp Business Accounts under a business portfolio. This endpoint allows businesses to retrieve and create WhatsApp Business Accounts (WABAs) for messaging and business communication purposes. WABAs can be associated with the specified business portfolio and configured with the provided parameters. GET /{Version}/{Business-ID}/whatsapp_business_accounts Retrieve a list of WhatsApp Business Accounts owned by the specified business portfolio. This endpoint provides information about WhatsApp Business Accounts that are owned by the business, including their configuration, status, and core properties. This corresponds to the GraphBusinessWhatsAppBusinessAccountsEdge functionality. Use Cases: Retrieve list of owned WhatsApp Business Accounts Monitor WABA status and configuration Verify WABA details for business integrations Manage business WhatsApp messaging setups Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: WABA information can be cached for moderate periods, but status information may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your business portfolio ID. This ID can be found in the Meta Business Suite or through business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name, currency, timezone_id). Available fields: id, name, account_review_status, purchase_order_number, currency, timezone_id, business_verification_status, country, on_behalf_of_business_info, is_enabled_for_insights, message_template_namespace business_typearray of One of "ENTERPRISE", "SMB" Filter results by WhatsApp Business Account type limitinteger [min: 1, max: 100] Maximum number of WhatsApp Business Accounts to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. beforestring Cursor for pagination. Use this to get the previous page of results. findstring Find a specific WhatsApp Business Account by ID Responses Retrieve a list of WhatsApp Business Accounts owned by the specified business portfolio. This endpoint provides information about WhatsApp Business Accounts that are owned by the business, including their configuration, status, and core properties. This corresponds to the GraphBusinessWhatsAppBusinessAccountsEdge functionality. Use Cases: Retrieve list of owned WhatsApp Business Accounts Monitor WABA status and configuration Verify WABA details for business integrations Manage business WhatsApp messaging setups Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: WABA information can be cached for moderate periods, but status information may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Business Accounts Content Type: application/json Schema: WhatsAppBusinessAccountsResponse Show child attributes WhatsAppBusinessAccountsResponse dataarray of WhatsAppBusinessAccount Array of WhatsApp Business Accounts Show child attributes data[]WhatsAppBusinessAccount WhatsApp Business Account details and configuration Show child attributes idstring·required Unique identifier for the WhatsApp Business Account namestring·required Human-readable name of the WhatsApp Business Account account_review_statusAccountReviewStatus Review status of the WhatsApp Business Account purchase_order_numberstring Purchase order number associated with the account currencystring Currency code for the WABA (ISO 4217 format) timezone_idstring Timezone identifier for the WABA business_verification_statusBusinessVerificationStatus Verification status of the business associated with the WABA countrystring Country code where the WABA is registered on_behalf_of_business_infoOnBehalfOfBusinessInfo Information about the business on whose behalf the WABA operates Show child attributes idstring Business ID namestring Business name is_enabled_for_insightsboolean Whether insights are enabled for this WABA message_template_namespacestring Namespace for message templates pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data afterstring Cursor pointing to the end of the page of data previousstring URL for the previous page of results nextstring URL for the next page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{Business-ID}/whatsapp_business_accounts Create a new WhatsApp Business Account under the specified business portfolio. This endpoint creates a new WABA with the provided configuration and associates it with the business portfolio. The account will be set up with the specified payment method and business settings. Rate Limiting: Standard Graph API rate limits apply. Account creation may have additional rate limits to prevent abuse. Business Logic: Account name must be unique within the business portfolio Payment method must be valid and active Business must have appropriate permissions for WABA creation Created account will be in pending state until verification is complete Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your business portfolio ID. This ID can be found in the Meta Business Suite or through business management APIs. Required Content Type: application/json Schema: WhatsAppBusinessAccountCreationRequest Show child attributes WhatsAppBusinessAccountCreationRequest namestring·required Human-readable name for the WhatsApp Business Account primary_funding_idstring ID of the primary funding source (credit card or extended credit) purchase_order_numberstring Purchase order number for billing reference currencystring Currency code for billing (ISO 4217 format) timezone_idinteger Timezone ID for the account business_typeWhatsAppBusinessType Type of WhatsApp Business Account on_behalf_of_business_idstring Business ID when creating account on behalf of another business Responses Create a new WhatsApp Business Account under the specified business portfolio. This endpoint creates a new WABA with the provided configuration and associates it with the business portfolio. The account will be set up with the specified payment method and business settings. Rate Limiting: Standard Graph API rate limits apply. Account creation may have additional rate limits to prevent abuse. Business Logic: Account name must be unique within the business portfolio Payment method must be valid and active Business must have appropriate permissions for WABA creation Created account will be in pending state until verification is complete 200 Successfully created WhatsApp Business Account Content Type: application/json Schema: WhatsAppBusinessAccountCreationResponse Show child attributes WhatsAppBusinessAccountCreationResponse idstring·required Unique identifier for the created WhatsApp Business Account payment_account_idstring·required ID of the associated payment account for billing 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Partner Onboarding to MM Lite API | Developer Documentation WhatsApp Business Partner Onboarding to MM Lite APICopy for LLMView as MarkdownVersionAPI for onboarding partners to WhatsApp Business MM Lite partnerships.This endpoint enables solution partners to initiate MM Lite onboarding requests to end businesses.The API validates eligibility, creates business agreement requests, and automatically configuresOBO (On Behalf Of) WABA mobility intents for eligible WhatsApp Business Accounts.Core Functionality:Validates partner business and application ownershipChecks end business eligibility for MM Lite partnershipsIdentifies eligible shared WABAs and OBO WABAs associated with the partnershipAutomatically sets mobility intents on eligible OBO WABAs (BSPs only)Creates a business agreement request with MM_LITE_ONBOARDING typeReturns a unique request ID for tracking the onboarding process WhatsApp Business Pre-Verified Phone Numbers API | Developer Documentation WhatsApp Business Pre-Verified Phone Numbers API Copy for LLM View as Markdown Version API for retrieving pre-verified phone numbers associated with a WhatsApp Business Account. This endpoint allows businesses to retrieve information about pre-verified phone numbers that are available for use with their WhatsApp Business Account. GET /{Version}/{Business-ID}/preverified_numbers Retrieve pre-verified phone numbers available for use with the specified business. This endpoint provides information about phone numbers that have been pre-verified and are ready for immediate use with WhatsApp Business messaging operations. Use Cases: Retrieve available pre-verified phone numbers for business messaging setup Check verification status and availability of phone numbers Monitor pre-verified phone number inventory Validate phone number options before WhatsApp Business Account configuration Facilitate quick business messaging setup with pre-verified numbers Filtering and Pagination: Results can be filtered by verification status, availability, and country Cursor-based pagination is supported for large result sets Default page size is 25 items, maximum is 100 items per page Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number information can be cached for short periods, but availability status may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your Business ID for which to retrieve pre-verified phone numbers. This ID can be found in your Meta Business Manager or through business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, display_phone_number, verification_status). Available fields: id, display_phone_number, country_prefix, verification_status, availability_status, created_time, last_updated, supported_features, country_code, region limitinteger [min: 1, max: 100] Maximum number of phone numbers to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to retrieve the next page of results. This value is provided in the 'paging' object of previous responses. beforestring Cursor for pagination. Use this to retrieve the previous page of results. This value is provided in the 'paging' object of previous responses. verification_statusPhoneNumberVerificationStatus Filter results by verification status. Only phone numbers with the specified verification status will be returned. availability_statusPhoneNumberAvailabilityStatus Filter results by availability status. Only phone numbers with the specified availability status will be returned. country_codestring Filter results by country code. Only phone numbers from the specified country will be returned. Use ISO 3166-1 alpha-2 country codes. Responses Retrieve pre-verified phone numbers available for use with the specified business. This endpoint provides information about phone numbers that have been pre-verified and are ready for immediate use with WhatsApp Business messaging operations. Use Cases: Retrieve available pre-verified phone numbers for business messaging setup Check verification status and availability of phone numbers Monitor pre-verified phone number inventory Validate phone number options before WhatsApp Business Account configuration Facilitate quick business messaging setup with pre-verified numbers Filtering and Pagination: Results can be filtered by verification status, availability, and country Cursor-based pagination is supported for large result sets Default page size is 25 items, maximum is 100 items per page Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number information can be cached for short periods, but availability status may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved pre-verified phone numbers Content Type: application/json Schema: PreVerifiedPhoneNumbersResponse Show child attributes PreVerifiedPhoneNumbersResponse dataarray of PreVerifiedPhoneNumber·required List of pre-verified phone numbers Show child attributes data[]PreVerifiedPhoneNumber Pre-verified phone number details and status information Show child attributes idstring·required Unique identifier for the pre-verified phone number display_phone_numberstring·required Formatted display version of the phone number country_prefixinteger [min: 1, max: 999] Country code prefix for the phone number verification_statusPhoneNumberVerificationStatus·required Current verification status of the pre-verified phone number availability_statusPhoneNumberAvailabilityStatus Current availability status of the pre-verified phone number created_timestring (date-time) Timestamp when the phone number was pre-verified last_updatedstring (date-time) Timestamp when the phone number information was last updated supported_featuresarray of WhatsAppBusinessFeature List of WhatsApp Business features supported by this phone number Show child attributes supported_features[]WhatsAppBusinessFeature WhatsApp Business features supported by the phone number country_codestring ISO 3166-1 alpha-2 country code for the phone number regionstring Geographic region or area for the phone number pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Pre-Verified Phone Numbers API | Developer Documentation WhatsApp Business Pre-Verified Phone Numbers API Copy for LLM View as Markdown Version API for retrieving pre-verified phone numbers associated with a WhatsApp Business Account. This endpoint allows businesses to retrieve information about pre-verified phone numbers that are available for use with their WhatsApp Business Account. GET /{Version}/{Business-ID}/preverified_numbers Retrieve pre-verified phone numbers available for use with the specified business. This endpoint provides information about phone numbers that have been pre-verified and are ready for immediate use with WhatsApp Business messaging operations. Use Cases: Retrieve available pre-verified phone numbers for business messaging setup Check verification status and availability of phone numbers Monitor pre-verified phone number inventory Validate phone number options before WhatsApp Business Account configuration Facilitate quick business messaging setup with pre-verified numbers Filtering and Pagination: Results can be filtered by verification status, availability, and country Cursor-based pagination is supported for large result sets Default page size is 25 items, maximum is 100 items per page Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number information can be cached for short periods, but availability status may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Business-IDstring·required Your Business ID for which to retrieve pre-verified phone numbers. This ID can be found in your Meta Business Manager or through business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, display_phone_number, verification_status). Available fields: id, display_phone_number, country_prefix, verification_status, availability_status, created_time, last_updated, supported_features, country_code, region limitinteger [min: 1, max: 100] Maximum number of phone numbers to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to retrieve the next page of results. This value is provided in the 'paging' object of previous responses. beforestring Cursor for pagination. Use this to retrieve the previous page of results. This value is provided in the 'paging' object of previous responses. verification_statusPhoneNumberVerificationStatus Filter results by verification status. Only phone numbers with the specified verification status will be returned. availability_statusPhoneNumberAvailabilityStatus Filter results by availability status. Only phone numbers with the specified availability status will be returned. country_codestring Filter results by country code. Only phone numbers from the specified country will be returned. Use ISO 3166-1 alpha-2 country codes. Responses Retrieve pre-verified phone numbers available for use with the specified business. This endpoint provides information about phone numbers that have been pre-verified and are ready for immediate use with WhatsApp Business messaging operations. Use Cases: Retrieve available pre-verified phone numbers for business messaging setup Check verification status and availability of phone numbers Monitor pre-verified phone number inventory Validate phone number options before WhatsApp Business Account configuration Facilitate quick business messaging setup with pre-verified numbers Filtering and Pagination: Results can be filtered by verification status, availability, and country Cursor-based pagination is supported for large result sets Default page size is 25 items, maximum is 100 items per page Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number information can be cached for short periods, but availability status may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved pre-verified phone numbers Content Type: application/json Schema: PreVerifiedPhoneNumbersResponse Show child attributes PreVerifiedPhoneNumbersResponse dataarray of PreVerifiedPhoneNumber·required List of pre-verified phone numbers Show child attributes data[]PreVerifiedPhoneNumber Pre-verified phone number details and status information Show child attributes idstring·required Unique identifier for the pre-verified phone number display_phone_numberstring·required Formatted display version of the phone number country_prefixinteger [min: 1, max: 999] Country code prefix for the phone number verification_statusPhoneNumberVerificationStatus·required Current verification status of the pre-verified phone number availability_statusPhoneNumberAvailabilityStatus Current availability status of the pre-verified phone number created_timestring (date-time) Timestamp when the phone number was pre-verified last_updatedstring (date-time) Timestamp when the phone number information was last updated supported_featuresarray of WhatsAppBusinessFeature List of WhatsApp Business features supported by this phone number Show child attributes supported_features[]WhatsAppBusinessFeature WhatsApp Business features supported by the phone number country_codestring ISO 3166-1 alpha-2 country code for the phone number regionstring Geographic region or area for the phone number pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Business does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Cloud API - Groups Invite Link API | Developer Documentation WhatsApp Business Cloud API - Groups Invite Link API Copy for LLM View as Markdown Version The Groups API gives you simple functions to control groups through their lifecycle. When you create a new group, an invite link is created for inviting participants to the group. Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users who you would like to join the group. Select language Select status code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Cloud API - Groups Join Requests API | Developer Documentation WhatsApp Business Cloud API - Groups Join Requests API Copy for LLM View as Markdown Version The Groups API gives you simple functions to control groups through their lifecycle. When you create a new group, an invite link is created for inviting participants to the group. Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users who you would like to join the group. Select language POST /{Version}/{group_id}/join_requests Approve one or more join requests Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required group_idstring·required Group ID Required Content Type: application/json Schema: object Show child attributes messaging_product"whatsapp"·required join_requestsarray of string·required Array of join request IDs to approve Show child attributes join_requests[]string Join request ID Responses Approve one or more join requests 200 Join requests approval response Content Type: application/json Schema: object Show child attributes messaging_productstring approved_join_requestsarray of string Show child attributes approved_join_requests[]string ID of approved join request failed_join_requestsarray of object Show child attributes failed_join_requests[]object Show child attributes join_request_idstring errorsarray of Error Show child attributes errors[]Error Show child attributes codeinteger Error code messagestring Error message titlestring Error title error_dataobject Show child attributes detailsstring Error details errorsarray of Error Show child attributes errors[]Error Show child attributes codeinteger Error code messagestring Error message titlestring Error title error_dataobject Show child attributes detailsstring Error details Select language Select status code DELETE /{Version}/{group_id}/join_requests Reject one or more join requests Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required group_idstring·required Group ID Required Content Type: application/json Schema: object Show child attributes messaging_product"whatsapp"·required join_requestsarray of string·required Array of join request IDs to reject Show child attributes join_requests[]string Join request ID Responses Reject one or more join requests 200 Join requests rejection response Content Type: application/json Schema: object Show child attributes messaging_productstring rejected_join_requestsarray of string Show child attributes rejected_join_requests[]string ID of rejected join request failed_join_requestsarray of object Show child attributes failed_join_requests[]object Show child attributes join_request_idstring errorsarray of Error Show child attributes errors[]Error Show child attributes codeinteger Error code messagestring Error message titlestring Error title error_dataobject Show child attributes detailsstring Error details errorsarray of Error Show child attributes errors[]Error Show child attributes codeinteger Error code messagestring Error message titlestring Error title error_dataobject Show child attributes detailsstring Error details Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Cloud API - Groups Participants API | Developer Documentation WhatsApp Business Cloud API - Groups Participants API Copy for LLM View as Markdown Version The Groups API gives you simple functions to control groups through their lifecycle. When you create a new group, an invite link is created for inviting participants to the group. Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users who you would like to join the group. Select language Select language Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Cloud API - Groups Query API | Developer Documentation WhatsApp Business Cloud API - Groups Query API Copy for LLM View as Markdown Version The Groups API gives you simple functions to control groups through their lifecycle. When you create a new group, an invite link is created for inviting participants to the group. Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users who you would like to join the group. Select language Select language Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Media API | Developer Documentation WhatsApp Cloud API - Media API Copy for LLM View as Markdown Version Retrieve and delete uploaded media files by media ID. Get media URLs with file metadata including size, MIME type, and SHA256 hash. Media URLs are valid for 5 minutes after retrieval. Select language Select status code DELETE /{Version}/{Media-ID} To delete media, make a DELETE call to the ID of the media you want to delete. Prerequisites User Access Token with whatsapp_business_messaging permission Media object ID from either uploading media endpoint or media message Webhooks Responses To delete media, make a DELETE call to the ID of the media you want to delete. Prerequisites User Access Token with whatsapp_business_messaging permission Media object ID from either uploading media endpoint or media message Webhooks 200 Delete Media Content Type: application/json Schema: object Show child attributes successboolean Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Media Download API | Developer Documentation WhatsApp Cloud API - Media Download API Copy for LLM View as Markdown Version Download media files using URLs obtained from media retrieval endpoints. Returns binary media content with appropriate MIME type headers. Media URLs expire after 5 minutes and must be re-retrieved if expired. Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Message History Events API | Developer Documentation WhatsApp Business Message History Events API Copy for LLM View as Markdown Version API for retrieving WhatsApp Business Message History Events and delivery status occurrences. This endpoint allows businesses to retrieve detailed message delivery status events for specific message history entries, including delivery status transitions, timestamps, and application information. GET /{Version}/{Message-History-ID}/events Retrieve paginated message delivery status events for a specific message history entry, including delivery status occurrences, timestamps, and application information. Use Cases: Track detailed message delivery status events and transitions Monitor delivery status occurrence timestamps Retrieve application information for delivery events Debug message delivery issues and status changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Message history events can be cached for short periods, but delivery status events may change frequently. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination. Use the after and before cursors from the response to navigate through results. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Message-History-IDstring·required Your WhatsApp Business Message History ID. This ID is provided when you retrieve message history and can be found through message history APIs. Query Parameters status_filterWhatsAppMessageDeliveryStatus Filter results by specific delivery status. When provided, only events with this delivery status will be returned. fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (cursor, node{id,delivery_status,occurrence_timestamp}). Available fields: cursor, node{id,delivery_status,error_description,occurrence_timestamp,status_timestamp,application} limitinteger [min: 1, max: 100] Maximum number of message history events to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. This value comes from the paging.cursors.after field in previous responses. beforestring Cursor for pagination. Use this to get the previous page of results. This value comes from the paging.cursors.before field in previous responses. Responses Retrieve paginated message delivery status events for a specific message history entry, including delivery status occurrences, timestamps, and application information. Use Cases: Track detailed message delivery status events and transitions Monitor delivery status occurrence timestamps Retrieve application information for delivery events Debug message delivery issues and status changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Message history events can be cached for short periods, but delivery status events may change frequently. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination. Use the after and before cursors from the response to navigate through results. 200 Successfully retrieved WhatsApp message history events Content Type: application/json Schema: MessageHistoryEventsResponse Show child attributes MessageHistoryEventsResponse dataarray of WhatsAppMessageHistoryEventsEdge Array of message history event edges Show child attributes data[]WhatsAppMessageHistoryEventsEdge Edge containing message delivery status occurrence with pagination cursor Show child attributes cursorstring Pagination cursor for this edge nodeWhatsAppBusinessMessageDeliveryStatusOccurrence·required Message delivery status occurrence with detailed event information Show child attributes idstring·required Unique identifier for the message delivery status occurrence delivery_statusWhatsAppMessageDeliveryStatus·required Message delivery status error_descriptionstring Error description if the delivery encountered an error occurrence_timestampinteger (int64)·required Unix timestamp when the delivery status occurrence happened status_timestampinteger (int64) Unix timestamp when the status was recorded applicationApplicationNode Meta application that processed the delivery status event Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application pagingPaginationInfo Pagination information for navigating through results Show child attributes cursorsobject Pagination cursors for navigation Show child attributes beforestring Cursor for the previous page of results afterstring Cursor for the next page of results previousstring (uri) URL for the previous page of results nextstring (uri) URL for the next page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Message History ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business - Assigned WhatsApp Business Accounts API | Developer Documentation WhatsApp Business - Assigned WhatsApp Business Accounts API Copy for LLM View as Markdown Version API for retrieving WhatsApp Business Accounts that have been assigned to a specific user. This endpoint allows apps to retrieve WhatsApp Business Accounts that are assigned to specific users. GET /{Version}/{User-ID}/assigned_whatsapp_business_accounts Retrieve WhatsApp Business Accounts that have been assigned to a specific user. This endpoint provides information about account assignments, permissions, and current status corresponding to the GraphAssignedWhatsAppBusinessAccountsEdge node. Use Cases: Retrieve all WhatsApp Business Accounts assigned to a user Check user permissions for specific accounts Monitor account assignment status and changes Validate user access before performing business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Assignment information can be cached for short periods, but permissions and status may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. User-IDstring·required The user ID for whom to retrieve assigned WhatsApp Business Accounts. This must be a valid user ID within your solution or partnership. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name, status). Available fields: id, name, status, assignment_date, permissions, business_id, phone_numbers limitinteger [min: 1, max: 100] Maximum number of accounts to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. beforestring Cursor for pagination. Use this to get the previous page of results. Responses Retrieve WhatsApp Business Accounts that have been assigned to a specific user. This endpoint provides information about account assignments, permissions, and current status corresponding to the GraphAssignedWhatsAppBusinessAccountsEdge node. Use Cases: Retrieve all WhatsApp Business Accounts assigned to a user Check user permissions for specific accounts Monitor account assignment status and changes Validate user access before performing business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Assignment information can be cached for short periods, but permissions and status may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved assigned WhatsApp Business Accounts Content Type: application/json Schema: AssignedAccountsResponse Show child attributes AssignedAccountsResponse dataarray of AssignedWhatsAppBusinessAccount·required List of assigned WhatsApp Business Accounts Show child attributes data[]AssignedWhatsAppBusinessAccount WhatsApp Business Account assigned to a user Show child attributes idstring·required Unique identifier for the WhatsApp Business Account namestring·required Display name of the WhatsApp Business Account statusWhatsAppBusinessAccountStatus·required Current status of the WhatsApp Business Account assignment_datestring (date-time) Date and time when the account was assigned to the user permissionsarray of WhatsAppBusinessAccountPermission List of permissions granted to the user for this account Show child attributes permissions[]WhatsAppBusinessAccountPermission Permission level for WhatsApp Business Account access business_idstring Business ID that owns this WhatsApp Business Account phone_numbersarray of PhoneNumberInfo Phone numbers associated with this WhatsApp Business Account Show child attributes phone_numbers[]PhoneNumberInfo Phone number information for WhatsApp Business Account Show child attributes idstring Phone number ID display_phone_numberstring Formatted phone number for display verified_namestring Verified business name for this phone number statusOne of "CONNECTED", "DISCONNECTED", "MIGRATED", "PENDING", "DELETED" Status of the phone number pagingPagingInfo Pagination information for the response Show child attributes cursorsobject Show child attributes beforestring Cursor for the previous page afterstring Cursor for the next page nextstring URL for the next page of results previousstring URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - User ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Incoming Webhook Payload | Developer Documentation WhatsApp Incoming Webhook Payload Copy for LLM View as Markdown Version Schemas for incoming WhatsApp webhook notifications. Defines payload structures for messages, status updates, and user interactions sent from WhatsApp users to businesses via webhooks. POST /whatsapp/webhooks Endpoint for receiving webhook payloads for diverse incoming WhatsApp message types. Request Syntax Select language Required Content Type: application/json Schema: WebhookPayload Show child attributes WebhookPayload objectstring·required Always 'whatsapp_business_account' for these webhooks. entryarray of Entry·required Show child attributes entry[]Entry Show child attributes idstring·required WhatsApp Business Account ID. changesarray of Change·required Show child attributes changes[]Change Show child attributes valueMust be one of: IncomingMessageValueGeneral, IncomingMessageValueSystem, StatusMessageValue, GroupValue·required Show child attributes IncomingMessageValueGeneral Show child attributes messaging_productstring·required Always 'whatsapp'. metadataMetadata·required Show child attributes display_phone_numberstring·required Business display phone number. phone_number_idstring·required Business phone number ID. contactsarray of ContactProfile·required Array of contact profiles for the sender. Included for all non-system incoming messages. Show child attributes contacts[]ContactProfile Show child attributes profileobject·required Show child attributes namestring·required WhatsApp user's name as it appears in their profile in the WhatsApp client. wa_idstring WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. messagesarray of IncomingMessage·required Array of message objects. The structure varies based on the 'type' property. Show child attributes messages[]IncomingMessage Show child attributes TextMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"text"·required textobject·required Show child attributes bodystring·required Text body of the message. contextobject Only included if message via a "Message business" button. Show child attributes fromstring·required Business display phone number. idstring·required WhatsApp message ID of the message the user used to access the "Message business" button. referred_productobject·required Show child attributes catalog_idstring·required Product catalog ID. product_retailer_idstring·required Product ID. referralobject Only included if message via a Click to WhatsApp ad. Show child attributes source_urlstring·required Ad URL. source_idstring·required Ad ID. source_typeOne of "ad", "post"·required bodystring·required Ad primary text. headlinestring·required Ad headline. media_typeOne of "image", "video"·required image_urlstring Only included for image media_type. video_urlstring Only included for video media_type. thumbnail_urlstring Only included for video media_type. ctwa_clidstring·required Ad click ID. welcome_messageobject Show child attributes textstring·required Ad greeting text. ReactionMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"reaction"·required reactionobject·required Show child attributes message_idstring·required WhatsApp message ID of the message the WhatsApp user reacted to. emojistring·required Emoji sent by the WhatsApp user as a reaction. AudioMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"audio"·required audioobject Show child attributes mime_typestring·required Media asset MIME type. sha256string·required Media asset SHA-256 hash. idstring·required Media asset ID. A GET request on this ID can provide the asset URL. voiceboolean·required Boolean indicating if audio is a recording made with the WhatsApp client voice recording feature (true) or not (false). DocumentMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"document"·required documentobject Show child attributes mime_typestring·required Media asset MIME type. sha256string·required Media asset SHA-256 hash. idstring·required Media asset ID. A GET request on this ID can provide the asset URL. filenamestring·required Media asset filename. ImageMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"image"·required imageobject Show child attributes mime_typestring·required Media asset MIME type. sha256string·required Media asset SHA-256 hash. idstring·required Media asset ID. A GET request on this ID can provide the asset URL. captionstring Media asset caption text. StickerMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"sticker"·required stickerobject Show child attributes mime_typestring·required Media asset MIME type. sha256string·required Media asset SHA-256 hash. idstring·required Media asset ID. A GET request on this ID can provide the asset URL. animatedboolean·required Boolean indicating if the sticker is animated (true) or not (false). VideoMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"video"·required videoobject Show child attributes mime_typestring·required Media asset MIME type. sha256string·required Media asset SHA-256 hash. idstring·required Media asset ID. A GET request on this ID can provide the asset URL. captionstring Media asset caption text. LocationMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"location"·required locationobject·required Show child attributes addressstring·required Location address. latitudenumber (float)·required Location latitude. longitudenumber (float)·required Location longitude. namestring·required Location name. urlstring Location URL. Usually only included for business locations. ContactSharingMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"contacts"·required contactsarray of ContactObject·required Array of contact objects. Many contact object properties may be omitted if the WhatsApp user chooses not to share them, or their device prevents them from being shared. Show child attributes contacts[]object Show child attributes addressesarray of object Show child attributes addresses[]object Show child attributes citystring City mentioned in the contact address countrystring Country mentioned in the contact address Show child attributes country_codestring ISO country code for the contact address statestring State mentioned in the contact address streetstring Street mentioned in the contact address typestring Type of address, such as home or work zipstring Zip code in the contact address birthdaystring (date) Contact birthday (YYYY-MM-DD). emailsarray of object Show child attributes emails[]object Show child attributes emailstring (email) Email address of the contact typestring Type of email, such as personal or work nameobject Show child attributes formatted_namestring·required Contact's formatted name first_namestring Contact’s first name last_namestring Contact’s last name middle_namestring Contact’s middle name suffixstring Contact’s name suffix prefixstring Contact’s name prefix orgobject Show child attributes companystring Name of the company where the contact works departmentstring Name of the department where the contact works titlestring Contact's job title phonesarray of object Show child attributes phones[]object Show child attributes phonestring Contact’s Phone number wa_idstring Contact's WhatsApp Number. Note that a WhatsApp user's ID and phone number may not always match. typestring Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. urlsarray of object Show child attributes urls[]object Show child attributes urlstring (uri) Website URL associated with the contact or their company typestring Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. UnsupportedMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. typeOne of "unsupported", "unknown"·required contextobject·required Show child attributes fromstring·required Business display phone number. idstring·required WhatsApp message ID of the message containing the button the WhatsApp user tapped. buttonobject·required Show child attributes payloadstring·required Quick-reply button payload. textstring·required Quick-reply button label text. ButtonMessage InteractiveMessageReply Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"interactive"·required contextobject·required Show child attributes fromstring·required Business display phone number. idstring·required WhatsApp message ID of the message containing the interactive component the user tapped. interactiveobject·required Show child attributes typeOne of "list_reply", "button_reply"·required Type of interactive reply (list_reply or button_reply). OrderMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"order"·required orderobject·required Show child attributes catalog_idstring·required Product catalog ID. textstring·required Empty string. product_itemsarray of object·required Show child attributes product_items[]object Show child attributes product_retailer_idstring·required Product ID. quantityinteger·required Product quantity. item_pricenumber (float)·required Individual product price. currencystring·required Catalog currency code. IncomingMessageValueSystem Show child attributes messaging_productstring·required Always 'whatsapp'. metadataMetadata·required Show child attributes display_phone_numberstring·required Business display phone number. phone_number_idstring·required Business phone number ID. messagesarray of SystemMessage·required Array containing only 'system' message objects. Show child attributes messages[]SystemMessage Show child attributes fromstring·required WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. idstring·required Unique WhatsApp message ID. timestampstring·required Unix timestamp indicating when the webhook was triggered. type"system"·required systemobject·required Show child attributes bodystring·required Description of the system change (e.g., user changed number). wa_idstring New WhatsApp user ID. type"user_changed_number"·required Type of system message. notunknown StatusMessageValue Show child attributes messaging_productstring·required Always 'whatsapp'. metadataMetadata·required Show child attributes display_phone_numberstring·required Business display phone number. phone_number_idstring·required Business phone number ID. statusesarray of Statuses·required Array of status objects. Show child attributes statuses[]Statuses Show child attributes idstring·required Unique WhatsApp message ID the status is associated with. statusOne of "sent", "delivered", "read", "failed"·required timestampstring·required recipient_idstring·required Recipeint phone number. group_idstring Group ID if the message was sent to a group. conversationConversation Show child attributes idstring expiration_timestampstring originConversationOrigin Show child attributes typestring pricingPricing Show child attributes billableboolean pricing_modelOne of "CBP", "PMP" categorystring errorsarray of StatusError Show child attributes errors[]StatusError Show child attributes codeinteger titlestring messagestring error_dataErrorData Show child attributes detailsstring hrefstring GroupValue Show child attributes messaging_productstring·required Always 'whatsapp'. metadataMetadata·required Show child attributes display_phone_numberstring·required Business display phone number. phone_number_idstring·required Business phone number ID. groupsarray of Groups·required Array of group objects. Show child attributes groups[]Groups Show child attributes timestampinteger·required Unix timestamp of the group event group_idstring·required Unique identifier for the group typeOne of "group_create", "group_delete", "group_settings_update", "group_add_participants", "group_remove_participants"·required Type of group event request_idstring·required Unique identifier for the request subjectstring Group subject/name descriptionstring Group description added_participantsarray of GroupParticipant List of participants added to the group Show child attributes added_participants[]GroupParticipant Show child attributes inputstring Input phone number or WhatsApp ID wa_idstring WhatsApp ID of the participant removed_participantsarray of GroupParticipant List of participants removed from the group Show child attributes removed_participants[]GroupParticipant Show child attributes inputstring Input phone number or WhatsApp ID wa_idstring WhatsApp ID of the participant profile_pictureGroupProfilePicture Show child attributes mime_typestring MIME type of the profile picture sha256string SHA256 hash of the profile picture fieldOne of "messages", "group_lifecycle_update", "group_settings_update", "group_participant_update"·required The field indicate to what object is the webhook related: messages: the webhook is related to messages from consumer or status of message sent by business to consumer. group_lifecycle_update: the webhook is related to group creation and deletion. group_settings_update: the webhook is related to group settings update. group_participant_update: the webhook is related to participants joining and leaving the groups. Responses Endpoint for receiving webhook payloads for diverse incoming WhatsApp message types. 200 Webhook received successfully Select language Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business API - WhatsApp Account Number API | Developer Documentation WhatsApp Business API - WhatsApp Account Number API Copy for LLM View as Markdown Version API for retrieving WhatsApp Account Number details and configuration information. This endpoint allows businesses to retrieve comprehensive information about their WhatsApp Account Numbers, including status, verification details, and configuration settings. GET /{Version}/{WhatsApp-Account-Number-ID} Retrieve comprehensive details about a WhatsApp Account Number, including its current status, verification information, quality rating, and configuration settings. Use Cases: Monitor account number status and quality rating Verify account number configuration before messaging operations Check verification and approval status Retrieve display name and business profile information Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Account number details can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Account-Number-IDstring·required Your WhatsApp Account Number ID. This ID represents the account number entity and can be obtained from your WhatsApp Business Account phone numbers list. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, display_phone_number, status). Available fields: id, display_phone_number, verified_name, status, quality_rating, country_code, country_dial_code, code_verification_status, name_status, messaging_limit_tier, account_mode, certificate, is_official_business_account Responses Retrieve comprehensive details about a WhatsApp Account Number, including its current status, verification information, quality rating, and configuration settings. Use Cases: Monitor account number status and quality rating Verify account number configuration before messaging operations Check verification and approval status Retrieve display name and business profile information Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Account number details can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Account Number details Content Type: application/json Schema: WhatsAppAccountNumber Show child attributes WhatsAppAccountNumber idstring·required Unique identifier for the WhatsApp Account Number display_phone_numberstring·required Phone number in international format for display purposes verified_namestring Business name verified for this phone number statusWhatsAppAccountNumberStatus·required Current status of the WhatsApp Account Number quality_ratingWhatsAppPhoneNumberQualityRating Quality rating based on message delivery and user feedback country_codestring ISO 3166-1 alpha-2 country code country_dial_codestring Country dialing code code_verification_statusWhatsAppCodeVerificationStatus Two-step verification status for the phone number name_statusWhatsAppDisplayNameStatus Status of the display name associated with the phone number messaging_limit_tierOne of "TIER_50", "TIER_250", "TIER_1K", "TIER_10K", "TIER_100K", "TIER_UNLIMITED" Current messaging limit tier for the account number account_modeWhatsAppBusinessSandboxEligibility Account mode indicating sandbox or live environment certificatestring Business certificate information for the account number is_official_business_accountboolean Whether this is an official business account 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Account Number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account - Assigned Users Management API | Developer Documentation WhatsApp Business Account - Assigned Users Management API Copy for LLM View as Markdown Version API for managing user assignments and permissions for WhatsApp Business Accounts. This endpoint allows businesses to manage user access to their WhatsApp Business Accounts, including listing assigned users, adding users with specific permissions, and removing user access. GET /{Version}/{WhatsApp-Business-Account-ID}/assigned_users Retrieve a list of users assigned to the WhatsApp Business Account with their permissions and user details. This endpoint supports pagination and filtering capabilities. Use Cases: Audit user access to WhatsApp Business Account Retrieve user permission assignments for compliance List all users with access for management purposes Monitor user access patterns and assignments Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: User assignment data can be cached for short periods, but permission changes may occur frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Query Parameters businessstring·required Business ID that owns or has access to the WhatsApp Business Account. This parameter is required to specify the business context for user assignments. fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, business, user_type limitinteger [min: 1, max: 100] Maximum number of assigned users to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. beforestring Cursor for pagination. Use this to get the previous page of results. Responses Retrieve a list of users assigned to the WhatsApp Business Account with their permissions and user details. This endpoint supports pagination and filtering capabilities. Use Cases: Audit user access to WhatsApp Business Account Retrieve user permission assignments for compliance List all users with access for management purposes Monitor user access patterns and assignments Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: User assignment data can be cached for short periods, but permission changes may occur frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved assigned users list Content Type: application/json Schema: AssignedUsersResponse Show child attributes AssignedUsersResponse dataarray of AssignedUser·required Array of assigned users Show child attributes data[]AssignedUser User assigned to WhatsApp Business Account with permissions Show child attributes idstring·required Unique identifier for the assigned user namestring·required Display name of the assigned user businessBusinessNode Business entity associated with the user Show child attributes idstring Unique identifier for the business namestring Name of the business user_typeAssignedUserType Type of user assignment pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data afterstring Cursor pointing to the end of the page of data nextstring Graph API endpoint for the next page of results previousstring Graph API endpoint for the previous page of results summaryAssignedUsersSummary Summary information about assigned users Show child attributes total_countinteger Total number of assigned users 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{WhatsApp-Business-Account-ID}/assigned_users Add a user to the WhatsApp Business Account with specified permission tasks. This operation grants the user access to perform specific actions on the account based on the provided permission tasks. Use Cases: Grant user access to WhatsApp Business Account management Assign specific permission tasks for granular access control Add new team members to WhatsApp Business Account operations Configure user permissions for different business roles Permission Tasks: Different permission tasks grant access to different WhatsApp Business Account features: MANAGE: General account management permissions DEVELOP: Development and API access permissions MANAGE_TEMPLATES: Message template management MANAGE_PHONE: Phone number management MESSAGING: Send and receive messages FULL_CONTROL: Complete access to all account features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Required Content Type: application/x-www-form-urlencoded Schema: object Show child attributes userstring·required User ID of the person to add to the WhatsApp Business Account. This must be a valid Facebook user ID. tasksarray of WhatsAppBusinessAccountPermissionTask·required Array of permission tasks to grant to the user. These tasks determine what actions the user can perform on the WhatsApp Business Account. Show child attributes tasks[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access Responses Add a user to the WhatsApp Business Account with specified permission tasks. This operation grants the user access to perform specific actions on the account based on the provided permission tasks. Use Cases: Grant user access to WhatsApp Business Account management Assign specific permission tasks for granular access control Add new team members to WhatsApp Business Account operations Configure user permissions for different business roles Permission Tasks: Different permission tasks grant access to different WhatsApp Business Account features: MANAGE: General account management permissions DEVELOP: Development and API access permissions MANAGE_TEMPLATES: Message template management MANAGE_PHONE: Phone number management MESSAGING: Send and receive messages FULL_CONTROL: Complete access to all account features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully added user to WhatsApp Business Account Content Type: application/json Schema: SuccessResponse Show child attributes SuccessResponse successboolean·required Indicates whether the operation was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID or User ID does not exist Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code DELETE /{Version}/{WhatsApp-Business-Account-ID}/assigned_users Remove a user's access from the WhatsApp Business Account. This operation revokes all permissions and access rights for the specified user on the account. Use Cases: Revoke user access when they leave the organization Remove temporary access grants Clean up user permissions for security compliance Manage user lifecycle and access control Important Notes: This operation removes ALL permissions for the user on this WhatsApp Business Account The user will lose access to all account features and data This action cannot be undone - the user must be re-added if access is needed again Webhooks may be triggered to notify of user access changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Required Content Type: application/x-www-form-urlencoded Schema: object Show child attributes userstring·required User ID of the person to remove from the WhatsApp Business Account. This must be a valid Facebook user ID that is currently assigned to the account. Responses Remove a user's access from the WhatsApp Business Account. This operation revokes all permissions and access rights for the specified user on the account. Use Cases: Revoke user access when they leave the organization Remove temporary access grants Clean up user permissions for security compliance Manage user lifecycle and access control Important Notes: This operation removes ALL permissions for the user on this WhatsApp Business Account The user will lose access to all account features and data This action cannot be undone - the user must be re-added if access is needed again Webhooks may be triggered to notify of user access changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully removed user from WhatsApp Business Account Content Type: application/json Schema: SuccessResponse Show child attributes SuccessResponse successboolean·required Indicates whether the operation was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID or User ID does not exist or is not assigned Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account - Conversational Automation API | Developer Documentation WhatsApp Business Account - Conversational Automation API Copy for LLM View as Markdown Version API for managing conversational automation settings for WhatsApp Business Account phone numbers. This endpoint allows businesses to configure automated conversation features including welcome messages, conversation prompts (ice breakers), and bot commands for their WhatsApp Business phone numbers. POST /{Version}/{Phone-Number-ID}/conversational_automation Configure conversational automation settings for a WhatsApp Business Account phone number, including welcome messages, conversation prompts (ice breakers), and bot commands. Use Cases: Set up automated welcome messages for new customer conversations Configure conversation prompts to guide customer interactions Define bot commands for common customer service scenarios Update existing automation settings Enable or disable specific automation features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Validation: Command names must be unique within the same phone number Prompts and command descriptions must comply with WhatsApp Business policies Maximum limits are enforced for prompts and commands Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required Your WhatsApp Business phone number ID. This ID represents the phone number entity and can be obtained from your WhatsApp Business Account phone numbers list. Required Content Type: application/json Schema: ConversationalAutomationRequest Show child attributes ConversationalAutomationRequest enable_welcome_messageboolean Whether to enable welcome messages for new conversations promptsarray of string List of conversation prompts (ice breakers) to help guide customer interactions Show child attributes prompts[]string Individual conversation prompt text commandsarray of BotCommand List of bot commands for automated responses Show child attributes commands[]BotCommand Bot command configuration for automated responses Show child attributes command_namestring·required Name of the bot command (without leading slash) command_descriptionstring·required Description of what the command does Responses Configure conversational automation settings for a WhatsApp Business Account phone number, including welcome messages, conversation prompts (ice breakers), and bot commands. Use Cases: Set up automated welcome messages for new customer conversations Configure conversation prompts to guide customer interactions Define bot commands for common customer service scenarios Update existing automation settings Enable or disable specific automation features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Validation: Command names must be unique within the same phone number Prompts and command descriptions must comply with WhatsApp Business policies Maximum limits are enforced for prompts and commands 200 Successfully configured conversational automation settings Content Type: application/json Schema: ConversationalAutomationResponse Show child attributes ConversationalAutomationResponse successboolean·required Indicates whether the automation configuration was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Extended Credits API | Developer Documentation WhatsApp Cloud API - Extended Credits API Copy for LLM View as Markdown Version Retrieve extended credit line information for WhatsApp Business Accounts. Returns credit line IDs and associated legal entity names for billing and payment management. Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business API - Phone Number Management API | Developer Documentation WhatsApp Business API - Phone Number Management API Copy for LLM View as Markdown Version API for managing WhatsApp Business Account phone numbers, including retrieving phone number details and creating new phone number registrations within a WhatsApp Business Account. GET /{Version}/{WABA-ID}/phone_numbers Retrieve all phone numbers associated with a WhatsApp Business Account, including their status, verification details, and configuration information. Use Cases: List all phone numbers in a WhatsApp Business Account Monitor phone number status and verification progress Check phone number quality ratings and messaging limits Retrieve phone number configuration details Filtering: You can filter results using the filtering parameter with JSON-encoded filter conditions. Supported filters include account_mode, messaging_limit_tier, and is_official_business_account. Sorting: Results can be sorted by creation_time or last_onboarded_time in ascending or descending order. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number data can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through the business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned. Available fields include: id, display_phone_number, verified_name, status, quality_rating, country_code, country_dial_code, code_verification_status, unified_cert_status, account_mode, host_platform, messaging_limit_tier, is_official_business_account, username filteringstring JSON-encoded array of filter conditions. Each filter should specify field, operator, and value. Supported fields: account_mode, messaging_limit_tier, is_official_business_account sortOne of "creation_time.asc", "creation_time.desc", "last_onboarded_time.asc", "last_onboarded_time.desc" Sort field and direction. Format: field_name.asc or field_name.desc Supported fields: creation_time, last_onboarded_time limitinteger [min: 1, max: 100] Maximum number of phone numbers to return per page afterstring Cursor for pagination - retrieve records after this cursor beforestring Cursor for pagination - retrieve records before this cursor Responses Retrieve all phone numbers associated with a WhatsApp Business Account, including their status, verification details, and configuration information. Use Cases: List all phone numbers in a WhatsApp Business Account Monitor phone number status and verification progress Check phone number quality ratings and messaging limits Retrieve phone number configuration details Filtering: You can filter results using the filtering parameter with JSON-encoded filter conditions. Supported filters include account_mode, messaging_limit_tier, and is_official_business_account. Sorting: Results can be sorted by creation_time or last_onboarded_time in ascending or descending order. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Phone number data can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Business Account phone numbers Content Type: application/json Schema: WhatsAppBusinessAccountPhoneNumbersConnection Show child attributes WhatsAppBusinessAccountPhoneNumbersConnection dataarray of WhatsAppBusinessAccountPhoneNumber·required Array of phone number records Show child attributes data[]WhatsAppBusinessAccountPhoneNumber WhatsApp Business Account phone number details and status information Show child attributes idstring·required Unique identifier for the phone number status record display_phone_numberstring·required Phone number in international format for display purposes verified_namestring Business name verified for this phone number statusWhatsAppPhoneNumberStatus·required Current status of the phone number in the WhatsApp Business Account quality_ratingWhatsAppPhoneNumberQualityRating Quality rating for the phone number based on messaging patterns country_codestring ISO 3166-1 alpha-2 country code country_dial_codestring Country dialing code code_verification_statusWhatsAppCodeVerificationStatus Status of phone number verification code unified_cert_statusWhatsAppBusinessUnifiedCertStatus Unified certification status combining business and name verification account_modeWhatsAppBusinessSandboxEligibility Account mode indicating sandbox or live environment eligibility host_platformWhatsAppBusinessAccountHostPlatform Platform hosting the WhatsApp Business Account messaging_limit_tierOne of "TIER_50", "TIER_250", "TIER_1K", "TIER_10K", "TIER_100K", "TIER_UNLIMITED" Current messaging limit tier for the phone number is_official_business_accountboolean Whether this is an official business account usernamestring WhatsApp username for the business account (if available) pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page afterstring Cursor pointing to the end of the page previousstring URL for the previous page of results nextstring URL for the next page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{WABA-ID}/phone_numbers Create a new phone number registration within a WhatsApp Business Account. This endpoint initiates the phone number onboarding process, including verification and business name approval. Use Cases: Add new phone numbers to a WhatsApp Business Account Migrate phone numbers from on-premises to Cloud API Register pre-verified phone numbers for BSP scenarios Initiate phone number verification and business name approval process Prerequisites: WhatsApp Business Account must have available phone number slots Phone number must not be already registered with WhatsApp Business Business must meet WhatsApp Business API requirements Appropriate permissions and app review completion Process Flow: Submit phone number and business name for registration Phone number verification code will be sent (if not pre-verified) Business name will be submitted for review Monitor status through GET endpoint until approval Rate Limiting: Phone number creation is subject to strict rate limits to prevent abuse. Standard Graph API rate limits also apply. Migration Support: Set migrate_phone_number=true when migrating from on-premises API to Cloud API. Additional validation and migration-specific logic will be applied. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID where the phone number will be added. This ID can be found in your WhatsApp Manager or through business management APIs. Required Content Type: application/json Schema: PhoneNumberCreateRequest Show child attributes PhoneNumberCreateRequest phone_numberstring·required Phone number in E.164 format without the + prefix verified_namestring·required Business name to be verified for this phone number ccstring Country code for the phone number migrate_phone_numberboolean Whether this is a phone number migration from on-premises preverified_idstring Pre-verified phone number ID for BSP scenarios Responses Create a new phone number registration within a WhatsApp Business Account. This endpoint initiates the phone number onboarding process, including verification and business name approval. Use Cases: Add new phone numbers to a WhatsApp Business Account Migrate phone numbers from on-premises to Cloud API Register pre-verified phone numbers for BSP scenarios Initiate phone number verification and business name approval process Prerequisites: WhatsApp Business Account must have available phone number slots Phone number must not be already registered with WhatsApp Business Business must meet WhatsApp Business API requirements Appropriate permissions and app review completion Process Flow: Submit phone number and business name for registration Phone number verification code will be sent (if not pre-verified) Business name will be submitted for review Monitor status through GET endpoint until approval Rate Limiting: Phone number creation is subject to strict rate limits to prevent abuse. Standard Graph API rate limits also apply. Migration Support: Set migrate_phone_number=true when migrating from on-premises API to Cloud API. Additional validation and migration-specific logic will be applied. 200 Successfully created phone number registration Content Type: application/json Schema: PhoneNumberCreateResponse Show child attributes PhoneNumberCreateResponse idstring·required Unique identifier for the created phone number status record 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or phone number limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 409 Conflict - Phone number already exists or is in use Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account - Schedules API | Developer Documentation WhatsApp Business Account - Schedules API Copy for LLM View as Markdown Version API for managing WhatsApp Business Account schedules and scheduling configurations. This endpoint allows businesses to manage scheduling functionality for their WhatsApp Business Account, including retrieving existing schedules and creating new scheduling configurations for automated messaging, business hours, and other time-based operations. GET /{Version}/{WABA-ID}/schedules Retrieve all schedules associated with a WhatsApp Business Account, including their configuration, status, and execution details. Use Cases: List all schedules in a WhatsApp Business Account Monitor schedule status and performance Check schedule configuration and timing details Retrieve schedule execution history and metrics Filtering: You can filter results using the filtering parameter with JSON-encoded filter conditions. Supported filters include status, schedule_type, and is_active. Sorting: Results can be sorted by created_time or updated_time in ascending or descending order. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Schedule data can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through the business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned. Available fields include: id, name, status, schedule_type, description, start_time, end_time, timezone, days_of_week, created_time, updated_time, is_active, recurrence_pattern filteringstring JSON-encoded array of filter conditions. Each filter should specify field, operator, and value. Supported fields: status, schedule_type, is_active sortOne of "created_time.asc", "created_time.desc", "updated_time.asc", "updated_time.desc" Sort field and direction. Format: field_name.asc or field_name.desc Supported fields: created_time, updated_time limitinteger [min: 1, max: 100] Maximum number of schedules to return per page afterstring Cursor for pagination - retrieve records after this cursor beforestring Cursor for pagination - retrieve records before this cursor Responses Retrieve all schedules associated with a WhatsApp Business Account, including their configuration, status, and execution details. Use Cases: List all schedules in a WhatsApp Business Account Monitor schedule status and performance Check schedule configuration and timing details Retrieve schedule execution history and metrics Filtering: You can filter results using the filtering parameter with JSON-encoded filter conditions. Supported filters include status, schedule_type, and is_active. Sorting: Results can be sorted by created_time or updated_time in ascending or descending order. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Schedule data can be cached for short periods, but status information may change frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Business Account schedules Content Type: application/json Schema: WhatsAppBusinessAccountSchedulesConnection Show child attributes WhatsAppBusinessAccountSchedulesConnection dataarray of WhatsAppBusinessAccountSchedule·required Array of schedule records Show child attributes data[]WhatsAppBusinessAccountSchedule WhatsApp Business Account schedule configuration and details Show child attributes idstring·required Unique identifier for the schedule namestring·required Human-readable name for the schedule statusWhatsAppScheduleStatus·required Current status of the schedule schedule_typeWhatsAppScheduleType·required Type of schedule configuration descriptionstring Optional description of the schedule purpose start_timestring (time) Schedule start time in HH:MM format end_timestring (time) Schedule end time in HH:MM format timezonestring Timezone identifier for the schedule days_of_weekarray of DayOfWeek Days of the week when the schedule is active Show child attributes days_of_week[]DayOfWeek Day of the week created_timestring (date-time) ISO 8601 timestamp when the schedule was created updated_timestring (date-time) ISO 8601 timestamp when the schedule was last updated is_activeboolean Whether the schedule is currently active recurrence_patternRecurrencePattern Pattern for recurring schedules Show child attributes frequencyOne of "DAILY", "WEEKLY", "MONTHLY", "YEARLY" intervalinteger [min: 1] Interval between recurrences end_datestring (date) End date for the recurrence pattern pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page afterstring Cursor pointing to the end of the page previousstring URL for the previous page of results nextstring URL for the next page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{WABA-ID}/schedules Create a new schedule configuration within a WhatsApp Business Account. This endpoint allows businesses to set up automated scheduling for various operations such as business hours, automated responses, and maintenance windows. Use Cases: Create business hours schedules for automated responses Set up maintenance windows for system operations Configure automated message campaigns with timing Establish recurring schedule patterns for business operations Prerequisites: WhatsApp Business Account must have scheduling feature enabled Appropriate permissions for schedule management Valid timezone and time format specifications Business must meet WhatsApp Business API requirements Process Flow: Submit schedule configuration with timing and recurrence details System validates schedule parameters and conflicts Schedule is created and activated based on is_active flag Monitor schedule status through GET endpoint Rate Limiting: Schedule creation is subject to rate limits to prevent abuse. Standard Graph API rate limits also apply. Validation: Start time must be before end time Timezone must be valid IANA timezone identifier Days of week must be valid if specified Recurrence pattern must be consistent with schedule type Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID where the schedule will be created. This ID can be found in your WhatsApp Manager or through business management APIs. Required Content Type: application/json Schema: ScheduleCreateRequest Show child attributes ScheduleCreateRequest namestring·required Human-readable name for the schedule schedule_typeWhatsAppScheduleType·required Type of schedule configuration descriptionstring Optional description of the schedule purpose start_timestring (time)·required Schedule start time in HH:MM format end_timestring (time)·required Schedule end time in HH:MM format timezonestring Timezone identifier for the schedule days_of_weekarray of DayOfWeek Days of the week when the schedule is active Show child attributes days_of_week[]DayOfWeek Day of the week is_activeboolean Whether the schedule should be active upon creation recurrence_patternRecurrencePattern Pattern for recurring schedules Show child attributes frequencyOne of "DAILY", "WEEKLY", "MONTHLY", "YEARLY" intervalinteger [min: 1] Interval between recurrences end_datestring (date) End date for the recurrence pattern Responses Create a new schedule configuration within a WhatsApp Business Account. This endpoint allows businesses to set up automated scheduling for various operations such as business hours, automated responses, and maintenance windows. Use Cases: Create business hours schedules for automated responses Set up maintenance windows for system operations Configure automated message campaigns with timing Establish recurring schedule patterns for business operations Prerequisites: WhatsApp Business Account must have scheduling feature enabled Appropriate permissions for schedule management Valid timezone and time format specifications Business must meet WhatsApp Business API requirements Process Flow: Submit schedule configuration with timing and recurrence details System validates schedule parameters and conflicts Schedule is created and activated based on is_active flag Monitor schedule status through GET endpoint Rate Limiting: Schedule creation is subject to rate limits to prevent abuse. Standard Graph API rate limits also apply. Validation: Start time must be before end time Timezone must be valid IANA timezone identifier Days of week must be valid if specified Recurrence pattern must be consistent with schedule type 200 Successfully created schedule Content Type: application/json Schema: ScheduleCreateResponse Show child attributes ScheduleCreateResponse idstring·required Unique identifier for the created schedule 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or schedule limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 409 Conflict - Schedule name already exists or time conflict Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account - Subscribed Apps API | Developer Documentation WhatsApp Business Account - Subscribed Apps API Copy for LLM View as Markdown Version API for managing app subscriptions to WhatsApp Business Account webhooks and retrieving subscription details. This endpoint allows apps to subscribe to, unsubscribe from, and query webhook subscriptions for WhatsApp Business Accounts. GET /{Version}/{WABA-ID}/subscribed_apps Retrieve a list of all applications currently subscribed to webhook events for the specified WhatsApp Business Account. Use Cases: Monitor which apps are subscribed to WABA webhook events Audit subscription configurations and permissions Verify subscription status before making changes Retrieve subscription details for troubleshooting Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Subscription data can be cached for short periods, but may change when apps subscribe or unsubscribe. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned. Available fields: id, name, link Responses Retrieve a list of all applications currently subscribed to webhook events for the specified WhatsApp Business Account. Use Cases: Monitor which apps are subscribed to WABA webhook events Audit subscription configurations and permissions Verify subscription status before making changes Retrieve subscription details for troubleshooting Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Subscription data can be cached for short periods, but may change when apps subscribe or unsubscribe. Implement appropriate cache invalidation strategies. 200 Successfully retrieved list of subscribed applications Content Type: application/json Schema: SubscribedAppsResponse Show child attributes SubscribedAppsResponse dataarray of SubscribedApp·required Array of subscribed applications Show child attributes data[]SubscribedApp Subscribed application details Show child attributes whatsapp_business_api_dataWhatsAppBusinessApiData·required Application subscription data for WhatsApp Business Account Show child attributes idstring·required Unique identifier for the subscribed application namestring·required Name of the subscribed application linkstring URL link to the application override_callback_uristring Custom webhook callback URL for this subscription 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{WABA-ID}/subscribed_apps Subscribe your application to webhook events for the specified WhatsApp Business Account. This enables your app to receive real-time notifications for events such as message deliveries, status updates, and other WABA activities. Use Cases: Enable webhook notifications for your app Configure custom callback URLs for webhook delivery Set up webhook verification tokens for security Override default app webhook settings for specific WABAs Rate Limiting: Standard Graph API rate limits apply. Subscription operations may have additional throttling to prevent abuse. Security: Always use HTTPS endpoints for webhook callbacks. Verify webhook authenticity using the provided verification tokens and signature validation. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through business management APIs. Optional Optional configuration for webhook subscription Content Type: application/json Schema: SubscriptionRequest Show child attributes SubscriptionRequest override_callback_uristring Custom webhook callback URL to override app default verify_tokenstring Verification token for webhook security Responses Subscribe your application to webhook events for the specified WhatsApp Business Account. This enables your app to receive real-time notifications for events such as message deliveries, status updates, and other WABA activities. Use Cases: Enable webhook notifications for your app Configure custom callback URLs for webhook delivery Set up webhook verification tokens for security Override default app webhook settings for specific WABAs Rate Limiting: Standard Graph API rate limits apply. Subscription operations may have additional throttling to prevent abuse. Security: Always use HTTPS endpoints for webhook callbacks. Verify webhook authenticity using the provided verification tokens and signature validation. 200 Successfully subscribed to WABA webhooks Content Type: application/json Schema: SubscriptionResponse Show child attributes SubscriptionResponse successboolean·required Indicates whether the subscription operation was successful dataarray of SubscribedApp Array containing subscription details Show child attributes data[]SubscribedApp Subscribed application details Show child attributes whatsapp_business_api_dataWhatsAppBusinessApiData·required Application subscription data for WhatsApp Business Account Show child attributes idstring·required Unique identifier for the subscribed application namestring·required Name of the subscribed application linkstring URL link to the application override_callback_uristring Custom webhook callback URL for this subscription 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code DELETE /{Version}/{WABA-ID}/subscribed_apps Unsubscribe your application from webhook events for the specified WhatsApp Business Account. This will stop your app from receiving webhook notifications for this WABA. Use Cases: Disable webhook notifications when no longer needed Clean up subscriptions during app decommissioning Temporarily disable webhooks for maintenance Remove subscriptions for WABAs no longer managed by your app Rate Limiting: Standard Graph API rate limits apply. Unsubscription operations are typically processed immediately. Important: Unsubscribing will immediately stop all webhook deliveries for this WABA. Ensure your application can handle the cessation of webhook events gracefully. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager or through business management APIs. Responses Unsubscribe your application from webhook events for the specified WhatsApp Business Account. This will stop your app from receiving webhook notifications for this WABA. Use Cases: Disable webhook notifications when no longer needed Clean up subscriptions during app decommissioning Temporarily disable webhooks for maintenance Remove subscriptions for WABAs no longer managed by your app Rate Limiting: Standard Graph API rate limits apply. Unsubscription operations are typically processed immediately. Important: Unsubscribing will immediately stop all webhook deliveries for this WABA. Ensure your application can handle the cessation of webhook events gracefully. 200 Successfully unsubscribed from WABA webhooks Content Type: application/json Schema: SubscriptionResponse Show child attributes SubscriptionResponse successboolean·required Indicates whether the subscription operation was successful dataarray of SubscribedApp Array containing subscription details Show child attributes data[]SubscribedApp Subscribed application details Show child attributes whatsapp_business_api_dataWhatsAppBusinessApiData·required Application subscription data for WhatsApp Business Account Show child attributes idstring·required Unique identifier for the subscribed application namestring·required Name of the subscribed application linkstring URL link to the application override_callback_uristring Custom webhook callback URL for this subscription 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or subscription not found Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Template API | Developer Documentation WhatsApp Cloud API - Template API Copy for LLM View as Markdown Version Create, retrieve, update, and delete message templates. Manage pre-approved message formats for business-initiated conversations. Includes template submission, localization, and quality score metrics. Select language Select status code Select language Select status code Select language Select status code Select language Select status code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account Solutions List API | Developer Documentation WhatsApp Business Account Solutions List API Copy for LLM View as Markdown Version API for retrieving Multi-Partner Solutions associated with a WhatsApp Business Account (WABA). This endpoint allows authorized applications to retrieve a list of Multi-Partner Solutions that are associated with a specific WhatsApp Business Account. GET /{Version}/{WABA-ID}/solutions Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID for which to retrieve associated Multi-Partner Solutions. This ID can be found in your WhatsApp Business Manager or through WABA management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (name, status, status_for_pending_request). Available fields: id, name, status, status_for_pending_request, owner_app, owner_permissions limitinteger [min: 1, max: 100] Maximum number of solutions to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Returns solutions after this cursor position. Use the cursor from the previous response's paging.cursors.after field. beforestring Cursor for pagination. Returns solutions before this cursor position. Use the cursor from the previous response's paging.cursors.before field. Responses Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. 200 Successfully retrieved Multi-Partner Solutions list Content Type: application/json Schema: SolutionsList Show child attributes SolutionsList dataarray of WhatsAppBusinessSolution·required Array of Multi-Partner Solutions associated with the WABA Show child attributes data[]WhatsAppBusinessSolution Multi-Partner Solution details and configuration Show child attributes idstring·required Unique identifier for the Multi-Partner Solution namestring·required Human-readable name of the Multi-Partner Solution statusWhatsAppBusinessSolutionStatus·required Current effective status of the Multi-Partner Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending solution status transition requests owner_appApplicationNode Meta application that owns the Multi-Partner Solution Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application owner_permissionsarray of WhatsAppBusinessAccountPermissionTask List of WhatsApp Business Account permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access pagingPaging Pagination information for cursor-based pagination Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned previousstring Graph API endpoint URL for the previous page of data nextstring Graph API endpoint URL for the next page of data 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account Solutions List API | Developer Documentation WhatsApp Business Account Solutions List API Copy for LLM View as Markdown Version API for retrieving Multi-Partner Solutions associated with a WhatsApp Business Account (WABA). This endpoint allows authorized applications to retrieve a list of Multi-Partner Solutions that are associated with a specific WhatsApp Business Account. GET /{Version}/{WABA-ID}/solutions Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID for which to retrieve associated Multi-Partner Solutions. This ID can be found in your WhatsApp Business Manager or through WABA management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (name, status, status_for_pending_request). Available fields: id, name, status, status_for_pending_request, owner_app, owner_permissions limitinteger [min: 1, max: 100] Maximum number of solutions to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Returns solutions after this cursor position. Use the cursor from the previous response's paging.cursors.after field. beforestring Cursor for pagination. Returns solutions before this cursor position. Use the cursor from the previous response's paging.cursors.before field. Responses Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. 200 Successfully retrieved Multi-Partner Solutions list Content Type: application/json Schema: SolutionsList Show child attributes SolutionsList dataarray of WhatsAppBusinessSolution·required Array of Multi-Partner Solutions associated with the WABA Show child attributes data[]WhatsAppBusinessSolution Multi-Partner Solution details and configuration Show child attributes idstring·required Unique identifier for the Multi-Partner Solution namestring·required Human-readable name of the Multi-Partner Solution statusWhatsAppBusinessSolutionStatus·required Current effective status of the Multi-Partner Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending solution status transition requests owner_appApplicationNode Meta application that owns the Multi-Partner Solution Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application owner_permissionsarray of WhatsAppBusinessAccountPermissionTask List of WhatsApp Business Account permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access pagingPaging Pagination information for cursor-based pagination Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned previousstring Graph API endpoint URL for the previous page of data nextstring Graph API endpoint URL for the next page of data 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account Solutions List API | Developer Documentation WhatsApp Business Account Solutions List API Copy for LLM View as Markdown Version API for retrieving Multi-Partner Solutions associated with a WhatsApp Business Account (WABA). This endpoint allows authorized applications to retrieve a list of Multi-Partner Solutions that are associated with a specific WhatsApp Business Account. GET /{Version}/{WABA-ID}/solutions Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-IDstring·required WhatsApp Business Account ID for which to retrieve associated Multi-Partner Solutions. This ID can be found in your WhatsApp Business Manager or through WABA management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (name, status, status_for_pending_request). Available fields: id, name, status, status_for_pending_request, owner_app, owner_permissions limitinteger [min: 1, max: 100] Maximum number of solutions to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Returns solutions after this cursor position. Use the cursor from the previous response's paging.cursors.after field. beforestring Cursor for pagination. Returns solutions before this cursor position. Use the cursor from the previous response's paging.cursors.before field. Responses Retrieve a paginated list of Multi-Partner Solutions associated with the specified WhatsApp Business Account. This endpoint supports field selection and cursor-based pagination for efficient data retrieval. Use Cases: Discover available Multi-Partner Solutions for business onboarding Monitor solution status and availability across your WABA Retrieve solution ownership and permission details Filter solutions by specific fields or status requirements Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution listings can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Pagination: This endpoint supports cursor-based pagination using limit, after, and before parameters. Use the paging object in responses to navigate through result sets. 200 Successfully retrieved Multi-Partner Solutions list Content Type: application/json Schema: SolutionsList Show child attributes SolutionsList dataarray of WhatsAppBusinessSolution·required Array of Multi-Partner Solutions associated with the WABA Show child attributes data[]WhatsAppBusinessSolution Multi-Partner Solution details and configuration Show child attributes idstring·required Unique identifier for the Multi-Partner Solution namestring·required Human-readable name of the Multi-Partner Solution statusWhatsAppBusinessSolutionStatus·required Current effective status of the Multi-Partner Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending solution status transition requests owner_appApplicationNode Meta application that owns the Multi-Partner Solution Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application owner_permissionsarray of WhatsAppBusinessAccountPermissionTask List of WhatsApp Business Account permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access pagingPaging Pagination information for cursor-based pagination Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned previousstring Graph API endpoint URL for the previous page of data nextstring Graph API endpoint URL for the next page of data 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WABA ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account - Migration Intent Details API | Developer Documentation WhatsApp Business Account - Migration Intent Details API Copy for LLM View as Markdown Version API for retrieving WhatsApp Business Account migration intent details and status information. This endpoint allows solution partners to retrieve comprehensive information about their WhatsApp Business Account migration intents, including current status and migration details. GET /{Version}/{Migration-Intent-ID} Retrieve comprehensive details about a WhatsApp Business Account migration intent, including its current status and migration information. Use Cases: Monitor migration intent lifecycle and status changes Verify migration intent configuration and current state Check migration progress and completion status Retrieve migration intent details for business workflows Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Migration intent details can be cached for short periods, but status information may change frequently during migration processes. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Migration-Intent-IDstring·required Your Migration Intent ID. This ID is provided when you create the migration intent and can be found through migration management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, status). Available fields: id, status Responses Retrieve comprehensive details about a WhatsApp Business Account migration intent, including its current status and migration information. Use Cases: Monitor migration intent lifecycle and status changes Verify migration intent configuration and current state Check migration progress and completion status Retrieve migration intent details for business workflows Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Migration intent details can be cached for short periods, but status information may change frequently during migration processes. Implement appropriate cache invalidation strategies. 200 Successfully retrieved migration intent details Content Type: application/json Schema: WhatsAppBusinessAccountMigrationIntent Show child attributes WhatsAppBusinessAccountMigrationIntent idstring·required Unique identifier for the migration intent statusWhatsAppBusinessAccountMigrationStatus·required Current status of the WhatsApp Business Account migration intent 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Migration Intent ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Bot - Bot Details API | Developer Documentation WhatsApp Business Bot - Bot Details API Copy for LLM View as Markdown Version This endpoint allows developers to retrieve comprehensive information about their WhatsApp Business Bot, including prompts, commands, and welcome message settings. This is essential for managing bot configuration and understanding current bot state. GET /{Version}/{WABA-Bot-ID} Retrieve comprehensive details about a WhatsApp Business Bot, including its prompts, commands, and welcome message configuration. Use Cases: Retrieve bot configuration and automated response settings Monitor available bot commands and their descriptions Check welcome message enablement status Validate bot state before implementing automation Audit bot configuration for business compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Bot details can be cached for moderate periods, but configuration may change when bot settings are updated. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WABA-Bot-IDstring·required Your WhatsApp Business Bot ID. This ID is provided when you create the bot and can be found in your Business Manager or through bot management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (prompts, commands, enable_welcome_message). Available fields: id, prompts, commands, enable_welcome_message Responses Retrieve comprehensive details about a WhatsApp Business Bot, including its prompts, commands, and welcome message configuration. Use Cases: Retrieve bot configuration and automated response settings Monitor available bot commands and their descriptions Check welcome message enablement status Validate bot state before implementing automation Audit bot configuration for business compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Bot details can be cached for moderate periods, but configuration may change when bot settings are updated. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Business Bot details Content Type: application/json Schema: WhatsAppBusinessBot Show child attributes WhatsAppBusinessBot idstring·required Unique identifier for the WhatsApp Business Bot promptsarray of string List of bot prompts and automated responses Show child attributes prompts[]string commandsarray of WhatsAppBusinessBotCommand List of available bot commands and their descriptions Show child attributes commands[]WhatsAppBusinessBotCommand Bot command configuration with name and description Show child attributes command_namestring·required Name of the bot command command_descriptionstring·required Description of what the command does enable_welcome_messageboolean Whether the welcome message is enabled for this bot 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Bot ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Block API | Developer Documentation WhatsApp Cloud API - Block API Copy for LLM View as Markdown Version The Block API allows businesses to manage blocked users on WhatsApp. Use this API to block users from sending messages to your business number, retrieve the list of blocked users, and unblock users when needed. For more information, see the Block Users Guide. Select language Select status code Select language Select status code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Business Encryption API | Developer Documentation WhatsApp Cloud API - Business Encryption API Copy for LLM View as Markdown Version API for managing WhatsApp Business Account encryption settings and public key management. This endpoint allows businesses to set up and manage encryption for their WhatsApp Business messaging by uploading and retrieving business public keys used for payload encryption. GET /{Version}/{Phone-Number-ID}/whatsapp_business_encryption Retrieve the current business public key and its signature verification status. This endpoint returns the public key that is currently configured for encrypting message payloads and indicates whether the stored signature is valid or has a mismatch. Use Cases: Verify current encryption configuration Check public key signature validation status Retrieve public key for client-side encryption setup Monitor encryption key status for security compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Public key information can be cached for moderate periods, but signature status may change and should be checked regularly for security validation. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required Your WhatsApp Business phone number ID. This ID represents the phone number entity and can be obtained from your WhatsApp Business Account phone numbers list. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, all available fields will be returned. Available fields: business_public_key, business_public_key_signature_status Responses Retrieve the current business public key and its signature verification status. This endpoint returns the public key that is currently configured for encrypting message payloads and indicates whether the stored signature is valid or has a mismatch. Use Cases: Verify current encryption configuration Check public key signature validation status Retrieve public key for client-side encryption setup Monitor encryption key status for security compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Public key information can be cached for moderate periods, but signature status may change and should be checked regularly for security validation. 200 Successfully retrieved business encryption public key information Content Type: application/json Schema: object Show child attributes dataarray of WhatsAppBusinessEncryptionInfo Show child attributes data[]WhatsAppBusinessEncryptionInfo Business encryption public key information and verification status Show child attributes business_public_keystring·required The business public key used for encrypting message payloads. This key is used to encrypt data channel requests and responses. Show child attributes business_public_key_signature_statusBusinessPublicKeyVerificationStatus·required Status of business public key signature verification 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{Phone-Number-ID}/whatsapp_business_encryption Upload and configure a business public key for message payload encryption. This endpoint accepts a business public key in PEM format, validates it, and stores it with a cryptographic signature for future use in encrypting message payloads and data channel requests. Use Cases: Initial setup of encryption for WhatsApp Business messaging Update existing public key for key rotation Enable secure payload encryption for sensitive business communications Configure encryption keys for compliance requirements Key Requirements: Must be a valid RSA public key in PEM format Key must meet Meta's security standards for encryption Only one active public key per phone number at a time Previous keys are replaced when new ones are uploaded Rate Limiting: Standard Graph API rate limits apply. Key uploads may have additional security-related rate limiting to prevent abuse. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required Your WhatsApp Business phone number ID. This ID represents the phone number entity and can be obtained from your WhatsApp Business Account phone numbers list. Required Content Type: multipart/form-data Schema: WhatsAppBusinessEncryptionUploadRequest Show child attributes WhatsAppBusinessEncryptionUploadRequest business_public_keystring·required The business public key in PEM format to be uploaded and signed. Must be a valid RSA public key that will be used for payload encryption. Responses Upload and configure a business public key for message payload encryption. This endpoint accepts a business public key in PEM format, validates it, and stores it with a cryptographic signature for future use in encrypting message payloads and data channel requests. Use Cases: Initial setup of encryption for WhatsApp Business messaging Update existing public key for key rotation Enable secure payload encryption for sensitive business communications Configure encryption keys for compliance requirements Key Requirements: Must be a valid RSA public key in PEM format Key must meet Meta's security standards for encryption Only one active public key per phone number at a time Previous keys are replaced when new ones are uploaded Rate Limiting: Standard Graph API rate limits apply. Key uploads may have additional security-related rate limiting to prevent abuse. 200 Successfully uploaded and configured business encryption public key Content Type: application/json Schema: WhatsAppBusinessEncryptionUploadResponse Show child attributes WhatsAppBusinessEncryptionUploadResponse successboolean·required Indicates whether the public key was successfully uploaded and signed 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Business Encryption API | Developer Documentation WhatsApp Cloud API - Business Encryption API Copy for LLM View as Markdown Version API for managing WhatsApp Business Account encryption settings and public key management. This endpoint allows businesses to set up and manage encryption for their WhatsApp Business messaging by uploading and retrieving business public keys used for payload encryption. GET /{Version}/{Phone-Number-ID}/whatsapp_business_encryption Retrieve the current business public key and its signature verification status. This endpoint returns the public key that is currently configured for encrypting message payloads and indicates whether the stored signature is valid or has a mismatch. Use Cases: Verify current encryption configuration Check public key signature validation status Retrieve public key for client-side encryption setup Monitor encryption key status for security compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Public key information can be cached for moderate periods, but signature status may change and should be checked regularly for security validation. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required Your WhatsApp Business phone number ID. This ID represents the phone number entity and can be obtained from your WhatsApp Business Account phone numbers list. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, all available fields will be returned. Available fields: business_public_key, business_public_key_signature_status Responses Retrieve the current business public key and its signature verification status. This endpoint returns the public key that is currently configured for encrypting message payloads and indicates whether the stored signature is valid or has a mismatch. Use Cases: Verify current encryption configuration Check public key signature validation status Retrieve public key for client-side encryption setup Monitor encryption key status for security compliance Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Public key information can be cached for moderate periods, but signature status may change and should be checked regularly for security validation. 200 Successfully retrieved business encryption public key information Content Type: application/json Schema: object Show child attributes dataarray of WhatsAppBusinessEncryptionInfo Show child attributes data[]WhatsAppBusinessEncryptionInfo Business encryption public key information and verification status Show child attributes business_public_keystring·required The business public key used for encrypting message payloads. This key is used to encrypt data channel requests and responses. Show child attributes business_public_key_signature_statusBusinessPublicKeyVerificationStatus·required Status of business public key signature verification 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{Phone-Number-ID}/whatsapp_business_encryption Upload and configure a business public key for message payload encryption. This endpoint accepts a business public key in PEM format, validates it, and stores it with a cryptographic signature for future use in encrypting message payloads and data channel requests. Use Cases: Initial setup of encryption for WhatsApp Business messaging Update existing public key for key rotation Enable secure payload encryption for sensitive business communications Configure encryption keys for compliance requirements Key Requirements: Must be a valid RSA public key in PEM format Key must meet Meta's security standards for encryption Only one active public key per phone number at a time Previous keys are replaced when new ones are uploaded Rate Limiting: Standard Graph API rate limits apply. Key uploads may have additional security-related rate limiting to prevent abuse. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required Your WhatsApp Business phone number ID. This ID represents the phone number entity and can be obtained from your WhatsApp Business Account phone numbers list. Required Content Type: multipart/form-data Schema: WhatsAppBusinessEncryptionUploadRequest Show child attributes WhatsAppBusinessEncryptionUploadRequest business_public_keystring·required The business public key in PEM format to be uploaded and signed. Must be a valid RSA public key that will be used for payload encryption. Responses Upload and configure a business public key for message payload encryption. This endpoint accepts a business public key in PEM format, validates it, and stores it with a cryptographic signature for future use in encrypting message payloads and data channel requests. Use Cases: Initial setup of encryption for WhatsApp Business messaging Update existing public key for key rotation Enable secure payload encryption for sensitive business communications Configure encryption keys for compliance requirements Key Requirements: Must be a valid RSA public key in PEM format Key must meet Meta's security standards for encryption Only one active public key per phone number at a time Previous keys are replaced when new ones are uploaded Rate Limiting: Standard Graph API rate limits apply. Key uploads may have additional security-related rate limiting to prevent abuse. 200 Successfully uploaded and configured business encryption public key Content Type: application/json Schema: WhatsAppBusinessEncryptionUploadResponse Show child attributes WhatsAppBusinessEncryptionUploadResponse successboolean·required Indicates whether the public key was successfully uploaded and signed 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Calling API | Developer Documentation WhatsApp Cloud API - Calling API Copy for LLM View as Markdown Version The WhatsApp Business Calling API enables you to initiate and receive calls with users on WhatsApp using voice-over-internet protocol (VoIP). GET /{Version}/{Phone-Number-ID}/call_permissions Check whether you have permission to call a WhatsApp user and what actions are available. This endpoint returns the current permission status for calling a specific user, along with available actions and their limits. Permission Status: granted: You have active permission to call this user - pending: A permission request has been sent but not yet approved - denied: The user has denied call permissions - expired: Previous permission has expired Available Actions: start_call: Initiate a new call to this user - send_call_permission_request: Send a permission request to this user Error Handling: This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required The API version to use Phone-Number-IDstring·required The ID of the phone number registered with your WhatsApp Business Account Query Parameters user_wa_idstring·required The WhatsApp ID of the user you want to check call permissions for Responses Check whether you have permission to call a WhatsApp user and what actions are available. This endpoint returns the current permission status for calling a specific user, along with available actions and their limits. Permission Status: granted: You have active permission to call this user - pending: A permission request has been sent but not yet approved - denied: The user has denied call permissions - expired: Previous permission has expired Available Actions: start_call: Initiate a new call to this user - send_call_permission_request: Send a permission request to this user Error Handling: This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period. 200 Call Permissions Check Success Content Type: application/json Schema: CallPermissionCheckResponsePayload Show child attributes CallPermissionCheckResponsePayload messaging_productstring·required Messaging product permissionobject·required Call permission details Show child attributes statusOne of "granted", "pending", "denied", "expired"·required Current permission status for calling this user expiration_timeinteger (int64) Unix timestamp when the permission expires (if applicable) actionsarray of object Available actions and their restrictions Show child attributes actions[]object Show child attributes action_nameOne of "start_call", "send_call_permission_request"·required Name of the action can_perform_actionboolean·required Whether the business can perform this action limitsarray of object Rate limits for this action Show child attributes limits[]object Show child attributes time_periodstring·required Time period for the limit current_usageinteger·required Current usage count max_allowedinteger·required Maximum allowed usage limit_expiration_timeinteger (int64) Unix timestamp when the limit resets 400 Bad Request - Invalid request parameters Content Type: application/json 429 Too Many Requests - Rate limit exceeded Content Type: application/json 403 Forbidden - Template not approved or insufficient permissions Content Type: application/json 500 Internal Server Error - An unexpected error occurred Content Type: application/json Select language Select status code POST /{Version}/{Phone-Number-ID}/calls Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls. For initiating or managing a call: Send a POST request with the appropriate action (connect, pre_accept, accept, reject, terminate). For terminating a call: Send a POST request with action "terminate" and the call_id. Note: Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required The API version to use Phone-Number-IDstring·required The ID of the phone number registered with your WhatsApp Business Account Optional Content Type: application/json Schema: Must be one of: CallRequestPayload, CallTerminateRequestPayload Show child attributes Must be one of: CallRequestPayload, CallTerminateRequestPayload CallRequestPayload Show child attributes messaging_productstring·required Messaging product tostring·required The number being called (callee) actionOne of "connect", "pre_accept", "accept", "reject", "terminate"·required The action being taken on the given call ID sessionobject Contains the session description protocol (SDP) type and description language Show child attributes sdp_typeOne of "offer", "answer"·required SDP type - "offer" for connect action, "answer" for accept action sdpstring·required The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866 biz_opaque_callback_datastring CallTerminateRequestPayload Show child attributes messaging_productstring·required Messaging product call_idstring·required The WhatsApp call ID action"terminate"·required Action to terminate the call Responses Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls. For initiating or managing a call: Send a POST request with the appropriate action (connect, pre_accept, accept, reject, terminate). For terminating a call: Send a POST request with action "terminate" and the call_id. Note: Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user. 200 Call Management Success Content Type: application/json Schema: Must be one of: CallResponsePayload, CallTerminateResponsePayload Show child attributes Must be one of: CallResponsePayload, CallTerminateResponsePayload CallResponsePayload Show child attributes messaging_productstring callsarray of object Show child attributes calls[]object Show child attributes idstring CallTerminateResponsePayload Show child attributes successboolean Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Commerce Settings API | Developer Documentation WhatsApp Cloud API - Commerce Settings API Copy for LLM View as Markdown Version Configure WhatsApp Business commerce settings including catalog visibility and shopping cart enablement. Retrieve and update commerce configurations for business phone numbers. Select language Select status code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Cloud API - Groups Management API | Developer Documentation WhatsApp Business Cloud API - Groups Management API Copy for LLM View as Markdown Version Create and manage WhatsApp Business groups with approval settings. Returns invite links for adding participants to groups. Retrieve active group lists with pagination support. Select language POST /{Version}/{Phone-Number-ID}/groups Create a new group and get an invite link Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required Phone-Number-IDstring·required Business phone number ID Required Content Type: application/json Schema: object Show child attributes messaging_product"whatsapp"·required Messaging product subjectstring·required Group subject. Maximum 128 characters. Whitespace is trimmed. descriptionstring Group description. Maximum 2048 characters. join_approval_modeOne of "approval_required", "auto_approve" Indicates if WhatsApp users who click the invitation link can join the group with or without being approved first. approval_required: WhatsApp users must be approved via join request before they can access the group auto_approve: WhatsApp users can join the group without approval Responses Create a new group and get an invite link 200 Group creation request submitted successfully Content Type: application/json Schema: object Show child attributes messaging_productstring request_idstring Group creation request ID 400 Bad Request - Invalid request parameters Content Type: application/json Schema: ErrorResponse Show child attributes ErrorResponse errorErrorObject·required Show child attributes messagestring·required Human-readable description of the error typestring·required Error type classification codeinteger·required Numeric error code 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: ErrorResponse Show child attributes ErrorResponse errorErrorObject·required Show child attributes messagestring·required Human-readable description of the error typestring·required Error type classification codeinteger·required Numeric error code 500 Internal Server Error - An unexpected error occurred Content Type: application/json Schema: ErrorResponse Show child attributes ErrorResponse errorErrorObject·required Show child attributes messagestring·required Human-readable description of the error typestring·required Error type classification codeinteger·required Numeric error code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Marketing Messages Lite API | Developer Documentation WhatsApp Cloud API - Marketing Messages Lite API Copy for LLM View as Markdown Version Send marketing template messages with automatic delivery optimization. Delivers relevant, timely messages to customers most likely to engage, with enhanced deliverability and down-funnel conversion insights. Endpoints POST /{Version}/{Phone-Number-ID}/marketing_messages POST /{Version}/{Phone-Number-ID}/marketing_messages Send marketing template messages using pre-approved templates. Supports optional product policy controls and message activity sharing settings. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required WhatsApp API version (e.g., v20.0) Phone-Number-IDstring·required WhatsApp Business Phone Number ID Required Content Type: application/json Schema: MarketingMessageRequestPayload Show child attributes MarketingMessageRequestPayload messaging_product"whatsapp"·required Messaging service used. Must be "whatsapp" recipient_type"individual"·required Type of recipient. Must be "individual" tostring·required WhatsApp ID or phone number of the message recipient type"template"·required Type of message. Must be "template" for marketing messages templateobject·required Show child attributes namestring·required Name of the template. languageLanguageObject·required Contains a language object. Specifies the language the template may be rendered in componentsarray of TemplateComponent Array of components objects containing the parameters of the message. Show child attributes components[]TemplateComponent product_policyOne of "CLOUD_API_FALLBACK", "STRICT" Optional product policy setting message_activity_sharingboolean Optional flag to control message activity sharing Responses Send marketing template messages using pre-approved templates. Supports optional product policy controls and message activity sharing settings. 200 Marketing message sent successfully Content Type: application/json Schema: MarketingMessageResponsePayload Show child attributes MarketingMessageResponsePayload contactsarray of object Show child attributes contacts[]object Show child attributes inputstring wa_idstring messagesarray of object Show child attributes messages[]object Show child attributes idstring message_statusOne of "accepted", "held_for_quality_assessment", "paused" The status of a WhatsApp message: accepted: The message has been accepted by WhatsApp and is being processed held_for_quality_assessment: The message is being held for quality assessment before delivery paused: The message delivery has been paused messaging_productstring 400 Bad Request - Invalid request parameters Content Type: application/json 401 Unauthorized - Invalid or missing access token Content Type: application/json 403 Forbidden - Template not approved or insufficient permissions Content Type: application/json Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Media Upload API | Developer Documentation WhatsApp Cloud API - Media Upload API Copy for LLM View as Markdown Version Upload media files (images, videos, audio, documents, stickers) to WhatsApp. Returns a media ID that can be used to send media messages. Supports multiple file formats and multipart form-data uploads. Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Message API | Developer Documentation WhatsApp Cloud API - Message API Copy for LLM View as Markdown Version Send and receive WhatsApp messages including text, media, templates, interactive messages, reactions, and more. Supports message status tracking, delivery receipts, and read confirmations. Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Phone Number API | Developer Documentation WhatsApp Cloud API - Phone Number APICopy for LLMView as MarkdownVersionWhatsApp Cloud API, hosted by Meta, is the official WhatsApp Business Platform API used for business messaging. This collection contains common queries, sample responses, and links to supporting documentation that can help you quickly get started with the API. Cloud API OverviewCloud API allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.https://developers.facebook.com/docs/whatsapp/cloud-api/overview Getting Started with Cloud APITo use the API and this collection you must have a Meta business portfolio, a WhatsApp Business Account, and a business phone number. If you complete the steps in the Cloud API Get Started guide, these assets will be created for you. Get Started as a Solution PartnerThis guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. Migrating from On-Premises API to Cloud APIThis guide explains how to migrate business phone numbers from On-Premises API to Cloud API. EnvironmentThis collection has a corresponding WhatsApp Cloud API Postman environment which you must select when using the collection. Set current values for the variables defined in this environment if you wish to use the collection to perform queries.You can find most of these values in the WhatsApp Manager or the WhatsApp > Getting Started panel in the app dashboard. However, if you have an access token and your business portfolio ID, you can use queries in the collection to get the remaining values. Access tokensThe API supports both user and system user access tokens. You can get a user access token by loading your app in the app dashboard and navigating to the WhatsApp > Getting Started panel.Since user access tokens expire after 24 hours, you'll likely want to generate a system user access token, which lasts up to 60 days (or permanently, if you wish). See Access Tokens to learn how to create a system user and system user access token.Once you have your token, save it as a current value in the environment. Business portfolio IDYou can get your business portfolio ID by signing into the Meta Business Suite. The ID appears in the URL as the business_id query string parameter value. Once you save this as a current value in the environment, go to the WhatsApp Business Account (WABA) folder and run the Get all owned WABAs query. This will return your WABA ID, which you can save to your environment and then use to determine your business phone number ID. PermissionsThe API only relies on two permissions:whatsapp_business_managementwhatsapp_business_messagingNote that if you get a user access token from the app dashboard, your app will automatically be granted these permissions (by you, on your behalf), so you can use the token to test right away.Queries that target your business portfolio require the business_management permission, which you may also need based on your business use case. Most developers do not need this permission, however, as accessing your business portfolio is uncommon, and the Meta Business Suite provides nearly all of this functionality anyway. Access token debuggerYou can paste any token you generate into the access token debugger to see what type of token it is and what permission you have granted to your app. PaginationEndpoints that return lists/collections may paginate results (you'll see previous and next properties in the response). Use the URLs from these properties to get the previous or next set of results. Note that if you click one of these links in Postman, it will open a new query in a new tab which you must save before running (otherwise it can't read your environment variables), so you may wish to cut and paste the URL and run the query in the same tab in which it was returned. WhatsApp Cloud API - Phone Number API | Developer Documentation WhatsApp Cloud API - Phone Number APICopy for LLMView as MarkdownVersionWhatsApp Cloud API, hosted by Meta, is the official WhatsApp Business Platform API used for business messaging. This collection contains common queries, sample responses, and links to supporting documentation that can help you quickly get started with the API. Cloud API OverviewCloud API allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.https://developers.facebook.com/docs/whatsapp/cloud-api/overview Getting Started with Cloud APITo use the API and this collection you must have a Meta business portfolio, a WhatsApp Business Account, and a business phone number. If you complete the steps in the Cloud API Get Started guide, these assets will be created for you. Get Started as a Solution PartnerThis guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. Migrating from On-Premises API to Cloud APIThis guide explains how to migrate business phone numbers from On-Premises API to Cloud API. EnvironmentThis collection has a corresponding WhatsApp Cloud API Postman environment which you must select when using the collection. Set current values for the variables defined in this environment if you wish to use the collection to perform queries.You can find most of these values in the WhatsApp Manager or the WhatsApp > Getting Started panel in the app dashboard. However, if you have an access token and your business portfolio ID, you can use queries in the collection to get the remaining values. Access tokensThe API supports both user and system user access tokens. You can get a user access token by loading your app in the app dashboard and navigating to the WhatsApp > Getting Started panel.Since user access tokens expire after 24 hours, you'll likely want to generate a system user access token, which lasts up to 60 days (or permanently, if you wish). See Access Tokens to learn how to create a system user and system user access token.Once you have your token, save it as a current value in the environment. Business portfolio IDYou can get your business portfolio ID by signing into the Meta Business Suite. The ID appears in the URL as the business_id query string parameter value. Once you save this as a current value in the environment, go to the WhatsApp Business Account (WABA) folder and run the Get all owned WABAs query. This will return your WABA ID, which you can save to your environment and then use to determine your business phone number ID. PermissionsThe API only relies on two permissions:whatsapp_business_managementwhatsapp_business_messagingNote that if you get a user access token from the app dashboard, your app will automatically be granted these permissions (by you, on your behalf), so you can use the token to test right away.Queries that target your business portfolio require the business_management permission, which you may also need based on your business use case. Most developers do not need this permission, however, as accessing your business portfolio is uncommon, and the Meta Business Suite provides nearly all of this functionality anyway. Access token debuggerYou can paste any token you generate into the access token debugger to see what type of token it is and what permission you have granted to your app. PaginationEndpoints that return lists/collections may paginate results (you'll see previous and next properties in the response). Use the URLs from these properties to get the previous or next set of results. Note that if you click one of these links in Postman, it will open a new query in a new tab which you must save before running (otherwise it can't read your environment variables), so you may wish to cut and paste the URL and run the query in the same tab in which it was returned. WhatsApp Cloud API - Phone Number API | Developer Documentation WhatsApp Cloud API - Phone Number APICopy for LLMView as MarkdownVersionWhatsApp Cloud API, hosted by Meta, is the official WhatsApp Business Platform API used for business messaging. This collection contains common queries, sample responses, and links to supporting documentation that can help you quickly get started with the API. Cloud API OverviewCloud API allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.https://developers.facebook.com/docs/whatsapp/cloud-api/overview Getting Started with Cloud APITo use the API and this collection you must have a Meta business portfolio, a WhatsApp Business Account, and a business phone number. If you complete the steps in the Cloud API Get Started guide, these assets will be created for you. Get Started as a Solution PartnerThis guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. Migrating from On-Premises API to Cloud APIThis guide explains how to migrate business phone numbers from On-Premises API to Cloud API. EnvironmentThis collection has a corresponding WhatsApp Cloud API Postman environment which you must select when using the collection. Set current values for the variables defined in this environment if you wish to use the collection to perform queries.You can find most of these values in the WhatsApp Manager or the WhatsApp > Getting Started panel in the app dashboard. However, if you have an access token and your business portfolio ID, you can use queries in the collection to get the remaining values. Access tokensThe API supports both user and system user access tokens. You can get a user access token by loading your app in the app dashboard and navigating to the WhatsApp > Getting Started panel.Since user access tokens expire after 24 hours, you'll likely want to generate a system user access token, which lasts up to 60 days (or permanently, if you wish). See Access Tokens to learn how to create a system user and system user access token.Once you have your token, save it as a current value in the environment. Business portfolio IDYou can get your business portfolio ID by signing into the Meta Business Suite. The ID appears in the URL as the business_id query string parameter value. Once you save this as a current value in the environment, go to the WhatsApp Business Account (WABA) folder and run the Get all owned WABAs query. This will return your WABA ID, which you can save to your environment and then use to determine your business phone number ID. PermissionsThe API only relies on two permissions:whatsapp_business_managementwhatsapp_business_messagingNote that if you get a user access token from the app dashboard, your app will automatically be granted these permissions (by you, on your behalf), so you can use the token to test right away.Queries that target your business portfolio require the business_management permission, which you may also need based on your business use case. Most developers do not need this permission, however, as accessing your business portfolio is uncommon, and the Meta Business Suite provides nearly all of this functionality anyway. Access token debuggerYou can paste any token you generate into the access token debugger to see what type of token it is and what permission you have granted to your app. PaginationEndpoints that return lists/collections may paginate results (you'll see previous and next properties in the response). Use the URLs from these properties to get the previous or next set of results. Note that if you click one of these links in Postman, it will open a new query in a new tab which you must save before running (otherwise it can't read your environment variables), so you may wish to cut and paste the URL and run the query in the same tab in which it was returned. WhatsApp Cloud API - Settings API | Developer Documentation WhatsApp Cloud API - Settings API Copy for LLM View as Markdown Version The Settings API allows you to configure various features and settings for your WhatsApp Business Account phone numbers. You can manage calling settings, user identity change settings, payload encryption, and data storage configurations. Select language Select status code Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Account Phone Number Verification - Verify Code API | Developer Documentation WhatsApp Business Account Phone Number Verification - Verify Code API Copy for LLM View as Markdown Version API for verifying phone number verification codes for WhatsApp Business Account phone numbers. This endpoint allows businesses to verify phone number verification codes sent during the phone number registration or verification process. POST /{Version}/{Phone-Number-ID}/verify_code Verify a phone number verification code for a WhatsApp Business Account phone number. This endpoint is used to complete the phone number verification process by submitting the verification code received via SMS or voice call. Use Cases: Complete phone number verification during initial setup Verify phone number ownership for messaging capabilities Finalize phone number registration process Complete phone number migration verification Rate Limiting: Verification attempts are rate-limited to prevent abuse. Failed attempts may result in temporary blocking. Use appropriate retry logic with exponential backoff. Security: Verification codes are time-limited (typically 10 minutes) and single-use. Multiple failed attempts may trigger additional security measures. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Phone-Number-IDstring·required The WhatsApp Business Account phone number ID that needs verification. This ID is provided when you add a phone number to your WhatsApp Business Account. Required Content Type: application/json Schema: VerifyCodeRequest Show child attributes VerifyCodeRequest codestring·required The verification code received via SMS or voice call Responses Verify a phone number verification code for a WhatsApp Business Account phone number. This endpoint is used to complete the phone number verification process by submitting the verification code received via SMS or voice call. Use Cases: Complete phone number verification during initial setup Verify phone number ownership for messaging capabilities Finalize phone number registration process Complete phone number migration verification Rate Limiting: Verification attempts are rate-limited to prevent abuse. Failed attempts may result in temporary blocking. Use appropriate retry logic with exponential backoff. Security: Verification codes are time-limited (typically 10 minutes) and single-use. Multiple failed attempts may trigger additional security measures. 200 Successfully verified the phone number verification code Content Type: application/json Schema: VerifyCodeResponse Show child attributes VerifyCodeResponse successboolean·required Indicates whether the verification code was successfully verified idstring The phone number ID that was verified 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Phone number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Invalid or expired verification code Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - WhatsApp Business QR Code Management API | Developer Documentation WhatsApp Cloud API - WhatsApp Business QR Code Management APICopy for LLMView as MarkdownVersionAPI for managing WhatsApp Business Account message QR code collections.Provides endpoints for listing all message QR codes and creating new ones.Message QR codes generate WhatsApp deep links with pre-filled messages that customerscan use to start conversations. Each QR code has a unique 14-character identifier.Requirements: WhatsApp Business Account with whatsapp_business_management permission,verified phone number, and valid system user access token. WhatsApp Cloud API - WhatsApp Business QR Code Management API | Developer Documentation WhatsApp Cloud API - WhatsApp Business QR Code Management APICopy for LLMView as MarkdownVersionAPI for managing WhatsApp Business Account message QR code collections.Provides endpoints for listing all message QR codes and creating new ones.Message QR codes generate WhatsApp deep links with pre-filled messages that customerscan use to start conversations. Each QR code has a unique 14-character identifier.Requirements: WhatsApp Business Account with whatsapp_business_management permission,verified phone number, and valid system user access token. WhatsApp Cloud API - WhatsApp Business QR Code Management API | Developer Documentation WhatsApp Cloud API - WhatsApp Business QR Code Management APICopy for LLMView as MarkdownVersionAPI for managing WhatsApp Business Account message QR code collections.Provides endpoints for listing all message QR codes and creating new ones.Message QR codes generate WhatsApp deep links with pre-filled messages that customerscan use to start conversations. Each QR code has a unique 14-character identifier.Requirements: WhatsApp Business Account with whatsapp_business_management permission,verified phone number, and valid system user access token. WhatsApp Cloud API - WhatsApp Business QR Code Management API | Developer Documentation WhatsApp Cloud API - WhatsApp Business QR Code Management APICopy for LLMView as MarkdownVersionAPI for managing WhatsApp Business Account message QR code collections.Provides endpoints for listing all message QR codes and creating new ones.Message QR codes generate WhatsApp deep links with pre-filled messages that customerscan use to start conversations. Each QR code has a unique 14-character identifier.Requirements: WhatsApp Business Account with whatsapp_business_management permission,verified phone number, and valid system user access token. WhatsApp Cloud API - WhatsApp Business QR Code Management API | Developer Documentation WhatsApp Cloud API - WhatsApp Business QR Code Management APICopy for LLMView as MarkdownVersionAPI for managing WhatsApp Business Account message QR code collections.Provides endpoints for listing all message QR codes and creating new ones.Message QR codes generate WhatsApp deep links with pre-filled messages that customerscan use to start conversations. Each QR code has a unique 14-character identifier.Requirements: WhatsApp Business Account with whatsapp_business_management permission,verified phone number, and valid system user access token. WhatsApp Business Pre-Verified Phone Number Partners API | Developer Documentation WhatsApp Business Pre-Verified Phone Number Partners API Copy for LLM View as Markdown Version API for retrieving partner businesses associated with a WhatsApp Business Pre-Verified Phone Number. This endpoint allows authorized applications to retrieve the list of partner businesses that have been granted access to a specific pre-verified phone number. GET /{Version}/{Pre-Verified-Phone-Number-ID}/partners Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required Your Pre-Verified Phone Number ID. This ID is provided when the pre-verified phone number is created and can be found in your WhatsApp Business Account management interface. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, created_time, updated_time, verification_status, primary_page, timezone_id, two_factor_type limitinteger [min: 1, max: 100] Maximum number of partner businesses to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use the 'after' cursor from a previous response to get the next page. beforestring Cursor for pagination. Use the 'before' cursor from a previous response to get the previous page. Responses Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved partner businesses for the pre-verified phone number Content Type: application/json Schema: WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse Show child attributes WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse dataarray of BusinessPartner·required List of partner businesses with access to the pre-verified phone number Show child attributes data[]BusinessPartner Business entity that has partner access to the pre-verified phone number Show child attributes idstring·required Unique identifier for the partner business namestring·required Name of the partner business created_timestring (date-time) ISO 8601 timestamp when the business was created updated_timestring (date-time) ISO 8601 timestamp when the business was last updated verification_statusOne of "not_verified", "pending", "verified" Business verification status primary_pagestring Primary Facebook Page ID associated with the business timezone_idinteger Timezone identifier for the business location two_factor_typeOne of "none", "admin_required" Two-factor authentication method configured for the business pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-Verified Phone Number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Pre-Verified Phone Number Partners API | Developer Documentation WhatsApp Business Pre-Verified Phone Number Partners API Copy for LLM View as Markdown Version API for retrieving partner businesses associated with a WhatsApp Business Pre-Verified Phone Number. This endpoint allows authorized applications to retrieve the list of partner businesses that have been granted access to a specific pre-verified phone number. GET /{Version}/{Pre-Verified-Phone-Number-ID}/partners Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required Your Pre-Verified Phone Number ID. This ID is provided when the pre-verified phone number is created and can be found in your WhatsApp Business Account management interface. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, created_time, updated_time, verification_status, primary_page, timezone_id, two_factor_type limitinteger [min: 1, max: 100] Maximum number of partner businesses to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use the 'after' cursor from a previous response to get the next page. beforestring Cursor for pagination. Use the 'before' cursor from a previous response to get the previous page. Responses Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved partner businesses for the pre-verified phone number Content Type: application/json Schema: WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse Show child attributes WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse dataarray of BusinessPartner·required List of partner businesses with access to the pre-verified phone number Show child attributes data[]BusinessPartner Business entity that has partner access to the pre-verified phone number Show child attributes idstring·required Unique identifier for the partner business namestring·required Name of the partner business created_timestring (date-time) ISO 8601 timestamp when the business was created updated_timestring (date-time) ISO 8601 timestamp when the business was last updated verification_statusOne of "not_verified", "pending", "verified" Business verification status primary_pagestring Primary Facebook Page ID associated with the business timezone_idinteger Timezone identifier for the business location two_factor_typeOne of "none", "admin_required" Two-factor authentication method configured for the business pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-Verified Phone Number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Pre-Verified Phone Number Partners API | Developer Documentation WhatsApp Business Pre-Verified Phone Number Partners API Copy for LLM View as Markdown Version API for retrieving partner businesses associated with a WhatsApp Business Pre-Verified Phone Number. This endpoint allows authorized applications to retrieve the list of partner businesses that have been granted access to a specific pre-verified phone number. GET /{Version}/{Pre-Verified-Phone-Number-ID}/partners Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required Your Pre-Verified Phone Number ID. This ID is provided when the pre-verified phone number is created and can be found in your WhatsApp Business Account management interface. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, created_time, updated_time, verification_status, primary_page, timezone_id, two_factor_type limitinteger [min: 1, max: 100] Maximum number of partner businesses to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use the 'after' cursor from a previous response to get the next page. beforestring Cursor for pagination. Use the 'before' cursor from a previous response to get the previous page. Responses Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved partner businesses for the pre-verified phone number Content Type: application/json Schema: WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse Show child attributes WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse dataarray of BusinessPartner·required List of partner businesses with access to the pre-verified phone number Show child attributes data[]BusinessPartner Business entity that has partner access to the pre-verified phone number Show child attributes idstring·required Unique identifier for the partner business namestring·required Name of the partner business created_timestring (date-time) ISO 8601 timestamp when the business was created updated_timestring (date-time) ISO 8601 timestamp when the business was last updated verification_statusOne of "not_verified", "pending", "verified" Business verification status primary_pagestring Primary Facebook Page ID associated with the business timezone_idinteger Timezone identifier for the business location two_factor_typeOne of "none", "admin_required" Two-factor authentication method configured for the business pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-Verified Phone Number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Pre-Verified Phone Number Partners API | Developer Documentation WhatsApp Business Pre-Verified Phone Number Partners API Copy for LLM View as Markdown Version API for retrieving partner businesses associated with a WhatsApp Business Pre-Verified Phone Number. This endpoint allows authorized applications to retrieve the list of partner businesses that have been granted access to a specific pre-verified phone number. GET /{Version}/{Pre-Verified-Phone-Number-ID}/partners Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Pre-Verified-Phone-Number-IDstring·required Your Pre-Verified Phone Number ID. This ID is provided when the pre-verified phone number is created and can be found in your WhatsApp Business Account management interface. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, created_time, updated_time, verification_status, primary_page, timezone_id, two_factor_type limitinteger [min: 1, max: 100] Maximum number of partner businesses to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use the 'after' cursor from a previous response to get the next page. beforestring Cursor for pagination. Use the 'before' cursor from a previous response to get the previous page. Responses Retrieve the list of partner businesses that have been granted access to a specific WhatsApp Business Pre-Verified Phone Number. Use Cases: Monitor partner business relationships and access permissions Verify which businesses have access to shared pre-verified phone numbers Retrieve partner business information for operational purposes Validate partnership configurations before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Partner information can be cached for moderate periods, but partnership relationships may change. Implement appropriate cache invalidation strategies. 200 Successfully retrieved partner businesses for the pre-verified phone number Content Type: application/json Schema: WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse Show child attributes WhatsAppBusinessPreVerifiedPhoneNumberPartnersResponse dataarray of BusinessPartner·required List of partner businesses with access to the pre-verified phone number Show child attributes data[]BusinessPartner Business entity that has partner access to the pre-verified phone number Show child attributes idstring·required Unique identifier for the partner business namestring·required Name of the partner business created_timestring (date-time) ISO 8601 timestamp when the business was created updated_timestring (date-time) ISO 8601 timestamp when the business was last updated verification_statusOne of "not_verified", "pending", "verified" Business verification status primary_pagestring Primary Facebook Page ID associated with the business timezone_idinteger Timezone identifier for the business location two_factor_typeOne of "none", "admin_required" Two-factor authentication method configured for the business pagingCursorPaging Cursor-based pagination information Show child attributes cursorsobject Show child attributes beforestring Cursor pointing to the start of the page of data that has been returned afterstring Cursor pointing to the end of the page of data that has been returned nextstring Graph API endpoint URL for the next page of results previousstring Graph API endpoint URL for the previous page of results 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Pre-Verified Phone Number ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Profile Node API | Developer Documentation WhatsApp Business Profile Node API Copy for LLM View as Markdown Version This endpoint allows applications to retrieve comprehensive information about WhatsApp Business Profiles, including profile details, contact information, and business metadata. This is essential for managing business profile lifecycle and understanding current configuration state. GET /{Version}/{WhatsApp-Business-Profile-ID} Retrieve comprehensive details about a WhatsApp Business Profile, including business information, contact details, and profile configuration. Use Cases: Retrieve business profile information and metadata Verify profile configuration and contact details Check profile status and business information Validate profile state before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Profile details can be cached for moderate periods, but business information may change occasionally. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Profile-IDstring·required Your WhatsApp Business Profile ID. This ID is provided when the profile is created and can be found in your WhatsApp Business Manager or through business management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id and any available profile fields). Available fields: id, account_name, description, email, about, address, vertical, websites, profile_picture_url, messaging_product Responses Retrieve comprehensive details about a WhatsApp Business Profile, including business information, contact details, and profile configuration. Use Cases: Retrieve business profile information and metadata Verify profile configuration and contact details Check profile status and business information Validate profile state before business operations Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Profile details can be cached for moderate periods, but business information may change occasionally. Implement appropriate cache invalidation strategies. 200 Successfully retrieved WhatsApp Business Profile details Content Type: application/json Schema: WhatsAppBusinessProfileNode Show child attributes WhatsAppBusinessProfileNode idstring·required Unique identifier for the WhatsApp Business Profile account_namestring Name of the business account descriptionstring Business description text emailstring (email) Contact email address of the business aboutstring About section text for the business profile addressstring Physical address of the business verticalWhatsAppBusinessVertical Industry vertical classification for the business websitesarray of string (uri) List of website URLs associated with the business Show child attributes websites[]string (uri) profile_picture_urlstring (uri) URL of the business profile picture profile_picture_handlestring Handle of the profile picture for upload operations messaging_product"whatsapp" The messaging service used 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Profile ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code POST /{Version}/{WhatsApp-Business-Profile-ID} Update the WhatsApp Business Profile information such as business description, email, address, and other profile details. This operation corresponds to the GraphWhatsAppBusinessProfilePost functionality. Use Cases: Update business profile information and metadata Modify contact details and business description Change business vertical classification Update website URLs and profile picture Maintain current business profile information Profile Picture Upload: It is recommended to use the Resumable Upload API to obtain an upload ID, then use this upload ID to obtain the picture handle for the profile_picture_handle field. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Profile-IDstring·required Your WhatsApp Business Profile ID. This ID is provided when the profile is created and can be found in your WhatsApp Business Manager or through business management APIs. Required Content Type: application/json Schema: WhatsAppBusinessProfileUpdateRequest Show child attributes WhatsAppBusinessProfileUpdateRequest messaging_product"whatsapp"·required The messaging service used for the request account_namestring Name of the business account descriptionstring Business description text emailstring (email) Contact email address of the business aboutstring About section text for the business profile addressstring Physical address of the business verticalWhatsAppBusinessVertical Industry vertical classification for the business websitesarray of string (uri) List of website URLs associated with the business Show child attributes websites[]string (uri) profile_picture_handlestring Handle of the profile picture generated from Resumable Upload API Responses Update the WhatsApp Business Profile information such as business description, email, address, and other profile details. This operation corresponds to the GraphWhatsAppBusinessProfilePost functionality. Use Cases: Update business profile information and metadata Modify contact details and business description Change business vertical classification Update website URLs and profile picture Maintain current business profile information Profile Picture Upload: It is recommended to use the Resumable Upload API to obtain an upload ID, then use this upload ID to obtain the picture handle for the profile_picture_handle field. Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully updated WhatsApp Business Profile Content Type: application/json Schema: WhatsAppBusinessProfileUpdateResponse Show child attributes WhatsAppBusinessProfileUpdateResponse idstring WhatsApp Business Profile ID that was updated successboolean Indicates if the update was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Profile ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Accept Deactivation Request API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Accept Deactivation Request API Copy for LLM View as Markdown Version API for accepting deactivation requests for WhatsApp Business Multi-Partner Solutions. This endpoint allows solution partners to accept pending deactivation requests for their Multi-Partner Solutions. POST /{Version}/{Solution-ID}/accept_deactivation_request Accepts a pending deactivation request for a WhatsApp Business Multi-Partner Solution. This endpoint completes the partner approval workflow by accepting a deactivation request that was previously initiated by another solution partner. Upon successful acceptance, the solution status transitions from ACTIVE to DEACTIVATED, and the pending request status changes from PENDING_DEACTIVATION to NONE. Important Business Logic: Solution must be in ACTIVE status with PENDING_DEACTIVATION pending status All outstanding payments and invoices must be settled before acceptance Active marketing campaigns must be concluded or transferred Webhook notifications will be sent to all solution partners upon completion Solution resources and permissions will be cleaned up according to policy Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version Solution-IDstring·required Unique identifier for the WhatsApp Business Solution Query Parameters fieldsstring Comma-separated list of fields to return in the response. Available Fields: id, name, status, status_for_pending_request, owner_permissions Default Fields: name, status, status_for_pending_request Optional Content Type: application/json Schema: object Responses Accepts a pending deactivation request for a WhatsApp Business Multi-Partner Solution. This endpoint completes the partner approval workflow by accepting a deactivation request that was previously initiated by another solution partner. Upon successful acceptance, the solution status transitions from ACTIVE to DEACTIVATED, and the pending request status changes from PENDING_DEACTIVATION to NONE. Important Business Logic: Solution must be in ACTIVE status with PENDING_DEACTIVATION pending status All outstanding payments and invoices must be settled before acceptance Active marketing campaigns must be concluded or transferred Webhook notifications will be sent to all solution partners upon completion Solution resources and permissions will be cleaned up according to policy 200 Deactivation request accepted successfully. Solution status updated to DEACTIVATED. Content Type: application/json Schema: WhatsAppBusinessSolution Show child attributes WhatsAppBusinessSolution idstring·required Unique identifier for the WhatsApp Business Solution namestring·required Human-readable name for the solution (UGC text, 2-75 characters) statusWhatsAppBusinessSolutionStatus·required Current status of the WhatsApp Business Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending requests for the solution owner_permissionsarray of WhatsAppBusinessAccountPermissionTask Array of permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access 400 Bad Request - Invalid request parameters or malformed solution ID format. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 401 Unauthorized - Invalid, missing, or expired access token. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 403 Forbidden - Insufficient permissions or app not authorized for this solution. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 404 Not Found - Solution ID does not exist or is not accessible to the requesting app. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 422 Unprocessable Entity - Valid parameters but business logic prevents processing (e.g., wrong solution state, outstanding payments). Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 429 Too Many Requests - Rate limit exceeded. Use exponential backoff for retries. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message 500 Internal Server Error - Unexpected server error. Retry with exponential backoff if is_transient is true. Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typeOne of "OAuthException", "GraphMethodException", "GraphAPIException"·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode fbtrace_idstring Internal trace ID for debugging is_transientboolean Whether this error might be resolved by retrying error_user_titlestring User-friendly error title error_user_msgstring User-friendly error message Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Access Token API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Access Token API Copy for LLM View as Markdown Version API for retrieving granular BISU (Business Integration System User) access tokens for Multi-Partner Solution partners. This endpoint allows solution partners to obtain granular access tokens that provide secure, scoped access to WhatsApp Business Accounts shared with their Multi-Partner Solution. GET /{Version}/{Solution-ID}/access_token Retrieve a granular BISU access token for accessing customer business resources through the Multi-Partner Solution. The token provides secure, scoped access to WhatsApp Business Accounts that have been shared with the solution. Use Cases: Obtain secure access tokens for partner applications to access customer business resources Enable multi-tenant partner architectures with dedicated tokens per customer business Support secure API operations on shared WhatsApp Business Accounts Implement proper security boundaries between different customer businesses Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Token Management: Access tokens are time-limited and should be refreshed before expiration. Store tokens securely and implement proper token rotation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required Your Multi-Partner Solution ID. This ID is provided when you create the solution and can be found in your Partner Dashboard or through solution management APIs. Query Parameters business_idstring·required The customer business ID for which you want to retrieve an access token. This must be a business that has shared a WhatsApp Business Account with your Multi-Partner Solution. Responses Retrieve a granular BISU access token for accessing customer business resources through the Multi-Partner Solution. The token provides secure, scoped access to WhatsApp Business Accounts that have been shared with the solution. Use Cases: Obtain secure access tokens for partner applications to access customer business resources Enable multi-tenant partner architectures with dedicated tokens per customer business Support secure API operations on shared WhatsApp Business Accounts Implement proper security boundaries between different customer businesses Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Token Management: Access tokens are time-limited and should be refreshed before expiration. Store tokens securely and implement proper token rotation strategies. 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution ID or business ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Reject Deactivation Request API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Reject Deactivation Request API Copy for LLM View as Markdown Version API for rejecting deactivation requests for Multi-Partner Solutions. This endpoint allows solution partners to reject pending deactivation requests for their Multi-Partner Solutions. POST /{Version}/{Solution-ID}/reject_deactivation_request Reject a pending deactivation request for a Multi-Partner Solution. This endpoint allows solution partners to decline deactivation requests from solution owners, maintaining the solution in its current active operational state. Use Cases: Reject deactivation requests from solution owners Maintain active solution partnerships when deactivation is not appropriate Respond programmatically to deactivation requests through API integration Keep solutions operational when business requirements or partnerships change Business Logic: Solution status remains ACTIVE after successful rejection StatusForPendingRequest transitions from PENDING_DEACTIVATION to NONE All existing solution configurations and permissions are preserved Solution partners receive notifications about the rejection decision Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Permissions: Requires whatsapp_business_management permission and valid solution partnership relationship. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required Your Multi-Partner Solution ID with a pending deactivation request. This ID is provided when you create the solution and can be found in your Partner Dashboard or through solution management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (name, status, status_for_pending_request). Available fields: id, name, status, status_for_pending_request, owner_app, owner_permissions Required Content Type: application/json Schema: object Show child attributes reject_deactivation_requestboolean·required Set to true to reject the pending deactivation request Responses Reject a pending deactivation request for a Multi-Partner Solution. This endpoint allows solution partners to decline deactivation requests from solution owners, maintaining the solution in its current active operational state. Use Cases: Reject deactivation requests from solution owners Maintain active solution partnerships when deactivation is not appropriate Respond programmatically to deactivation requests through API integration Keep solutions operational when business requirements or partnerships change Business Logic: Solution status remains ACTIVE after successful rejection StatusForPendingRequest transitions from PENDING_DEACTIVATION to NONE All existing solution configurations and permissions are preserved Solution partners receive notifications about the rejection decision Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Permissions: Requires whatsapp_business_management permission and valid solution partnership relationship. 200 Successfully rejected the deactivation request Content Type: application/json Schema: WhatsAppBusinessSolution Show child attributes WhatsAppBusinessSolution idstring·required Unique identifier for the Multi-Partner Solution namestring·required Human-readable name of the Multi-Partner Solution statusWhatsAppBusinessSolutionStatus·required Current effective status of the Multi-Partner Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending solution status transition requests owner_appApplicationNode Meta application that owns the Multi-Partner Solution Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application owner_permissionsarray of WhatsAppBusinessAccountPermissionTask List of WhatsApp Business Account permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or unauthorized access Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution not found or not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Invalid solution state or business logic violation Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error type classification codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Send Deactivation Request API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Send Deactivation Request API Copy for LLM View as Markdown Version API for sending deactivation requests for Multi-Partner Solutions. This endpoint allows solution partners to request deactivation of their Multi-Partner Solutions. POST /{Version}/{Solution-ID}/send_deactivation_request Submit a deactivation request for a Multi-Partner Solution. This initiates a workflow to transition the solution from its current state to deactivated, following proper business validation and approval processes. Use Cases: Request deactivation of an active Multi-Partner Solution Initiate solution lifecycle transition management Trigger business workflow for solution deactivation approval Programmatically manage solution lifecycle states Business Logic: Solution must be in ACTIVE or INITIATED state to be eligible for deactivation Deactivation requests are processed asynchronously Solution status will transition to PENDING_DEACTIVATION during processing Final deactivation requires business approval workflow completion Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Workflow: Validate solution ownership and permissions Check solution eligibility for deactivation Submit deactivation request to business workflow Return confirmation with tracking identifier Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required Your Multi-Partner Solution ID. This ID is provided when you create the solution and can be found in your Partner Dashboard or through solution management APIs. Optional Content Type: application/json Schema: WhatsAppBusinessSolutionDeactivationRequest Show child attributes WhatsAppBusinessSolutionDeactivationRequest reasonstring Optional reason for the deactivation request Responses Submit a deactivation request for a Multi-Partner Solution. This initiates a workflow to transition the solution from its current state to deactivated, following proper business validation and approval processes. Use Cases: Request deactivation of an active Multi-Partner Solution Initiate solution lifecycle transition management Trigger business workflow for solution deactivation approval Programmatically manage solution lifecycle states Business Logic: Solution must be in ACTIVE or INITIATED state to be eligible for deactivation Deactivation requests are processed asynchronously Solution status will transition to PENDING_DEACTIVATION during processing Final deactivation requires business approval workflow completion Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Workflow: Validate solution ownership and permissions Check solution eligibility for deactivation Submit deactivation request to business workflow Return confirmation with tracking identifier 200 Successfully submitted deactivation request Content Type: application/json Schema: WhatsAppBusinessSolutionDeactivationResponse Show child attributes WhatsAppBusinessSolutionDeactivationResponse successboolean·required Indicates whether the deactivation request was successfully submitted messagestring·required Human-readable message describing the result request_idstring Unique identifier for tracking the deactivation request 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Solution is not eligible for deactivation Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Solution Accept API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Solution Accept API Copy for LLM View as Markdown Version API for accepting Multi-Partner Solution partnership invitations. This endpoint allows partner applications to accept invitations to participate in Multi-Partner Solutions. POST /{Version}/{Solution-ID}/accept Accept an invitation to participate in a Multi-Partner Solution as a partner application. This endpoint transitions the partner's status from NOTIFICATION_SENT to ACCEPTED, enabling the solution to progress toward ACTIVE status once all required partners accept. Use Cases: Accept partnership invitations for Multi-Partner Solutions Activate partner participation in existing solutions Confirm partner app's commitment to solution terms and conditions Enable solution workflow progression from INITIATED to ACTIVE status Business Logic: Only invited partner apps can accept solution invitations Solution must be in INITIATED status to accept partnerships Partner status transitions from NOTIFICATION_SENT to ACCEPTED Solution may become ACTIVE once all required partners accept Acceptance creates formal partnership agreement between apps Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Validation: Partner app must have received a valid solution invitation Solution must exist and be accessible to the partner app Partner app must have proper permissions and capabilities Acceptance request must include valid partner app identification Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required ID of the Multi-Partner Solution to accept. This ID is provided in the original invitation and can be found in partner notifications or solution management interfaces. Required Content Type: application/json Schema: WhatsAppBusinessSolutionAcceptRequest Show child attributes WhatsAppBusinessSolutionAcceptRequest partner_app_idstring·required ID of the partner application accepting the solution invitation. This must match the app ID that received the original invitation. log_session_idstring Optional session identifier for logging and debugging purposes. Used to track the acceptance flow across multiple API calls. Responses Accept an invitation to participate in a Multi-Partner Solution as a partner application. This endpoint transitions the partner's status from NOTIFICATION_SENT to ACCEPTED, enabling the solution to progress toward ACTIVE status once all required partners accept. Use Cases: Accept partnership invitations for Multi-Partner Solutions Activate partner participation in existing solutions Confirm partner app's commitment to solution terms and conditions Enable solution workflow progression from INITIATED to ACTIVE status Business Logic: Only invited partner apps can accept solution invitations Solution must be in INITIATED status to accept partnerships Partner status transitions from NOTIFICATION_SENT to ACCEPTED Solution may become ACTIVE once all required partners accept Acceptance creates formal partnership agreement between apps Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Validation: Partner app must have received a valid solution invitation Solution must exist and be accessible to the partner app Partner app must have proper permissions and capabilities Acceptance request must include valid partner app identification 200 Multi-Partner Solution invitation accepted successfully. The partner's status has been updated to ACCEPTED and the solution may progress toward ACTIVE status. Content Type: application/json Schema: WhatsAppBusinessSolutionAcceptResponse Show child attributes WhatsAppBusinessSolutionAcceptResponse solution_idstring·required ID of the Multi-Partner Solution that was accepted partner_statusWhatsAppBusinessSolutionPartnerStatus·required Current status of the partner's participation in the Multi-Partner Solution successboolean·required Indicates whether the acceptance was successful messagestring Human-readable confirmation message update_timestring (date-time) Timestamp when the acceptance was processed 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or not invited to solution Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Solution cannot be accepted in current state Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Solution Details API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Solution Details API Copy for LLM View as Markdown Version API for retrieving Multi-Partner Solution details and configuration information. This endpoint allows solution partners to retrieve comprehensive information about their Multi-Partner Solutions, including status, permissions, and ownership details. GET /{Version}/{Solution-ID} Retrieve comprehensive details about a Multi-Partner Solution, including its current status, pending status transitions, ownership information, and granted permissions. Use Cases: Monitor solution lifecycle and status changes Verify solution configuration before business onboarding Check pending approval requests and status transitions Retrieve solution ownership and permission details Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution details can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required Your Multi-Partner Solution ID. This ID is provided when you create the solution and can be found in your Partner Dashboard or through solution management APIs. Query Parameters fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (name, status, status_for_pending_request). Available fields: id, name, status, status_for_pending_request, owner_app, owner_permissions Responses Retrieve comprehensive details about a Multi-Partner Solution, including its current status, pending status transitions, ownership information, and granted permissions. Use Cases: Monitor solution lifecycle and status changes Verify solution configuration before business onboarding Check pending approval requests and status transitions Retrieve solution ownership and permission details Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: Solution details can be cached for short periods, but status information may change frequently during transitions. Implement appropriate cache invalidation strategies. 200 Successfully retrieved Multi-Partner Solution details Content Type: application/json Schema: WhatsAppBusinessSolution Show child attributes WhatsAppBusinessSolution idstring·required Unique identifier for the Multi-Partner Solution namestring·required Human-readable name of the Multi-Partner Solution statusWhatsAppBusinessSolutionStatus·required Current effective status of the Multi-Partner Solution Show child attributes status_for_pending_requestWhatsAppBusinessSolutionPendingStatus·required Status of any pending solution status transition requests owner_appApplicationNode Meta application that owns the Multi-Partner Solution Show child attributes idstring Unique identifier for the Meta application namestring Name of the Meta application owner_permissionsarray of WhatsAppBusinessAccountPermissionTask List of WhatsApp Business Account permissions granted to the solution owner Show child attributes owner_permissions[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Business Multi-Partner Solutions - Solution Reject API | Developer Documentation WhatsApp Business Multi-Partner Solutions - Solution Reject API Copy for LLM View as Markdown Version API for rejecting Multi-Partner Solution partnership requests or deactivation requests. This endpoint allows solution partners to reject pending partnership requests or deactivation requests for Multi-Partner Solutions. POST /{Version}/{Solution-ID}/reject Reject a pending partnership request or deactivation request for a Multi-Partner Solution. This endpoint allows solution owners to decline incoming requests and maintain control over their solution partnerships and lifecycle. Use Cases: Reject partnership requests from unauthorized or incompatible applications Decline deactivation requests to keep solutions active Maintain solution security and partnership quality Control solution access and collaboration boundaries Request Types: PARTNERSHIP_REQUEST: Reject an incoming partnership request from another app DEACTIVATION_REQUEST: Reject a request to deactivate the solution Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Business Logic: Only solution owners can reject requests for their solutions Partnership rejections require the partner_app_id parameter Rejection actions are permanent and cannot be undone through this API Rejected requests may need to be resubmitted through proper channels Request Syntax Try it Select language Select status code Header Parameters User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. Solution-IDstring·required Your Multi-Partner Solution ID. This ID is provided when you create the solution and can be found in your Partner Dashboard or through solution management APIs. Required Content Type: application/json Schema: SolutionRejectRequest Show child attributes SolutionRejectRequest request_typeOne of "PARTNERSHIP_REQUEST", "DEACTIVATION_REQUEST"·required Type of request being rejected rejection_reasonstring Optional reason for rejecting the request partner_app_idstring The app ID of the requesting partner. Required when request_type is PARTNERSHIP_REQUEST, not used for DEACTIVATION_REQUEST Responses Reject a pending partnership request or deactivation request for a Multi-Partner Solution. This endpoint allows solution owners to decline incoming requests and maintain control over their solution partnerships and lifecycle. Use Cases: Reject partnership requests from unauthorized or incompatible applications Decline deactivation requests to keep solutions active Maintain solution security and partnership quality Control solution access and collaboration boundaries Request Types: PARTNERSHIP_REQUEST: Reject an incoming partnership request from another app DEACTIVATION_REQUEST: Reject a request to deactivate the solution Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Business Logic: Only solution owners can reject requests for their solutions Partnership rejections require the partner_app_id parameter Rejection actions are permanent and cannot be undone through this API Rejected requests may need to be resubmitted through proper channels 200 Successfully rejected the Multi-Partner Solution request Content Type: application/json Schema: SolutionRejectResponse Show child attributes SolutionRejectResponse successboolean·required Indicates whether the rejection was successful solution_idstring·required The ID of the Multi-Partner Solution rejected_request_typeOne of "PARTNERSHIP_REQUEST", "DEACTIVATION_REQUEST"·required Type of request that was rejected rejection_timestampstring (date-time) ISO 8601 timestamp when the rejection was processed partner_app_idstring App ID of the partner whose request was rejected (for partnership rejections) 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or not solution owner Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 404 Not Found - Solution ID does not exist or request not found Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request cannot be processed due to business logic constraints Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes GraphAPIError errorobject·required Show child attributes messagestring·required Human-readable error message typestring·required Error category type codeinteger·required Numeric error code error_subcodeinteger More specific error subcode when available fbtrace_idstring Unique identifier for debugging and support requests with Meta is_transientboolean Indicates whether this error is temporary and the request should be retried error_user_titlestring User-friendly error title for display purposes error_user_msgstring User-friendly error message for display purposes Select language Select status code Authentication Scheme Type Location bearerAuth HTTP Bearer Header: Authorization Usage Examples bearerAuth: Include Authorization: Bearer your-token-here in request headers Global Authentication Requirements All endpoints require: bearerAuth WhatsApp Cloud API - Phone Number API | Developer Documentation WhatsApp Cloud API - Phone Number APICopy for LLMView as MarkdownVersionWhatsApp Cloud API, hosted by Meta, is the official WhatsApp Business Platform API used for business messaging. This collection contains common queries, sample responses, and links to supporting documentation that can help you quickly get started with the API. Cloud API OverviewCloud API allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.https://developers.facebook.com/docs/whatsapp/cloud-api/overview Getting Started with Cloud APITo use the API and this collection you must have a Meta business portfolio, a WhatsApp Business Account, and a business phone number. If you complete the steps in the Cloud API Get Started guide, these assets will be created for you. Get Started as a Solution PartnerThis guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. Migrating from On-Premises API to Cloud APIThis guide explains how to migrate business phone numbers from On-Premises API to Cloud API. EnvironmentThis collection has a corresponding WhatsApp Cloud API Postman environment which you must select when using the collection. Set current values for the variables defined in this environment if you wish to use the collection to perform queries.You can find most of these values in the WhatsApp Manager or the WhatsApp > Getting Started panel in the app dashboard. However, if you have an access token and your business portfolio ID, you can use queries in the collection to get the remaining values. Access tokensThe API supports both user and system user access tokens. You can get a user access token by loading your app in the app dashboard and navigating to the WhatsApp > Getting Started panel.Since user access tokens expire after 24 hours, you'll likely want to generate a system user access token, which lasts up to 60 days (or permanently, if you wish). See Access Tokens to learn how to create a system user and system user access token.Once you have your token, save it as a current value in the environment. Business portfolio IDYou can get your business portfolio ID by signing into the Meta Business Suite. The ID appears in the URL as the business_id query string parameter value. Once you save this as a current value in the environment, go to the WhatsApp Business Account (WABA) folder and run the Get all owned WABAs query. This will return your WABA ID, which you can save to your environment and then use to determine your business phone number ID. PermissionsThe API only relies on two permissions:whatsapp_business_managementwhatsapp_business_messagingNote that if you get a user access token from the app dashboard, your app will automatically be granted these permissions (by you, on your behalf), so you can use the token to test right away.Queries that target your business portfolio require the business_management permission, which you may also need based on your business use case. Most developers do not need this permission, however, as accessing your business portfolio is uncommon, and the Meta Business Suite provides nearly all of this functionality anyway. Access token debuggerYou can paste any token you generate into the access token debugger to see what type of token it is and what permission you have granted to your app. PaginationEndpoints that return lists/collections may paginate results (you'll see previous and next properties in the response). Use the URLs from these properties to get the previous or next set of results. Note that if you click one of these links in Postman, it will open a new query in a new tab which you must save before running (otherwise it can't read your environment variables), so you may wish to cut and paste the URL and run the query in the same tab in which it was returned. WhatsApp Cloud API - Register API | Developer Documentation WhatsApp Cloud API - Register APICopy for LLMView as MarkdownVersionWhatsApp Cloud API, hosted by Meta, is the official WhatsApp Business Platform API used for business messaging. This collection contains common queries, sample responses, and links to supporting documentation that can help you quickly get started with the API. Cloud API OverviewCloud API allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.https://developers.facebook.com/docs/whatsapp/cloud-api/overview Getting Started with Cloud APITo use the API and this collection you must have a Meta business portfolio, a WhatsApp Business Account, and a business phone number. If you complete the steps in the Cloud API Get Started guide, these assets will be created for you. Get Started as a Solution PartnerThis guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. Migrating from On-Premises API to Cloud APIThis guide explains how to migrate business phone numbers from On-Premises API to Cloud API. EnvironmentThis collection has a corresponding WhatsApp Cloud API Postman environment which you must select when using the collection. Set current values for the variables defined in this environment if you wish to use the collection to perform queries.You can find most of these values in the WhatsApp Manager or the WhatsApp > Getting Started panel in the app dashboard. However, if you have an access token and your business portfolio ID, you can use queries in the collection to get the remaining values. Access tokensThe API supports both user and system user access tokens. You can get a user access token by loading your app in the app dashboard and navigating to the WhatsApp > Getting Started panel. Alternatively you can use the Graph API Explorer to generate one.Since user access tokens expire after 24 hours, you'll likely want to generate a system user access token, which lasts up to 60 days (or permanently, if you wish). See Access Tokens to learn how to create a system user and system user access token.Once you have your token, save it as a current value in the environment. Business portfolio IDYou can get your business portfolio ID by signing into the Meta Business Suite. The ID appears in the URL as the business_id query string parameter value. Once you save this as a current value in the environment, go to the WhatsApp Business Account (WABA) folder and run the Get all owned WABAs query. This will return your WABA ID, which you can save to your environment and then use to determine your business phone number ID. PermissionsThe API only relies on two permissions:whatsapp_business_managementwhatsapp_business_messagingNote that if you get a user access token from the app dashboard, your app will automatically be granted these permissions (by you, on your behalf), so you can use the token to test right away.Queries that target your business portfolio require the business_management permission, which you may also need based on your business use case. Most developers do not need this permission, however, as accessing your business portfolio is uncommon, and the Meta Business Suite provides nearly all of this functionality anyway. Access token debuggerYou can paste any token you generate into the access token debugger to see what type of token it is and what permission you have granted to your app. PaginationEndpoints that return lists/collections may paginate results (you'll see previous and next properties in the response). Use the URLs from these properties to get the previous or next set of results. Note that if you click one of these links in Postman, it will open a new query in a new tab which you must save before running (otherwise it can't read your environment variables), so you may wish to cut and paste the URL and run the query in the same tab in which it was returned. Solution Providers Solution providers | Developer Documentation Solution providersUpdated: Nov 14, 2025This documentation contains information, instructions, and resources for solution providers — businesses that provide, or want to provide, WhatsApp messaging services to other businesses. If you are building an app that will not be used by other businesses, refer to our Cloud API Get Started guide instead.Solution providers are business entities that deploy value-added solutions as WhatsApp authorized service providers on behalf of their business customers. Solution providers include Solution Partners, Tech Providers, and Tech Partners. Solution PartnersSolution Partners are Meta Business Partners⁠ that provide a full range of WhatsApp Business Platform services to other businesses, such as messaging services, billing, integration support, and customer support.Solution Partners have credit lines⁠ which can be extended to business customers who they bring on board, thus removing the need for those customers to enter their own payment method during the onboarding process. Furthermore, Solution Providers are able to directly invoice their customers for the WhatsApp Business Platform services provided through their apps.In addition, Solution Partners have access to Direct Support and are eligible to participate in the Meta Business Partner SMB Accelerator Program⁠, which offers incentive, accreditation, and enablement services.Note that becoming a Solution Provider is a lengthy process, so if you don’t need a credit line and don’t need to invoice your business customers for API usage directly, consider becoming a Tech Provider instead.See Get started for solution partners. Tech ProvidersTech Providers are similar to Solution Partners in that they also can offer a full range of WhatsApp Business Platform services to other businesses, either by providing these services on their own, or by partnering with a Solution Partner who already offers these services.Unlike Solution Providers, however, Tech Providers do not have credit lines. Instead, business customers onboarded by Tech Providers must provide their own payment method after onboarding is complete. Meta will then bill these customers for API usage, and the Tech Provider will bill for other services.Tech Providers also cannot participate in the Meta Business Partner SMB Accelerator Program⁠, unless they upgrade to a Tech Partner. However, Tech Providers do have access to Direct Support.To learn how to become a Tech Provider, see Become a Tech Provider. Tech PartnersTech Partners are Tech Providers who are, or are eligible to become, Meta Business Partners⁠. Tech Providers who apply to become a Meta Business Partner and are approved are eligible to participate in the Meta Business Partner SMB Accelerator Program⁠.To learn how to upgrade to a Tech Partner, see Upgrading to a Tech Partner. Other partnersIf you just want to use Meta Business Suite to provide WhatsApp messaging-related services to business customers (i.e. you don’t need API access), you only need a verified business portfolio. Go to https://business.facebook.com⁠ and create a business portfolio, or sign into your existing Meta Business Suite account if you already have one.Complete the business verification steps⁠ described in our Help Center article.Once your business is verified, provide your business portfolio ID to any business customers for whom you wish to provide service, and ask them to share their WhatsApp Business Account with you. Once shared, you can use Meta Business Suite to access their account and provider service. Comparison Solution Partners Tech Providers Tech Partners Can offer full WhatsApp Business Platform services to onboarded customers Yes Yes Yes Has a credit line Yes No No Customers bypass payment method collection Yes No No Bills customers directly for API usage (vs. Meta billing customers for usage) Yes No No Is a Meta Business Partner Yes No Yes Eligible for accelerator program Yes No Yes Access to Direct Support Yes Yes Yes Onboarding business customersThere are multiple ways for you to onboard business customers. Embedded SignupEmbedded Signup is a scalable, authentication and authorization interface that can be launched directly from your website or customer portal. Embedded Signup automatically generates all required WhatsApp assets for business customers who successfully complete the flow, and authorizes your app to access those assets. Hosted Embedded SignupHosted Embedded Signup (“Hosted ES”) is an alternative and simpler way of implementing Embedded Signup that doesn’t require you to configure and host the implementation code on your website or portal. Partner-initiated account creationIf you are a Solution Partner, you can initiate WhatsApp Business Account creation for a business customer who can then use Meta Business Suite to approve or decline creation. Meta Business SuiteYour business customers can use Meta Business Suite to create a WhatsApp Business Account on their own and share it with you. Multi-Partner SolutionsMulti-Partner Solutions allow solution partners to jointly manage onboarded business customer assets in order to provide comprehensive WhatsApp messaging services. For example, if you are a Tech Provider, you may wish to create a multi-partner solution with a Solution Partner who can share their credit line with business customers onboarded via your joint solution. Access TokensIf you are a Tech Provider or Tech Partner, you should use business tokens exclusively. If you are a Solution Partner, you should use a system token only when sharing your credit line with onboarded business customers; in all other cases, use business tokens. System tokensSystem tokens should only be used by Solution Partners, and only when sharing credit lines with onboarded business customers; at all other times, use a business token instead.System tokens are described in our API documentation, as they are used by non-solution partners as well. See System User Access tokens to learn how to create a system user and token.When creating your system user, aside from granting it any permissions and roles your app needs, also grant it the Finance editor role: Sign into the Meta Business Suite⁠.Locate your business portfolio in the top-left dropdown menu and click its Settings (gear) icon.Click Business settings.Navigate to Users > System Users.Edit the user and grant it the Finance editor role.This will allow your app to use the API to share your credit line with onboarded customers. Business tokensBusiness tokens are access tokens scoped to individual onboarded business customers. Use these tokens when accessing onboarded customer data, such as WhatsApp Business Accounts, message templates, business phone numbers, and when sending and receiving messages for your customers.To get a business token that is scoped to a customer, you must exchange a code returned to you when that customer completes the Embedded Signup flow. This process is described in the Onboarding Business Customers section of the Embedded Signup documentation. PermissionsThe permissions your app requires from onboarded customers depends on the services you provide. These are described in broad terms below but are largely determined by the endpoints your app will be querying.The most commonly needed permissions are: whatsapp_business_management — necessary if your app needs access to onboarded customer WhatsApp Business Account settings and message templates.whatsapp_business_messaging — necessary if your app needs access to onboarded customer business phone number settings, or if your app will be used by customers to send and receive messages.Note that before your app can be granted these permissions by your business customers, the permissions must be approved through the App Review process. App ReviewBefore you can officially begin onboarding business customers, you must submit your app for App Review and request advanced access approval for any permissions your app requires.If advanced access is not approved for a given permission, the permission will not appear in the Embedded Signup flow and your business customers will be unable to grant it to your app. Business VerificationIn order to be eligible for increased messaging limits, business phone number limits, and Official Business Account status, your business customers must verify their business. Your business customers can submit their business for verification by following the instructions in the following Help Center article:How to Verify Your Business on Meta⁠Alternatively, if you are a Select Solution or Premier Solution Partner, you can submit a customer’s business for verification on their behalf, which has a much faster turnaround time. See Partner-led Business Verification. Become a Tech Provider | Developer Documentation Become a Tech Provider Updated: Nov 20, 2025 This document describes the steps you must take to become a Tech Provider. As a Tech Provider, you can independently provide all WhatsApp messaging services to business customers who you have onboarded, or you can work with a Solution Partner to jointly offer these services. If you are partnering with a Solution Partner, ask them for their app ID, which you will need to complete these steps. Before you start You need the following:A Meta app with the WhatsApp use case and a connected business portfolio⁠ During the app creation process you can create a business portfolio. If you prefer to onboard with a Solution Partner, you will need to provide your partner’s app ID. Go to the app dashboard In the Meta App Dashboard go to Use cases > Customize (pencil icon) and click the Customize button for the WhatsApp use case, then select Tech Provider onboarding from the left-side menu. On this page of the dashboard, you will find links to the WhatsApp Embedded Signup developer documentation, Developer Support, and Success Stories as well as steps to complete the Tech Provider onboarding process. Step 1: Verify your business To become a tech provider you need to verify your business with Meta⁠. If you already have a verified business, and linked it to your app during the app creation process, this step will be marked as completed and you can start the app review process. Click Start verification to verify your business. You’ll need the following information:Verify business details – Provide your business name, address, phone number, email and website for verification.Confirm your connection – Select a way for us to get in touch to confirm your connection to the business.Upload documents – You might need to upload accepted documents to confirm these details if your business is not found. Your business must be verified before you can start the app review process. Step 2: App Review Once you have completed business verification, you can submit your app for App Review. You’ll need to complete the following tasks:Review your app settingsCreate and submit videos of your appSubmit documentation for App Review Review your app settings Your app will need basic settings such as an app icon, privacy policy, and app category. Videos To pass App Review, you need to submit video evidence of your capabilities to send messages and manage templates.The first video must show a message created and sent from your app and received in the WhatsApp client (mobile app or web app).The second video must show your app being used to create a message template. If you are partnering with a Solution Partner, you can use your current integration with them to demostrate these actions. Submit documentation for App Review Get approval to access advanced permissions and features so that your can manage your clients’ accounts and information. App Review is the process that will grant you advanced access to the following permissions which are required to become a Tech Provider.Advanced access to whatsapp_business_messaging will allow you to send messages for customers.Advanced access to whatsapp_business_management allows you to onboard customers and manage their assets. Click the Begin App Review button to start your submission. Learn more about App Review. Onboard with an existing Solution Partner If you prefer to onboard with a Solution Partner, click the Onboard with a Solution Partner button at the bottom of the page. After clicking the Onboard with a Solution Partner button, the Tech Provider onboarding page will refresh to this flow. The flow is identical to the Tech Provider flow with the additional App Review step to Create a partner solution by entering your partner’s app ID to create a partner solution. To onboard without a partner, you can do so by clicking the Onboard without a partner button at the bottom of the page. Support Confirmed Tech Providers have access to all support channels. See Support. Next stepsOnboarding business customers - Onboarding business customers via Embedded Signup.Webhooks - Before your app users can use your app to send and receive messages or manage templates, you must set up Webhooks.Billing - Your onboarded business customers must add a credit card to your WhatsApp Business Platform Account⁠. Get started as a Solution Partner | Developer Documentation Get started as a Solution Partner Updated: Dec 12, 2025 This guide goes over the steps Solution Partners need to take in order to offer the Cloud API to their customers. There are 4 main stages:Prepare & PlanSet up AssetsSign ContractsBuild Integration After you're done, please keep up with monthly updates. Prepare & plan Read documentation Before you start, we recommend reading through our developer documentation and our Postman collection?. This helps you understand how the Cloud API works, including how to get started and migrate numbers. Plan onboarding & migration We recommend that you use Embedded Signup to onboard new business customers to the Cloud API. If you haven't already, implement Embedded Signup. Embedded Signup is the fastest and easiest way to register business customers, enabling them to start sending messages in less than five minutes. Set up assets To use the Cloud API, Solution Partners need to have the following assets: Asset Specific Instructions Business portfolio You can use an existing one, or set up a new one?. Save the business portfolio ID. WhatsApp Business Account (WABA) See Create a WhatsApp Business Account for the WhatsApp Business API? for help. Meta App If you don't have an app, you need to create one with the Business type. Remember to add a display name and a contact email to your app. As a (Solution Partner), your app must go through App Review and request Advanced Access to the following permissions: whatsapp_business_management - Used to manage phone numbers, message templates, registration, business profile under a WhatsApp Business Account. To get this permission, your app must go through App Review. whatsapp_business_messaging - Used to send/receive messages from WhatsApp users, upload/download media under a WhatsApp Business Account. To get this permission, your app must go through App Review. whatsapp_business_manage_events - Used to log events-such as purchases, add-to-cart actions, leads, and more under a WhatsApp Business Account. Only request this permission if you are using the Marketing Messages API for WhatsApp with Conversions API. To get this permission, your app must go through App Review. As a Solution Partner, you can also feel free to use the same Meta app across different clients and WABAs. But be aware that each app can only have one webhook endpoint and each app needs to go through App Review. System User See Add system users to your business portfolio? for help. Currently, a Meta App with whatsapp_business_messaging, whatsapp_business_management, whatsapp_business_manage_events, and business_messaging permissions has access to up to:1 admin system user1 employee system user We recommend using the admin system user for your production deployment. See About business portfolio access? for more information. Business Phone Number This is the phone number the business will use to send messages. Phone numbers need to be verified through SMS/voice call. For Solution Partners and Direct Developers: If you wish to use your own number, then you should add a phone number? in WhatsApp Manager and verify it with the verify endpoint via Graph API. For business customers of Solution Partners: If you wish to use your own number, then you should add and verify their numbers using the Solution Partner's Embedded Signup flow. There is no limit to the amount of business phone numbers that can be onboarded to the Cloud API. Consumer Phone Number This is a phone number that is currently using the consumer WhatsApp app. This number will be receiving the messages sent by your business phone number. Sign contracts Accepting Terms of Service In order to access the WhatsApp Business Messaging Cloud API you need to first accept the WhatsApp Business Platform Terms of Service on behalf of your business. To do so, navigate to WhatsApp Manager? and accept the Terms of Service in the informational banner. For any new Cloud API businesses, you will need to accept Terms of Service before you can start using Cloud API. Registration calls will fail until you accept the Terms of Service. You as a developer need to accept the Terms of Service. If you are a Solution Partner, you do not need your customers to accept. Build integration Step 1: Get system user access token Graph API calls use access tokens for authentication. For more information, see Access Tokens. We recommend using your system user to generate your token. To generate a system user access token: Go to Business portfolio? > Business Settings > Users > System Users to view the system user you created. Click on that user and select Add Assets. This action launches a new window. Under Select Asset Type on the left side pane, select Apps. Under Select Assets, choose the Meta app you want to use (your app must have the correct permissions). Enable Develop App for that app. Select Save Changes to save your settings and return to the system user main screen. Now you are ready to generate your token. In the system user main screen, click Generate Token and select your Meta app. After selecting the app, you will see a list of available permissions. Select whatsapp_business_management , whatsapp_business_messaging , and whatsapp_business_manage_events . Click Generate Token. A new window opens with your system user, assigned app and access token. Save your token. Optionally, you can click on your token and see the Token Debugger. In your debugger, you should see the permissions you have selected. You can also directly paste your token into the Access Token Debugger. Step 2: Set up webhooks With Webhooks set up, you can receive real-time HTTP notifications from the WhatsApp Business Platform. This means you get notified when, for example, you get a message from a customer or there are changes to your WhatsApp Business Account (WABA). To set up your webhook endpoint, you need to create an internet-facing web server with a URL that meets Meta's and WhatsApp's requirements. See our Webhooks document for more information. If you need an endpoint for testing purposes, you can deploy a test app that simply dumps webhook payloads to your console. App setup Once the endpoint is ready, configure it to be used by your Meta app: In the App Dashboard, go to WhatsApp > Configuration, then click the Edit button.Callback URL: This is the URL Meta will be sending the events to. See the Webhooks, Getting Started guide for information on creating the URL.Verify Token: This string is set up by you, when you create your webhook endpoint. After adding the information, click Verify and Save. After saving, back in the Configuration panel, click the Manage button and subscribe to individual webhook fields. To receive notifications of customer messages, be sure to subscribe to the messages webhook field. You only need to set up Webhooks once for every application you have. You can use the same Webhook to receive multiple event types from multiple WhatsApp Business Accounts, or set up an override. For more information, see our Webhooks section. Step 3: Subscribe to your WABA To make sure you get notifications for the correct account, subscribe your app: If you get the response below, all Webhook events for the phone numbers under this account will be sent to your configured Webhooks endpoint. Step 6: Receive a message From consumer app Once participating customers send a message to your business, you get 24 hours of free messages with them -that window of time is called the customer service window. For testing purposes, we want to enable this window, so you can send as many messages as you would like. From a personal WhatsApp iOS/Android app, send a message to the phone number you just registered. Once the message is sent, you should receive an incoming message to your Webhook with a notification in the following format. Keep up with monthly updates We will release Cloud API updates on the first Tuesday of every month. Those will include new features and improvements. You don't need to do any work to use any of the new features, since the Cloud API updates automatically. FAQs General FAQs Which company will be providing the Cloud API? WhatsApp develops and operates the WhatsApp Business API, which enables businesses to communicate with WhatsApp consumer users on the WhatsApp network. When using the Cloud API, Meta will host the WhatsApp Business API for you and provide an endpoint for the WhatsApp service for your incoming and outgoing WhatsApp communications. Are there any additional costs for the Cloud API? Access to Cloud API is free, and we expect it to generate additional cost savings for developers, as Meta hosts and maintains the Cloud API. Technical implementation FAQs What is the architecture of the Cloud API? The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). What will disaster recovery look like: if a region is unavailable, how much time does it take to move messages to another region? We will have disaster recovery and data replication across multiple regions. The expected downtime would be within our SLA and usually in the order of less than a minute to less than five minutes. Data privacy & security FAQs Where are the servers for Cloud API? Cloud API processes messages on servers in Meta data centers?. If a business opts to use Cloud API Local Storage, message data is stored in data centers located in another designated country. Is the Cloud API end-to-end encrypted? What is the encryption model? See Cloud API Overview, Encryption. What happens to message data at rest? How long is it stored? Cloud API messages at rest are encrypted. Messages have a maximum retention period of 30 days in order to provide the base features and functionality of the Cloud API service; for example, retransmissions. Does Meta have access to encryption keys? In order to send and receive messages through Cloud API, Cloud API manages the encryption/decryption keys on behalf of the business. For more detail, see the WhatsApp Encryption Overview technical whitepaper?. Regulatory compliance FAQs How does Cloud API comply with regional data protection laws (such as GDPR, LGPD, and PDPB)? Meta takes data protection and people's privacy very seriously and we comply with applicable legal, industry, and regulatory requirements governing data protection, as well as industry best practices. Cloud API customers must meet their own obligations under data protection laws, such as the General Data Protection Regulation (GDPR). Please visit our Meta Business Messaging Compliance Center? to learn more. Measurement Partners | Developer Documentation Measurement Partners Updated: Dec 12, 2025 A Measurement Partner is a third-party company that helps businesses measure the effectiveness of their marketing campaigns on our platform. Measurement Partners gain read-only access to WhatsApp Business Account (WABA) analytics data and webhooks. Specifically, they can view phone numbers, message templates, and incoming messages, and can access WABA analytics data. For a business to share their analytics data with a Measurement Partner, they must already have a WABA. Measurement Partners cannot create WABAs or send messages on behalf of their clients. Onboarding flow overview Follow these steps to onboard as a Measurement Partner: Complete Tech Provider onboarding.Create your Facebook Login Button using the Measurement Partner ES template instructions belowEmbed the Facebook Login Button on your website How to create Facebook Login button using the Measurement Partner ES template Follow the steps below to create your Facebook Login button that will show the Measurement Partner ES flow to your customers. Step 1: Load the Facebook JavaScript SDK See Basic Setup for instructions on loading the basic version of the Facebook JavaScript SDK with the options set to their most common defaults. The fbAsyncInit function must be attached to the window object before the line of code loading the JavaScript SDK as the SDK calls this function to set up the Facebook Login information. This setup uses the following parameters: appId - The Meta app ID cookie - Enables cookies to allow the server to access this session xfbml- Parses social plugins on the page version - The Graph API version to use Step 2: Create Facebook Login for Business Configuration Prerequisites You should have created an app in the App Dashboard on https://developers.facebook.com/Add the Facebook Login for Business product to your appFollow best practices on how to set up Client OAuth settings, specifically settings like Valid OAuth Redirect URIs and Allowed Domains for the JavaScript SDK Process In the App Dashboard, under Facebook Login for Business, click TemplatesClick the Use template button for the WhatsApp Measurement Partner template.Since all the template configuration details have been set, simply click Create from templateCopy and retain the Configuration ID and set this value in the Facebook Login Button script in the next step. Step 4: Create a login button Create a button or link on your website to launch the Embedded Signup flow. Use the onClick function to call the launchWhatsAppSignup() function set up in Step 3 above. Embed your new Facebook Login button Copy the button code to the desired location on your site. Testing the Embedded Signup flow for Measurement Partners On the sidebar under WhatsApp, click ES Integrations and then scroll down to Embedded sign-up launch.Under Embedded sign-up dialog, choose your Measurement Partner config and click Login with Facebook.Follow the prompts to test the sign-up flow. Upgrading to a Tech Partner | Developer Documentation Upgrading to a Tech PartnerUpdated: Nov 4, 2025This document describes the requirements and steps you must to take to become a Tech Partner. Product JourneyThe product journey details the steps for Tech Providers to upgrade to become a Tech Partner on the Meta Developer Platform.Becoming a Tech Partner allows you to have even more choices and control of WhatsApp messaging solutions. It also grants access to benefits such as: Training and supportAnalytics reportsBusiness customer matching opportunities Context DefinitionsDuring this upgrade process, there are a couple of surfaces and definitions that you will come across: Meta for Developers - The entry point for developer documentation and common tools and dashboards, including the App Dashboard, the WhatsApp product panel within it, and the Quickstart panel.Quickstart panel - a panel within the App Dashboard > WhatsApp product panel. The Quickstart panel is where you can begin or resume a request for an upgrade.Enterprise Center - Enterprise Center is a new centralized platform that enables Meta to do business with external partners and vendors.Supplier Connect - Supplier Connect is an application on Enterprise Center that serves as a front to onboard external partners or third-party vendors (suppliers). It is a secure, self-service portal that allows partners to view and modify data, as well as carry out different business transactions such as: viewing purchase orderssubmitting invoicestracking paymentsMeta Business Partners - Meta Business Partners are companies Meta has vetted for their technical skills and services, and their unique ability to help businesses grow. Partners are part of a respected global community and get access to unique benefits, including: TrainingSupportAnalytics reportsBusiness customer matching opportunitiesPartner Portal - The Partner Portal provides scalable solutions for collaboration with Business Messaging partners across pipeline management and Business Messaging Accelerate program. The portal is the main surface used by WhatsApp partners to create and progress deals and view the relevant metrics and incentives for their business. Eligibility RequirementsTo be eligible for an upgrade, you must: have successfully completed all Tech Provider Get Started stepsgreater than or equal to 2,500 average daily messages (sent or received) on the WhatsApp Business Platform between your business and its users over the last 7 days or greater than or equal to 200 average daily calls (business-initiated or user-initiated) on the WhatsApp Business Platform between your business and its users over the last 7 days10 or more active business customers (have used your app to send at least 1 message in the last 30 days)maintain a business phone number quality rating⁠ of 90% or better Getting SupportSee Support. Step 1: Access the Upgrade FlowIn the App Dashboard, navigate to WhatsApp > Quickstart, and in the Become a Partner section, click the Take the next step button. Step 2: Initiate the Upgrade ProcessOn the Onboarding page, scroll to the bottom and click Become a Partner. This will reveal the 4 steps that are required to complete the upgrade to become a Tech Partner. Keep in mind the following: Please carefully fill out all business details because the information will be submitted and reviewed for approval.During a few of these steps, you will receive emails as shown in the steps below. If you do not see them, check your spam folder.This process will likely take a few weeks to complete to get through all of the approvals. Step 3: Add the WhatsApp Specialty For Your BusinessReturn to the Onboarding page inside of Meta for Developers and navigate to the Meta Business Partners application step, then click the Apply now button to submit an application to become a Meta Business Partner and apply for the WhatsApp Specialty. Step 4: Sign up for the Partner PortalNavigate back to the Onboarding page in Meta for Developers and scroll down to the Sign up for the Partner Portal step. Click Sign up and on the Partner Portal login screen select the link to Sign up. Add your name and business ID and accept the agreement to create the account. The Partner Portal is a resource to use as a partner to collaborate on deals with the Business Messaging team as well as access resources such as marketing and sales material. Once you have created an account, you will receive an email with a link to get started and add your account password. Step 5: Enroll in the Accelerate ProgramThe final step is to enroll in the Business Messaging Accelerate Program and accept the agreement. On the Onboarding page in Meta for Developers, scroll down to the last step to Enroll in the Accelerate Program and click the button to Complete enrollment.Inside of the Partner Portal, look for the Business Messaging Accelerate card and click to view and sign. You will be able to download the agreements if needed. When you return to the Onboarding page in Meta for Developers, if all steps are complete, you are officially a Tech Partner! App Review | Developer Documentation App Review Updated: Nov 6, 2025 App Review is part of app development that enables us to verify that your app uses our Products and APIs in an approved manner. Meta needs to validate how you intend to use the requested permissions to make sure it is compliant with our requirements and policies. Businesses first need to develop a prototype of their product so they can demonstrate their use case with a video recording for the App Review submission. To pass App Review, it is important that you ask for only the permissions your app needs; requesting unnecessary permissions is a common reason for rejection during app review. The following video provides a brief overview of the App Review process: Business apps are automatically approved for Standard Access for all Permissions and Features available to the Business app type, so you can test your app while you are in this access level. Make sure your test users have a developer or admin role in the Meta app being used to implement embedded signup. This means that if you are using the API for yourself as a Direct Developer, you do not need advanced access or app review. If you are building an app that other businesses will be using, you must request advanced access for any permissions your app needs. You can request Advanced Access by submitting your app to App Review. Permissions Commonly requested permissions and what to include to get approval for Advanced Access: Permission Description What to include in your submission whatsapp_business_management The whatsapp_business_management permission allows your app to read and/or manage WhatsApp business assets you own or have been granted access to by other businesses through this permission. These business assets include WhatsApp Business Accounts, business phone numbers, message templates, QR codes and their associated messages, and webhook subscriptions. Written: Explain how you will use this permission to access the business assets of business customers who you have onboarded onto the platform. Video: Record a video of your app, or WhatsApp Manager, being used to create a message template. whatsapp_business_messaging The whatsapp_business_messaging permission allows an app to send WhatsApp messages and make calls to a specific phone number, upload and retrieve media from messages, manage and get WhatsApp business profile information, and to register those phone numbers with Meta. Written: Explain what messaging functionality your app offers to business customers who you have onboarded onto the platform, and how they perform those functions. If you are partnering with a Solution Partner and plan to use their API, ask the Solution Partner to share a video with you that you can submit as part of your submission. whatsapp_business_manage_events Only request this permission if you are using the Marketing Messages API for WhatsApp with Conversions API. The whatsapp_business_manage_events permission allows an app to log events, such as purchase, add-to-cart, leads and more, on behalf of a WhatsApp Business Account administered by an app user. The allowed usage for this permission is to log events on WhatsApp Business Accounts and send this activity data to Meta for ads targeting, optimization and reporting. This permission is automatically approved if you already have advanced access for whatsapp_business_messaging permission. The average turnaround time for app reviews is about 24 hours. We recommend starting the app review process as soon as possible. You don’t need to wait for Embedded Signup to be fully implemented to start this process. Reducing chances of app review rejection You must request Advanced access for the permissions above. You can request these permissions in a single bulk submission, or as separate submissions. For each permission, an explanation and screen recording specific to the permission being requested is required. As part of your submission, you must include separate screen recordings that show how your app uses each permission in your submission. The video can be a screen recording directly from your computer, or a recording using a digital camera or camera phone. You will need to attach this file to your App Review submission. Do not submit a video that includes multiple permissions supporting different use cases. You must submit a different video clip for each permission. Your submission may be rejected if you highlight multiple permissions being used as part of the same video. Both written descriptions and screen recordings are required for each permission. If you include a screen recording that shows how your app uses a permission, but fail to include a description of how it uses it, your submission will be rejected. Submissions in draft mode will not be reviewed, so don’t forget to submit your App Review submission! Partner-initiated WABA creation | Developer Documentation Partner-initiated WABA creationUpdated: Nov 14, 2025If you are a Solution Partner and you don’t want to onboard a business customer with Embedded Signup, you can use Meta Business Suite to initiate WABA creation for a business customer. This generates a WABA creation request which your business customer can review in Meta Business Suite. The customer can then accept the request (or decline it) and optionally add a business phone number.If accepted, the WABA will be created and its ownership will be assigned to the customer. You will also be given access to the WABA based on the permissions you defined when you initiated the request. You can then use your system token to add a business phone number to the customer’s WABA (if they opted not to create one) and share your credit line with the customer, which completes the onboarding process.Note that if you use this method to create a WABA for a business customer, and the customer accepts it, you must use your system token when accessing the WABA (a business token will not work), and you must use the API to share your credit line with the customer (it cannot be shared as part of the initiation or acceptance process). Initiating WABA creation Access Meta Business Suite⁠.If you have multiple business portfolios, select the appropriate portfolio using the dropdown menu at the top-left of the page.Navigate to the Settings (gear icon) > Accounts > WhatsApp accounts panel.Click the blue Add dropdown button and select Request a new WhatsApp Business account for a client.Complete the flow, filling out each field as appropriate.Navigate to the Settings > Requests > Other requests panel and click the Sent tab and verify that your invitation has been sent to the business customer.Instruct the customer to accept the request. See Business customer instructions below for content you can send them. Onboarding business customers Listen for an account_update webhook with the event property set to PARTNER_ADDED or PARTNER_APP_INSTALLED, or look for a developer notification or developer alert, indicating that the customer has accepted your request.If the customer accepted your request, navigate to the Settings (gear icon) > Accounts > WhatsApp accounts panel and confirm that you see the customer’s WABA in the list of WABAs.If the WABA doesn’t have a business phone number, click the three-dot menu to the far right of the WABA’s name, select Add phone number, and complete the flow. Alternatively, you can add a phone number programmatically using the API.Share your credit line with the customer.This completes the onboarding process. You can now use your system token to provide WhatsApp messaging services to the customer. Business customer instructionsOnce you have confirmed that the invitation has been sent, instruct the business customer to review and accept the request in the Meta Business Suite. Invitations that have not been accepted within 90 days will be canceled automatically.You can send them the following instructions: Access Meta Business Suite at https://business.facebook.com⁠.If you have multiple business portfolios, select the appropriate portfolio using the dropdown menu at the top-left of the page.Navigate to the Settings (gear icon) > Requests > Other Requests panel and click the Received tab.Locate the invitation and review its contents (or decline the invitation).Add and verify a business phone number (optional).Confirm the invitation.Navigate to the Accounts > WhatsApp account panel and confirm that your WhatsApp Business Account has been created and shared with your Solution Partner. Adding phone numbersOnce the business customer has shared their WABA with you, you can register a business phone number for the customer in one of two ways: Via WhatsApp Manager: Navigate to the WhatsApp Manager⁠ > Overview panel and locate the WABA in the WhatsApp account section. Click the three-dot menu to the far right of the WABA’s name, click Add phone number, and complete the flow.Via API: See Registering business phone numbers.Alternatively, you can instruct the customer to add a number on their own using the WhatsApp Manager. Canceling invitationsTo cancel an invitation that has not been accepted yet, navigate to the Settings (gear icon) > Requests panel and click the Sent tab. Locate the invitation and click its Cancel button. Payment methodsBusiness customers cannot add their own payment method to a WABA created via the partner-initiated WABA creation process. You must use the API to share your credit line with any business customer who accepts your creation request. Multi-Partner SolutionsIf you are part of a Multi-Partner Solution (“MPS”), you can share a WABA created through the partner-initiated WABA creation process with other MPS participants after you have successfully onboarded the WABA.To share the WABA with other MPS participants, you have two options: Recommended: direct the customer to your (or your partner’s) MPS-configured implementation of Embedded Signup, and instruct them to complete the flow using their existing WABA name, business portfolio, and business phone number.Use the API to add the WABA to your MPS. WABA Sharing modelWith the WABA Sharing model, a business customer creates and grants access to their WABA to a solution provider using Embedded Signup.When a customer successfully completes a solution provider’s Embedded Signup flow, a WABA is created under the customer’s business portfolio (and is thus owned by the customer) and a webhook is triggered, notifying the partner. The partner can then use the contents of the webhook and the customer’s business token to onboard the customer and provide message services via the API. Onboarding customers to the WABA Sharing modelTo onboard a business customer to the WABA Sharing model, you must use Embedded Signup. See the Embedded Signup documentation to learn how to implement Embedded Signup, and how to onboard business customers as a Solution Provider. On-Behalf-Of modelThe On-Behalf-Of WABA ownership model has been deprecated and is no longer possible. See On-Behalf-Of account ownership model deprecation for details. Multi-Partner Solutions | Developer Documentation Multi-Partner Solutions Updated: Feb 27, 2026 This document explains how to set up Multi-Partner Solutions (“solutions”) and how to use them with Embedded Signup. Multi-Partner Solutions allow Solution Partners and Tech Providers to jointly manage customer WhatsApp assets in order to provide WhatsApp messaging services to their customers. For example, if you are a Tech Provider and are unable to offer custom or full WhatsApp messaging services to your customers, you can work with a Solution Partner to offer your customers the Solution Partner’s services. Once created and accepted via API or App Dashboard, the solution’s ID can be used to customize the Embedded Signup flow. Any customers onboarded via the customized flow can grant asset access to all of the solution’s partners. Note that solutions can also be set up via an embedded button that triggers an interface that gathers app information from Tech Providers. This flow and the API calls involved are described in the Multi-Partner Solution — Embedded Creation document, but the information below is still relevant and should be read first. Requirements You must be an approved Solution Partner, a Tech Provider who has completed the steps in our Get Started for Tech Providers document appropriate for your intended usage, or a Tech Provider who has been upgraded to a Tech Partner. If your app will be calling our APIs to access onboarded customer data:The app must be the same app whose token will be used in API requests.The app must have undergone App Review and been approved for the whatsapp_business_management and whatsapp_business_messaging permissions.The app must be subscribed to the account_updates webhooks field and be able to successfully digest webhooks for onboarded customers. Creating Multi-Partner Solutions Use the App Dashboard > WhatsApp > Partner Solutions panel to create, accept, and manage solutions. Solutions can be created by either partner of the solution. Once created, a solution request is sent to the invited partner, who can then use the panel in their App Dashboard to accept or decline the request. Once accepted, either partner can use the solution ID to customize the Embedded Signup flow and onboard business customers. Solution States Solutions states are displayed in the Partner solutions panel. Solutions can have the following states: State Description Active The solution has been accepted by the invited party and can be used to configure Embedded Signup for customer onboarding. Deactivated The solution has been deactivated. Customers who attempt to access Embedded Signup configured for a solution in this state will see an error informing them that it cannot be used for onboarding at this time. Draft The solution has been initiated and saved, but you have not sent it to your partner. Customers who attempt to access Embedded Signup configured for a solution in this state will see an error informing them that it cannot be used for onboarding at this time. Inactive The solution request was declined by your partner. Customers who attempt to access Embedded Signup configured for a solution in this state will see an error informing them that it cannot be used for onboarding at this time. Pending Solution has not been accepted or declined by your partner. Customers who attempt to access Embedded Signup configured for a solution in this state will see an error informing them that it cannot be used for onboarding at this time. Pending deactivation Your partner has requested to deactivate the solution. You can accept or decline this request. Onboarding Limits Tech Providers who are part of a solution can onboard up to 200 total new customers in a rolling one week period. Only customers who are new to the WhatsApp Business Platform count against this limit. Embedded Signup Embedded Signup can be configured and hosted by either of the solution’s partners, or both partners. Once implemented, customers who access it will see a customized version of the Embedded Signup flow, which makes it clear that by completing the flow they are granting WhatsApp data access to both partners: When a customer completes the flow, all of the customer’s WhatsApp assets that we need are automatically generated, and access to those assets is granted to both partners of the solution. Billing Customers onboarded via Embedded Signup configured with a solution ID share the credit line of the Solution Partner associated with the solution. Step 1: Determine Solution Details Contact your potential partner and work together to determine:A solution name. The solution name will appear in the Partner Solutions panel in the App Dashboard for both you and your partner, so you should both agree on a name that can be distinguished from other solutions you may initiate or accept.Who will create and initiate the solution request. Either partner can do this. If you are initiating the request, you will need your partner’s app ID.Who will host Embedded Signup configured with the solution ID. Either or both partners can do this.Anything else, such as contracts, service level agreements, services provided, billing processes, etc. This is left to the discretion of you and your partner, subject to each of your separate agreements with Meta. Step 2: Subscribe to Webhooks Subscribe to the account_update and partner_solutions webhooks fields. These webhooks will inform you when new business customers are onboarded, and when partner solutions that you are associated with are created or edited. See the Webhooks section below for example payloads and what to look for when you receive any of these webhooks. Step 3: Create a Solution If you are creating the solution, navigate to the App Dashboard > WhatsApp > Partner solutions panel and click the Create a partner solution button. Use your partner’s app ID to complete the flow. As part of the creation flow you can designate which solution partner apps can be used by onboarded business customers to send messages (Only me, Only my partner). Upon creation, an email and Meta Business Suite notification will be sent to your partner, and a partner_solutions webhook will be triggered. The partner solution will appear in the Partner solutions panel with a Pending status until accepted by your partner. If accepted, its status will change to Active. If declined, its status will change to Inactive. Step 5: Configure Embedded Signup Assign the solution ID to the solutionID property in the extras.setup object within the launch method and callback registration portion of the Embedded Signup code. // Launch method and callback registration const launchWhatsAppSignup = () => { FB.login(fbLoginCallback, { config_id: '', // your configuration ID goes here, ensure it is in quotes response_type: 'code', override_default_response_type: true, extras: { setup: { solutionID: '' // add solution ID here, ensure it is in quotes }, featureType: '', sessionInfoVersion: '3', } }); } Both you and your partner’s business portfolio (Business Settings > Business Info) will appear throughout the Embedded Signup flow. Once configured, surface the customized Embedded SIgnup flow to customers on your platform wherever you feel it is appropriate. Note that if you have multiple active partner solutions, it is your responsibility to inject the correct solution ID into your Embedded Signup configuration and surface it to your intended customers, otherwise a customer could be onboarded using the wrong solution. Step 6: Listen for Onboarded Business Customers To listen for onboarded customers, your app must be subscribed to the account_update webhook field. In addition, we will send an email to admins of the business portfolio that owns the app, and a Meta Business Suite notification to the business portfolio that owns the app. Step 7: Share Your Credit Line (Solution Partners only) If you are a Solution Partner, share your line of credit with any business customers newly onboarded via the partner solution. Note: If you are a Solution Partner trying to add a user to a WhatsApp Business Account that is shared with you, you would need to account for the following scenarios:If you are not granted the MESSAGING permission on the solution, then you need to decide which granular tasks you need when adding the user to the shared WhatsApp Business Account: DEVELOP, MANAGE_TEMPLATES, MANAGE_PHONE, VIEW_COST, MANAGE_EXTENSIONS, VIEW_PHONE_ASSETS, MANAGE_PHONE_ASSETS, VIEW_TEMPLATES, VIEW_INSIGHTS, MANAGE_USERS, and MANAGE_BILLING.In this scenario, also note that MANAGE_BILLING is needed for credit line sharing. MANAGE will only work if you are given Full access on the solution, i.e. including MESSAGING. Editing or Deactivating Solutions You can use the App Dashboard or API to edit or deactivate a solution. When you request deactivation, the solution’s status will change to Pending deactivation and your partner will be notified by email and Meta Business Suite notification. In addition, a partner_solutions webhook will be triggered with event set to SOLUTION_UPDATED and solution_status set to PENDING_DEACTIVATION. Your partner can then accept or reject your request. Note that partner solutions can still be used to onboard customers until your partner accepts the deactivation request. If the deactivation request is rejected, the solution will remain in an Active state and can continue to be used to onboard customers. If the deactivation request is accepted, the solution status will be set to Deactivated and can no longer be used to onboard business customers, so make sure that neither you nor your partner are surfacing it to business customers. LimitationsYou can only edit solutions that were created by you.You can request deactivation of any solutions that you create which are in an Active state. Via App Dashboard Use the App Dashboard > WhatsApp > Partner solutions panel to edit or deactivate a solution. Note that you can only edit solutions that were initiated by you. State Permitted actions Active You may edit the solution name, or deactivate the solution. Deactivated Solutions in this state cannot be edited. Draft You may edit the solution name. Inactive You may edit the solution name. Pending Solutions in this state cannot be edited until accepted or declined by your partner. Pending deactivation You may accept or decline the partner’s deactivation request. Via API Migrating business customer assets among solutions You have several options for migrating business customer assets to and from Multi-Partner Solutions. See Migrating business customer assets. Multi-Partner Solution — Embedded creation | Developer Documentation Multi-Partner Solution - Embedded creation Updated: Dec 12, 2025 Multi-Partner Solutions (MPS) allow Solution Partners and Tech Providers to jointly manage customer WhatsApp assets in order to provide WhatsApp messaging services to customers. If you are a Solution Partner, instead of using the app dashboard to create an MPS, you can create one using a snippet of JavaScript and an HTML button which you can embed somewhere on your website. Tech Providers who want to partner with you can use the button to grant your app permission to manage solutions for one or more of their apps, which you can then do using a series of API requests. Flow Tech Providers who visit your website and click the embedded solution creation button will be asked to authenticate, and after doing so, will be presented with an interface that allows them to choose an existing app: After choosing an app, they can review and confirm that they will be granting your app permission to manage their app's Multi-Partner Solutions. Once the Tech Provider dismisses the interface, a user access token will be generated and returned to flow, where you can capture it. You can then use the token in a series of API calls to get Tech Provider's chosen app ID(s) and create and accept a solution. Requirements Facebook Login for Business must be configured on your app, with Valid OAuth Redirect URIs and Allowed Domains for the JavasScript SDK set. You should already have set these values when configuring Embedded Signup.Your app must undergo App Review and be approved for advanced access for the manage_app_solution permission. Embedded creation button Step 1: Grant permission to app Access the Meta Business Suite and use your system user to grant your app the manage_app_solution permission. Log into business.facebook.com?.Use the business portfolio dropdown menu on the left to locate your business portfolio and click the gear icon (for settings).Navigate to Users > System Users.Click the system user who has business asset access on your app and WhatsApp Business Account.Click the Generate token button.Select your app.Set an expiration date for the token.Select the manage_app_solution permission.Generate a token. Use this token when accepting any Multi-Partner Solutions you create for your partners (see below). Step 2: Add embedded button code Add the following code to your website or portal, or wherever you plan on directing Tech Providers who will be working with you as part of an MPS. Be sure to replace with your app ID. Direct prospective Tech Provider partners to this location and instruct them to complete the flow. Let them know that completing the flow does not create the solution (it requires some API calls on your part) and that you'll provide them with the solution ID once it has been created. How to use Multi-Solution Conversations (MSC) | Developer Documentation How to use Multi-Solution Conversations (MSC)Updated: Feb 24, 2026 OverviewMulti-Solution Conversations allows businesses to use multiple partners and solutions on the same phone number, creating a seamless chat thread experience for their customers. Requirements This feature is currently in a closed beta. Please reach out to your partner manager for more details.Your business portfolio must have an increased messaging limit.Businesses with banned or restricted WhatsApp Business accounts (WABA) are not eligible. Use the Business Support Home⁠ to address restrictions. Features Simple end-business onboarding via Embedded Sign-up: Partners can onboard businesses easily through Embedded Signup.Payment and template isolation per partner: Each partner has their own WhatsApp Business Account, their own templates, and their own billing and metrics. LimitationsSince this feature is still in beta, some functionality may not work as expected. See Beta Product Testing Terms⁠. How Multi-Solution Conversations work The chart above illustrates a new WABA shared with each integrated partner, and assets separated per WABA. The business shares all phone numbers associated with their WhatsApp Business Account (WABA) to a partner through the Embedded Signup flow.The system creates and shares a new WABA with the partner the business onboards with.The partner now has messaging or calling access to the business phone numbers shared with them and can message or manage calls on behalf of the business. Supported APIs and usageBusinesses can use a single phone number across one or multiple partners across the following APIs and uses: Messaging via WhatsApp Cloud APICalling via WhatsApp Cloud APIClick-to-WhatsApp Ads via Ads Manager⁠ Additional limitationsMSC does not currently support: Conversation routing and management: currently, all parties the phone number is shared with receive incoming webhooks. Businesses must work with partners to manage response handling.Coexistence phone numbersPhone numbers using the Groups APIWABA created through Embedded Signup which are used on Ads Manager for Marketing MessagesMeasurement Partner onboarding General limitations Only 5 partners or solutions can be enabled per each end-business WhatsApp Business Account (WABA).Only 1 partner can attach a catalog to the shared phone number(s) between partners. Phone number sharing limitationsThe business cannot share a phone number with the same partner more than once via different WABAs.For example, the business has a phone number linked to WABA 1 and then shares WABA 1 with Partner 1. If you have the same phone number linked to WABA 2, you cannot also share WABA 2 with Partner 1. If you try to share the phone number, you may receive an error. How messaging, calling, and account management works when using MSCUse the following table to understand how different features and APIs work when using MSC as a partner or business. OnboardingValue: Use an existing phone number across multiple partners and solutions. Business Experience Partner Experience The business onboards an existing phone with more than one partner via Embedded Signup. Partners can see the new WABA shared with them within Meta Business Suite settings. Account managementValue: Account management as usual Business Experience Partner Experience You can perform account management operations via the usual pathways (WhatsApp Manager, API, and so on) based on permissions granted. API usageValue: Enable messaging and calling functions across multiple partners on a single phone number Feature Business Experience Partner Experience Cloud API MessagingMarketing Messages API for WhatsApp Not applicable Send messages: All partners can send messages via API on the shared phone number(s).Receive messages: All partners will receive all incoming webhooks on the shared phone number(s). Cloud API Calling Not applicable Partners onboarded to the Calling API can make business-initiated calls, and receive user-initiated calls.Learn more about the WhatsApp Business Calling API Templates Not applicable Partners can create templates as usual by using the new WABA, either through the API or WhatsApp Manager.Learn how to create and manage message templates Conversation Routing and Management Currently, all parties the phone number is shared with receive incoming webhooks.Businesses must work with partners to manage response handling. Currently, all parties the phone number is shared with receive incoming webhooks.Businesses must work with partners to manage response handling. BillingValue: Simplified, siloed billing ownership per WABA Business Experience Partner Experience Businesses can add a payment method to any of the WABAs created and shared with partners. Partners add their own payment methods to the WABA shared with them, the same as they do today.Each partner is billed only for the messages sent through their app.Per-message pricing applies. Asset managementValue: Simplified, siloed asset management per WABA Feature Business Experience Partner Experience Templates The business can create and see templates on all WABAs shared with partners. Partners can only create templates on the WABAs that are shared with them.Partners are not able to see other Partners’ templates Phone numbers Phone numbers are a shared resource.Whether the end business or partner adds the phone number, it will be visible to all in WhatsApp Manager. Any new phone numbers added to WABAs using MSC are shared with all partners with access to these MSC WABAs. OffboardingValue: The business has full control of what partners, assets, and accounts they retain. Role/Asset Business Experience Partner Experience Partner Experience WABA The business can delete the WABA. Partners cannot delete the WABA shared with them. Phone number Both the business and partner can delete a phone number. Partner The business can remove the partner. Not applicable. How violations and bans work with MSC Phone number violations Phone number violations will ban all WABAs across all partners, associated with the phone number.Template violations Template violations will only apply to the violating WABA.Business portfolio violations Any bans on the business portfolio will ban all WABAs associated with the phone number.Decision appeals continue to function as they do today. Onboarding for MSC (Embedded Signup flow)Only available to businesses with a messaging limit of at least 1,000 business-initiated conversations in a rolling 24 hour period.Once a business meets the eligibility requirements, the MSC flow for Embedded Signup is automatically displayed in the Embedded Signup flow (v2 and above). Partners don’t need to configure anything in Embedded Signup for this to work.When businesses sign up to a partner through Embedded Signup, they see the flow below and can choose to share their existing business phone numbers. This onboards them to MSC. Embedded Signup has two experiences, and a given business may see either one randomly. Both experiences are described below.Once the business completes the Embedded Signup flow, the partner does not need to re-register with the business. Embedded Signup flow for businesses (experience 1)The Notes column calls out any MSC-specific notes for each screen. Screen Notes Authentication screen No changes Authorization screen No changes Business Asset Selection Screen Here, you can select a WhatsApp Business account that is already shared with other partner(s) Phone number addition screen Select ‘Use a new or existing WhatsApp number’, then click on the dropdown ‘Add a new WhatsApp number’, then select existing WhatsApp Business Account you want to share with current partner Permissions review screen No changes Success screen No changes Embedded Signup flow for businesses (experience 2)Businesses onboard to MSC by using the Embedded Signup flow. Note that these screenshots may differ as the product evolves.Step 1: Select the business portfolio. Step 2: Select Share existing WhatsApp phone numbers. Step 3: The business selects the WABA with the phone number(s) they would like to share. Note that these numbers are only selectable if they have not been shared already with this partner. Step 4: Create a name for the new WhatsApp Business Account being created. Step 5: Verify permission information. Step 6: Verify signup information and finish. TroubleshootingThe “Share existing WhatsApp phone numbers” option is greyed outThis can happen for several reasons: The business already has a solution with the partner they are trying to share the number with.The business has exceeded the 5 partner maximum for the number.The phone number is not eligible to send 1k messages yet.The phone number has not been registered.What can I do if the business phone number goes offline?Rarely, a phone number can go offline. To solve this issue, try the following: Register the phone number again: The business should search each of their WABA activity logs to find which partner registered the phone number first. Then, that partner can register the phone number again.Turn off 2-factor authentication (optional): If the business cannot obtain which partner originally registered the phone number, they can shut off two-factor authentication and have another partner register the number again. Learn how to disable 2FA on a phone number. Frequently asked questionsHow do I get support?For support concerning Multi-Solutions Conversations, choose the WABiz: Onboarding topic when opening a Direct Support⁠ ticket.How can I offboard from MSC?To offboard from MSC: Migrate templates (Optional): If there are newly created templates on an MSC-created WABA, please migrate them before offboarding. [Learn how to migrate templates here.]Submit a WhatsApp support ticket: Use the request type “Embedded Signup - MSC Offboarding” and include the WABA you would like to retain.Is MSC supported for Tech Providers, Tech Partners, and Multi-Partner Solutions?Yes.Will a partner be able to see how many partners a client is using and the specific services/capabilities each partner provides?No.Does every partner need to register a given business phone number to onboard it to MSC?No, only one partner needs to register it. Once the number has been registered, it is ready to be used with new partners without the need to re-register it.What happens if a business tries to onboard without having previously registered their phone number(s)?An error will be displayed in Embedded Signup, prompting the business to register their number(s).If multiple partners respond to messages within the same conversation window, who will be charged?Per-message pricing applies.What happens if two partners send messages at the same time? Will I get billed twice?Per-message pricing applies.When will MSC become generally available?Mid-2026. Partner-led Business Verification | Developer Documentation Partner-led Business Verification Updated: Nov 14, 2025 This feature is currently only available to approved Select Solution and Premier Solution Partners. See our Sign up for partner-led business verification? Help Center article to learn how to request approval. This document describes how to create business verification submissions for business customers who have been onboarded via Embedded Signup. If you are an approved Solution Partner, you can gather required business verification documentation from your onboarded business customers and submit their business for verification on their behalf. Decisions on submissions created in this way can be made in minutes instead days. Requirementsyou must already be an approved Select Solution or Premier Solution Partner, and approved for access?your system user access tokenthe system user whose system token you are using must be an admin on your business portfolio (see our About business portfolio access? Help Center article)the system user whose system token you are using must have granted your app the business_management permissionthe business customer's business portfolio ID (provided by the customer? or returned via API by requesting the owner_business_info field on the customer's WABA ID, using their business token) Limitations You are limited to three submissions for a given business customer. If all three submissions are rejected, the customer must complete business verification on their own. If your submission is rejected three times, share the following Help Center article with the customer: How to Verify Your Business on Meta? Support If you need help with partner-led business verification, open a Direct Support ticket:Go to Direct Support?.Click Ask a Question.Under Topic select WABiz: Onboarding.Click Request type and select Partner-led Business Verification for WhatsApp. Supported Documents See the following Help Center article for a list of business documents that we will accept: Upload official documents to verify your business? Turnaround Time The average turnaround time for a submission is 5 minutes, but can take several hours. If you do not receive a webhook notifying of the outcome of a submission after 24 hours, please open a Direct Support ticket. Webhooks Submission decisions are communicated via account_update webhook, so make sure your app is subscribed to the account_update webhook field, and your app is subscribed to webhooks on the business customer's WhatsApp Business Account. Webhook parameters Placeholder Description Example value Business customer's business portfolio ID. 2729063490586005 Description of rejection reasons. Note that this parameter will be present even if the submission was rejected, but its value will be set to NONE. See the rejection_reasons field on the WhatsApp Business Partner Client Verification Submission node reference for a list of possible values and their descriptions. LEGAL_NAME_NOT_FOUND_IN_DOCUMENTS Business verification status. Values can be: APPROVED - Indicates the customer's business has been verified. FAILED - Indicates we were unable to verify the customer's business based on the submitted business information. APPROVED Business customer's WABA ID. 486585971195941 Unix timestamp indicating when the webhook was sent. 1730752761 Getting submission status Request parameters Placeholder Description Example value Optional. The customer's business portfolio ID. Include this parameter if you only want to get data on submissions you have created for the business identified by the customer's business portfolio ID. 2729063490586005 Required. Your system user access token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD Response Upon success, the endpoint returns an array of WhatsApp Business Partner Client Verification Submission nodes, with default fields on each node. Response parameters See the WhatsApp Business Partner Client Verification Submission node reference for descriptions of returned fields and parameter values. Get business verification status Request parameters Placeholder Description Example value Required. The customer's business portfolio ID. 2729063490586005 Required. The customer's business token. EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn Response parameters Placeholder Description Example value The business customer's business portfolio ID. 2729063490586005 The business portfolio's verification status. See the verification_status field on the Business node reference for a list of possible values. verified Tracking with the Meta Pixel | Developer Documentation Tracking with the Meta Pixel Updated: Nov 4, 2025 The Meta Pixel is a snippet of JavaScript code that allows you to track visitor activity on your website. It works by loading a small library of functions that you can use whenever a site visitor takes an action (i.e., an event) that you want to track; this is called a conversion. Embedding the Meta Pixel is a feature that lets you know how many visitors to a given page have clicked on the embedded signup button. This can help you understand how many people considered WhatsApp and how many successfully converted. Make sure the initial code setup triggers a Pageview event with your Facebook app ID and the feature parameter. Managing WhatsApp Business Accounts | Developer Documentation Managing WhatsApp Business Accounts Updated: Feb 27, 2026 This document describes common endpoints used to manage business customer WhatsApp Business Accounts. Understanding shared WABAs Permissions A Solution Partner has the following permissions in a shared WABA: Add phone numbersCreate templatesSend messages to customersAssign users to the accountAccess metricsView payment information On their side, the businesses onboarding via Embedded Signup can see and/or do: Category What can businesses see? Insights Messaging, cost, and quality state changes. Quality Quality statuses and ratings. Category What can businesses do? Assets Add and manage phone numbers and templates. WABA management Unshare WABA with a Solution Partner, delete WABA, and change settings. Integration with other Meta products Integrate with Ads that Click to WhatsApp. Solution Partners cannot disable what businesses are able to see or do or customize their views. Businesses can see Manage Your WhatsApp Solution Partner's Permissions? for more information. Notifications Solution Partners receive relevant notifications via webhooks and through Business Manager. Notifications are sent when: A business shares a WABA.Messaging limits or quality rating changes for a client's WABA.When a phone number display name or a template is approved. If the business leaves the Embedded Signup flow before they have successfully completed it, they may have shared the WABA but the phone number's certificate may not ready, which means the number cannot be registered for API use. If this happens, please reach out to the business to help them complete the embedded signup flow. See Also WhatsApp Business Management APIReference: BusinessReference: WhatsApp Business Account Registering business phone numbers | Developer Documentation Registering business phone numbers Updated: Nov 14, 2025 This document describes the steps to programmatically register business phone numbers on WhatsApp Business Accounts (WABA). Note that Embedded Signup performs steps 1-3 automatically (unless you are bypassing the phone number addition screen) so you only need to perform step 4 when a business customer completes the flow. If you have disabled phone number selection, however, you must perform all 4 steps. Registering business phone numbers is a four step process:Create the number on a WABA.Get a verification code for that number.Use the code to verify the number.Register the verified number for API use. These steps are described below. You can also perform all 4 steps repeatedly to register business phone numbers in bulk. Limitations Business phone numbers must meet our phone number requirements. Step 2: Request a verification code Send a POST request to the WhatsApp Business Phone Number > Request Code endpoint to have a verification code sent to the business phone number. Query string parameters Placeholder Description Example Value Required. Indicates how you want the verification code delivered to the business phone number. Values can be SMS or VOICE. SMS Required. Indicates language used in delivered verification code. en_US Response properties Placeholder Description Example Value Boolean indicating success or failure. Upon success, the API will respond with true and a verification code will be sent to the business phone number using the method specified in your request. true Example SMS delivery Example of an SMS message in English containing a verification code, delivered to a business phone number: WhatsApp code 123-830 Step 3: Verify the number Send a POST request to the WhatsApp Business Phone Number > Verify Code endpoint to verify the business phone number, using the verification code contained in the SMS or voice message delivered to the number. Query string parameters Placeholder Description Example Value String Required. Verification code, without the hyphen. 123830 Response properties Placeholder Description Example Value Boolean indicating success or failure. Upon success, the API will respond with true, indicating that the business phone number has been verified. true Manage System Users | Developer Documentation Manage System Users Updated: Nov 14, 2025 Adding your System User to shared WhatsApp Business Accounts allows you to programmatically manage the accounts. On this guide, we go over actions BSPs may need to perform to manage their system users.For help creating a system user, see System Users, Create, Retrieve and Update a System User.For help generating your system user access token, see System Users, Install Apps and Generate Tokens. Add System Users to a WhatsApp Business Account For this API call, you need to use the access token of a System User with admin permissions. Permissions Name Description MANAGE Provides admin access. Users can have admin access on a WhatsApp Business Account that is shared with Admin permissions. Note: If you are a Solution Partner trying to add a user to a WhatsApp Business Account that is shared with you via a Multi-Partner Solution, then you would need to account for the following scenarios:If you are not granted MESSAGING permission on the solution, then you need to decide which granular tasks you need when adding the user to the shared WhatsApp Business Account: DEVELOP, MANAGE_TEMPLATES, MANAGE_PHONE, VIEW_COST, MANAGE_EXTENSIONS, VIEW_PHONE_ASSETS, MANAGE_PHONE_ASSETS, VIEW_TEMPLATES, VIEW_INSIGHTS, MANAGE_USERS, MANAGE_BILLING.In such scenario, also note that MANAGE_BILLING is needed for sharing Line of Credit.MANAGE will only work if you are given full access on the solution i.e. including MESSAGING. DEVELOP Provides developer access. Users can have developer access on a WhatsApp Business Account that is shared with Standard permissions. See AlsoReference: WhatsApp Business Account On-Behalf-Of account ownership model deprecation | Developer Documentation On-Behalf-Of account ownership model deprecationUpdated: Nov 14, 2025We have deprecated the On-Behalf-Of (“OBO”) account ownership model and replaced it with partner-initiated WABA creation. All existing WABAs created under the OBO model should have been transferred to business customers by October 1, 2025. Post 1st October 2025, all the eligible OBO accounts will be auto-migrated in batches through the end of 2025. Deprecation timeline March 24, 2025: partner-initiated WABA creation is made available to all Solution Providers.September 29, 2025: last day to onboard business customers to the OBO model.October 1, 2025: last day to transfer ownership of OBO model WABAs to business customers. Payment methodsPartner-initiated WABA creation does not support automatic payment setup. Instead, you must share your credit line with the business customer via the API. See Partner-initiated WABA creation for details. Multi-Partner SolutionsBusiness customers cannot be onboarded to a Multi-Partner Solution as part of the partner-initiated WABA creation process, but can be added to an MPS afterwards. See Partner-initiated WABA creation for details. Marketing Messages API for WhatsAppExisting OBO model WABAs need to be transferred to business customers if you want to use them with the Marketing Messages API for WhatsApp, but this can be done as part of the Marketing Messages API for WhatsApp onboarding process. Migrate an existing WhatsApp Number to a Business Account | Developer Documentation Migrate an existing WhatsApp Number to a Business AccountUpdated: Oct 31, 2025To use an existing WhatsApp Messenger phone number with Cloud API, you must first delete your WhatsApp Messenger account.To use an existing WhatsApp Business app phone number with Cloud API, you must either delete your account, or onboard to the platform using a solution provider⁠ who supports business app number onboarding. Remember to back up your chat history from the WhatsApp Business App. These are guides on how to do so for Android⁠ or iOS⁠.Note that if you delete your WhatsApp Business app phone number and then register it for use with Cloud API using the steps below, your existing messaging history will be lost, and you will be unable to use that number with the WhatsApp Business app again, unless you deregister the number from Cloud API. If you onboard via a solution provider who supports business app number onboarding, you will be able to use both the WhatsApp Business app and the solution partner’s app concurrently, and your messaging history will be preserved. Deleting a WhatsApp Messenger or WhatsApp Business app account Open WhatsApp Messenger or WhatsApp Business app on your Android or iPhoneNavigate to Settings > AccountSelect Delete my account. Messages sent to this phone number will be queued in the meantimeFollow the steps to delete the WhatsApp account for that phone number. It may take up to 3 minutes for the disconnected number to become available Account Settings Delete My Account Deletion StepsOnce the number is available, follow the instructions to Add a Phone Number. Business customer phone numbers | Developer Documentation Business customer phone numbers Updated: Feb 27, 2026 This document describes business customer phone numbers, their requirements, and endpoints commonly used to manage business phone numbers. Basics Your business customers need a dedicated number to use WhatsApp. Phone numbers already in use with the WhatsApp app are not supported, but numbers in use with the WhatsApp Business app can be registered. Business customers can have multiple phone numbers associated with their Meta Business Account?, so they can add another number for API use if they wish. When completing the Embedded Signup flow, your business customers should use a phone number and display name that they want to have appear in the WhatsApp app. We strongly discourage signing up with a test or personal number, or test display name, as are difficult to change. For more detailed information relating to phone numbers and WhatsApp for Business Platform, see Phone Numbers.For information on how to migrate an existing registered WhatsApp phone number, see Migrate Phone Number. Instructions for business customers This section is directed towards customers of Embedded Signup and provides guidance about actions they may perform relating to phone numbers. Add Phone Numbers to a WhatsApp Business Account There are two methods to add additional numbers to a WhatsApp Business Account (WABA): [Recommended] Go through the embedded signup flow again, select the existing Business Manager & WABA, add the number, and verify it.In the Business Manager, go to the Phone Numbers tab of WhatsApp Manager, and select Add Phone Number. When using this option, the Solution Partner has to manually verify the phone number as phone verification is not available in the Business Manager. For this reason, it is recommended that businesses follow the embedded signup flow to add additional numbers. Learn More Phone numbers: WhatsApp for Business Platform OverviewPhone numbers: Migrate an existing registered numberReference: WhatsApp Business Account Managing credit lines | Developer Documentation Managing credit lines Updated: Dec 12, 2025 This document describes how Solution Partners can share and revoke lines of credit with onboarded business customers. Billing Liability Disclosure Business customers that you onboard through Embedded Signup must be granted access to your line of credit with Meta to pay for WhatsApp Business Platform access. This means that businesses pay you, and you receive an aggregated invoice to pay Meta. You are the “Bill To Party” for all businesses sharing your credit line. You are liable for and will pay Meta for all WhatsApp Business Platform spend made by these businesses. You can grant access to your line of credit using the APIs described in this document. You can revoke access to your line of credit for individual businesses within the Meta Business Suite⁠ or with a series of API calls. Authentication and authorization Nearly all credit line related endpoints require your system user access token. In addition, the system user who the token represents must have granted your app the business_management permission, and must have been granted an Admin or Financial Editor role on your business portfolio. Sharing your credit line We are currently testing new steps for sharing your credit line with onboarded business customers. These steps will eventually replace this step, so if you wish to implement these steps now, refer to the Alternate method for sharing your credit line below. Request parameters Placeholder Description Example value Required. The business’s currency, as a three-letter currency code. Support values are: AUD EUR GBP IDR INR USD This currency is used for invoicing and corresponds to pricing rates. USD Required. The customer’s WABA ID. 102290129340398 Required. Your extended credit line ID. 1972385232742146 Required. Your system token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD Response parameters Placeholder Description Example value The extended credit line’s allocation configuration ID. Save this ID if you want to verify that your credit line has been shared with the customer. 58501441721238 The customer’s WABA ID. 102290129340398 Troubleshooting Unshared WhatsApp Business Accounts If a business customer unshares their WABA with you, or removes you as a partner from their WhatsApp Business Account, you will not be able to get their business portfolio ID via API. Instead, you can get their portfolio ID from the email notification that was sent to admins of the business portfolio, when the business customer removed you as a partner, or unshared their WABA. When WABA is unshared with you, all messaging for that WABA is blocked to protect your credit line. For complete security, we recommend that you revoke your credit line from the business customer’s WABA as soon as it has been unshared with you. See AlsoReference: BusinessReference: WhatsApp Business AccountReference: Extended Credit Managing Webhooks | Developer Documentation Managing Webhooks Updated: Dec 12, 2025 WhatsApp Business Accounts (WABAs) and their assets are objects in the Facebook Social Graph. When a trigger event occurs to one of those objects, Facebook sees it and sends a notification to the webhook URL specified in your Facebook App’s dashboard. In the context of embedded signup, you can use webhooks to get notifications of changes to your WABAs, phone numbers, message templates, and messages sent to your phone numbers. You must individually subscribe to every WABA for which you wish to receive webhooks. After fetching the client’s WABA ID, subscribe your app to the ID in order to start receiving webhooks. See Webhooks for more information about webhooks and fields. Subscribe to webhooks on a business customer WABA Response Upon success: Repeat this process for any other WABAs for which you wish you receive webhooks notifications. Note that if you subscribe your app to webhooks for multiple WABAs, all webhooks notifications will be sent to the app’s callback URL specified in the Webhooks product panel of the App Dashboard, unless you override webhooks. Get all subscriptions on a WABA To get a list of apps subscribed to webhooks for a WABA, send a GET request to the subscribed_apps endpoint on the WABA: Unsubscribe from a WABA To unsubscribe your app from webhooks for a WhatsApp Business Account, send a DELETE request to the subscribed_apps endpoint on the WABA. Overriding the callback URL See Webhooks Overrides. Set up notifications You can set up webhooks to send you notifications of changes to your subscribed WhatsApp Business Accounts. The types of notifications you can subscribe to are: Available subscription fields Field name Description account_alerts The account_alerts webhook notifies you of changes to a business phone number’s messaging limit, business profile, and Official Business Account status. account_review_update The account_review_update webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines. account_update The account_update webhook notifies of changes to a WhatsApp Business Account’s partner-led business verification submission, its authentication-international rate eligibility, or primary business location, when it is shared with a Solution Partner, policy or terms violations, offboarding, reconnection, or when it is deleted. automatic_events The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting. business_capability_update The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.). history The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider. message_template_components_update The message_template_components_update webhook notifies you of changes to a template’s components. message_template_quality_update The message_template_quality_update webhook notifies you of changes to a template’s quality score. message_template_status_update The message_template_status_update webhook notifies you of changes to the status of an existing template. messages The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user. partner_solutions The partner_solutions webhook describes changes to the status of a Multi-Partner Solution. payment_configuration_update The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil. phone_number_name_update The phone_number_name_update webhook notifies you of business phone number display name verification outcomes. phone_number_quality_update The phone_number_quality_update webhook notifies you of changes to a business phone number’s throughput level. security The security webhook notifies you of changes to a business phone number’s security settings. smb_app_state_sync The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider. smb_message_echoes The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider. template_category_update The template_category_update webhook notifies you of changes to template’s category. user_preferences The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences. Templates Utility templates | Developer Documentation Utility templates Updated: Nov 14, 2025 This document describes how to create and send utility templates. Utility templates are typically sent in response to a user action or request, such as an order confirmation or update. Utility templates have strict content requirements, particularly around marketing material. If you attempt to create or update a utility template with marketing material, the template will automatically be re-categorized as a marketing template. See our template categorization documentation for content guidelines. Supported components Utility templates support the following components: 1 header (optional; all types supported)1 body1 footer (optional)Up to 10 buttons (optional). Supported types: Call requestCopy codePhone numberQuick-replyURL Best practices for authenticating users via WhatsApp | Developer Documentation Best practices for authenticating users via WhatsApp Updated: Nov 21, 2025 Security To register with WhatsApp, users must register using their phone number. During this sign-up process⁠, WhatsApp verifies the user has ownership of this phone number by sending a 6-digit registration code via SMS or phone call. For many WhatsApp users, their phone number will continue to be the same as the number they have registered with WhatsApp. However, WhatsApp does not enforce ownership of the phone number past initial registration, so there is no guarantee that a phone number and the WhatsApp account tied to that phone number are owned by the same individual. In particular, since phone numbers are recycled by mobile providers, it is possible that if your user currently owns the phone number and does not use WhatsApp, the previous owner of that phone number still has access to the WhatsApp account tied to that phone number⁠. As such, for sensitive authentication use cases such as account recovery (where a code sent via WhatsApp may be the only authentication factor), a phone number and the WhatsApp account tied to that phone number should not be treated interchangeably. In these cases, some best practices may apply:Explicitly verifying that your user owns the WhatsApp account as you would any other new authentication channel, by sending e.g. an initial OTP and having the user enter it in your app during registration or while they are logged in.Showing an additional challenge to verify the user, on top of the code sent via WhatsApp. With the first method, you can take advantage of our identity change check systems on Cloud API to “bind” the WhatsApp account to your user’s account, making sure that future messages only reach the WhatsApp user who received that initial OTP. For example, on Cloud API you should store the identity hash received after sending the initial OTP and (assuming the verification was successful) include it in all subsequent message send requests. This setup would improve security over SMS as message delivery would fail if the phone number is recycled and the new owner registers on WhatsApp (OTP codes will not be accidentally sent to an unintended recipient). To combat phishing, WhatsApp disables forwarding⁠ of authentication messages. Messages travel end-to-end encrypted between Cloud API and the user. WhatsApp does not support and cannot validate the security practices of unofficial apps⁠. There is no guarantee that authentication via WhatsApp is secure for users who use these apps. UX Collect opt-in Per the WhatsApp Business Messaging Policy⁠, you must get opt-in before send you can send a message to a WhatsApp user. A common implementation is to offer users a choice of authentication channels (WhatsApp, e-mail, SMS, etc.), as shown in our sample application. Resolving message delivery issues If you are seeing issues where users are selecting WhatsApp but messages end up being undeliverable, it is possible users are accidentally selecting WhatsApp when they in fact are not registered on WhatsApp. To mitigate this, on Android, you can check if WhatsApp is installed and only show WhatsApp in this case. fun isWhatsAppAvailable(context:Context){return isAppAvailable(context,"com.whatsapp")|| isAppAvailable(context,"com.whatsapp.w4b")} fun isAppAvailable( context:Context, packageName:String):Boolean{ val intent =Intent() intent.setPackage(packageName) intent.action ="com.whatsapp.otp.OTP_REQUESTED" val packageManager = context.packageManager val listActivities = packageManager.queryBroadcastReceivers(intent,0)return listActivities.isNotEmpty()} If you are still seeing issues where users are selecting WhatsApp but messages end up being undeliverable, it is also possible that the WhatsApp phone number is not correct. This could be through a user typo error, or that an app is incorrectly assuming the initial registration phone number is the same as the WhatsApp phone number. Users may have a phone number used for SMS and a different phone number used for WhatsApp, in the case where they might have multiple SIM cards for traveling. You should ensure that if WhatsApp is chosen as the authentication channel that the user has a chance to confirm their WhatsApp phone number. If messages are being delivered but you are seeing lower than expected conversion rates in your authentication flows, consider adopting our more seamless “one-tap autofill” functionality, available for Android. Support all apps Your users may be ready to receive messages through WhatsApp or the WhatsApp Business App (or both). If following our Android client implementation guide, your “one-tap autofill” messages should work with any combination of installs, but we recommend testing one-tap across both the consumer app and the business app. Be ready to receive the code from WhatsApp If integrating with “one-tap autofill” functionality, you should be able to handle the code arriving as soon as you have sent the handshake. WhatsApp will send the code when received regardless of what screen is currently shown on your app. For example, in situations with poor network connectivity, you may receive the code before you are able to load the code entry screen in your app. To handle these cases, one option is to store the received code such that the app can retrieve it when the next screen is fully loaded. This way, the code can be automatically filled by your app as soon as the code is received. Business accounts and phone numbers Every business must have its own WhatsApp Business Account and be sending authentication templates through its own phone number, as opposed to sharing WABAs and phone numbers with separate business entities. Sharing a WABA across multiple businesses is against policy as it conflicts with the WhatsApp Business Terms of Service⁠ and WhatsApp Business Messaging Policy⁠, in addition to creating poor user and business experiences on WhatsApp. Checking if WhatsApp is installed on Android and iOS Checking on Android You can check WhatsApp installation before offering WhatsApp as an option if you expect both WhatsApp and your app to be on the same device. First, you need to add the following to your AndroidManifest.xml file: Using the SDK (Preferred) Instantiate the WhatsAppOtpHandler object: WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler(); Check if the WhatsApp client is installed by passing the isWhatsAppInstalled method as the clause in an If statement: If(whatsAppOtpHandler.isWhatsAppInstalled(context)){// ... do something} Without the SDK if(this.isWhatsAppInstalled(context)){// ... do something}publicboolean isWhatsAppInstalled(final@NonNullContext context){return isWhatsAppInstalled(context,"com.whatsapp")|| isWhatsAppInstalled(context,"com.whatsapp.w4b");}publicboolean isWhatsAppInstalled(final@NonNullContext context,final@NonNullString type){finalIntent intent =newIntent(); intent.setPackage(type); intent.setAction("com.whatsapp.otp.OTP_REQUESTED");PackageManager packageManager = context.getPackageManager();List receivers = packageManager.queryBroadcastReceivers(intent,0);return!receivers.isEmpty();}} Checking on iOS Use the following code in your iOS application to check if WhatsApp is installed let schemeURL = URL(string:"whatsapp://otp")!let isWhatsAppInstalled =UIApplication.shared.canOpenURL(schemeURL) Best practices for authenticating users via WhatsApp | Developer Documentation Best practices for authenticating users via WhatsApp Updated: Nov 21, 2025 Security To register with WhatsApp, users must register using their phone number. During this sign-up process⁠, WhatsApp verifies the user has ownership of this phone number by sending a 6-digit registration code via SMS or phone call. For many WhatsApp users, their phone number will continue to be the same as the number they have registered with WhatsApp. However, WhatsApp does not enforce ownership of the phone number past initial registration, so there is no guarantee that a phone number and the WhatsApp account tied to that phone number are owned by the same individual. In particular, since phone numbers are recycled by mobile providers, it is possible that if your user currently owns the phone number and does not use WhatsApp, the previous owner of that phone number still has access to the WhatsApp account tied to that phone number⁠. As such, for sensitive authentication use cases such as account recovery (where a code sent via WhatsApp may be the only authentication factor), a phone number and the WhatsApp account tied to that phone number should not be treated interchangeably. In these cases, some best practices may apply:Explicitly verifying that your user owns the WhatsApp account as you would any other new authentication channel, by sending e.g. an initial OTP and having the user enter it in your app during registration or while they are logged in.Showing an additional challenge to verify the user, on top of the code sent via WhatsApp. With the first method, you can take advantage of our identity change check systems on Cloud API to “bind” the WhatsApp account to your user’s account, making sure that future messages only reach the WhatsApp user who received that initial OTP. For example, on Cloud API you should store the identity hash received after sending the initial OTP and (assuming the verification was successful) include it in all subsequent message send requests. This setup would improve security over SMS as message delivery would fail if the phone number is recycled and the new owner registers on WhatsApp (OTP codes will not be accidentally sent to an unintended recipient). To combat phishing, WhatsApp disables forwarding⁠ of authentication messages. Messages travel end-to-end encrypted between Cloud API and the user. WhatsApp does not support and cannot validate the security practices of unofficial apps⁠. There is no guarantee that authentication via WhatsApp is secure for users who use these apps. UX Collect opt-in Per the WhatsApp Business Messaging Policy⁠, you must get opt-in before send you can send a message to a WhatsApp user. A common implementation is to offer users a choice of authentication channels (WhatsApp, e-mail, SMS, etc.), as shown in our sample application. Resolving message delivery issues If you are seeing issues where users are selecting WhatsApp but messages end up being undeliverable, it is possible users are accidentally selecting WhatsApp when they in fact are not registered on WhatsApp. To mitigate this, on Android, you can check if WhatsApp is installed and only show WhatsApp in this case. fun isWhatsAppAvailable(context:Context){return isAppAvailable(context,"com.whatsapp")|| isAppAvailable(context,"com.whatsapp.w4b")} fun isAppAvailable( context:Context, packageName:String):Boolean{ val intent =Intent() intent.setPackage(packageName) intent.action ="com.whatsapp.otp.OTP_REQUESTED" val packageManager = context.packageManager val listActivities = packageManager.queryBroadcastReceivers(intent,0)return listActivities.isNotEmpty()} If you are still seeing issues where users are selecting WhatsApp but messages end up being undeliverable, it is also possible that the WhatsApp phone number is not correct. This could be through a user typo error, or that an app is incorrectly assuming the initial registration phone number is the same as the WhatsApp phone number. Users may have a phone number used for SMS and a different phone number used for WhatsApp, in the case where they might have multiple SIM cards for traveling. You should ensure that if WhatsApp is chosen as the authentication channel that the user has a chance to confirm their WhatsApp phone number. If messages are being delivered but you are seeing lower than expected conversion rates in your authentication flows, consider adopting our more seamless “one-tap autofill” functionality, available for Android. Support all apps Your users may be ready to receive messages through WhatsApp or the WhatsApp Business App (or both). If following our Android client implementation guide, your “one-tap autofill” messages should work with any combination of installs, but we recommend testing one-tap across both the consumer app and the business app. Be ready to receive the code from WhatsApp If integrating with “one-tap autofill” functionality, you should be able to handle the code arriving as soon as you have sent the handshake. WhatsApp will send the code when received regardless of what screen is currently shown on your app. For example, in situations with poor network connectivity, you may receive the code before you are able to load the code entry screen in your app. To handle these cases, one option is to store the received code such that the app can retrieve it when the next screen is fully loaded. This way, the code can be automatically filled by your app as soon as the code is received. Business accounts and phone numbers Every business must have its own WhatsApp Business Account and be sending authentication templates through its own phone number, as opposed to sharing WABAs and phone numbers with separate business entities. Sharing a WABA across multiple businesses is against policy as it conflicts with the WhatsApp Business Terms of Service⁠ and WhatsApp Business Messaging Policy⁠, in addition to creating poor user and business experiences on WhatsApp. Checking if WhatsApp is installed on Android and iOS Checking on Android You can check WhatsApp installation before offering WhatsApp as an option if you expect both WhatsApp and your app to be on the same device. First, you need to add the following to your AndroidManifest.xml file: Using the SDK (Preferred) Instantiate the WhatsAppOtpHandler object: WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler(); Check if the WhatsApp client is installed by passing the isWhatsAppInstalled method as the clause in an If statement: If(whatsAppOtpHandler.isWhatsAppInstalled(context)){// ... do something} Without the SDK if(this.isWhatsAppInstalled(context)){// ... do something}publicboolean isWhatsAppInstalled(final@NonNullContext context){return isWhatsAppInstalled(context,"com.whatsapp")|| isWhatsAppInstalled(context,"com.whatsapp.w4b");}publicboolean isWhatsAppInstalled(final@NonNullContext context,final@NonNullString type){finalIntent intent =newIntent(); intent.setPackage(type); intent.setAction("com.whatsapp.otp.OTP_REQUESTED");PackageManager packageManager = context.getPackageManager();List receivers = packageManager.queryBroadcastReceivers(intent,0);return!receivers.isEmpty();}} Checking on iOS Use the following code in your iOS application to check if WhatsApp is installed let schemeURL = URL(string:"whatsapp://otp")!let isWhatsAppInstalled =UIApplication.shared.canOpenURL(schemeURL) One-tap autofill authentication templates | Developer Documentation One-tap autofill authentication templates Updated: Feb 6, 2026 Upcoming deprecation: Starting April 15, 2026, the PendingIntent-based handshake method for authentication templates will be deprecated. If you are currently using PendingIntent to initiate handshakes or verify app identity, the OTP Android SDK is the preferred way to migrate. One-tap autofill authentication templates allow you to send a one-time password or code along with an one-tap autofill button to your users. When a WhatsApp user taps the autofill button, the WhatsApp client triggers an activity which opens your app and delivers it the password or code. One-tap autofill button authentication templates consist of:Preset text: is your verification code.An optional security disclaimer: For your security, do not share this code.An optional expiration warning (optional): This code expires in minutes.A one-tap autofill button. Note: The OTP Android SDK features a simplified workflow for implementing one-tap and zero-tap authentication templates. You can learn how to use it below. Limitations One-tap autofill buttons are only supported on Android. If you send an authentication template to a WhatsApp user who is using a non-Android device, the WhatsApp client will display a copy code button instead. URLs, media, and emojis are not supported. App signing key hash You must include your app signing key hash in your post body. To calculate your hash, follow Google’s instructions for computing your app’s hash string⁠. Alternatively, if you follow Google’s instructions and download your app signing key certificate (step 1), you can use your certificate with the sms_retriever_hash_v9.sh⁠ shell script to compute the hash. For example: ./sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/.android/debug.keystore Supported apps The supported_apps array allows you define pairs of app package names and signing key hashes for up to 5 apps. This can be useful if you have different app builds and want each of them to be able to initiate the handshake: Alternatively, if you are using Graph API version 20.0 or older and have only a single app, you can define the app’s package name and signing key hash as buttons object properties, but this is not recommended as we will stop supporting this method starting with version 21.0: Handshake You must signal to the WhatsApp client to expect imminent delivery of a password or code. You can do this by initiating a “handshake”. A handshake is an Android intent and public class that you implement but that the WhatsApp client can start. When a user in your app requests a one-time password or verification code and chooses for it to be delivered to their WhatsApp number, first perform the handshake, then call our API to send the authentication template message. When the WhatsApp client receives the message, it will perform an eligibility check, and if there are no errors, start the intent and display the message to the user. Finally, when the user taps the message’s one-tap autofill button, we automatically load your app and pass it the password or code. If you do not perform a handshake before sending the message, or the message fails an eligibility check, the delivered message will display a copy code button instead of a one-tap button. Eligibility check The WhatsApp client performs the following checks when it receives an authentication template message. If any check fails, the one-tap autofill button will be replaced with a copy code button.The handshake was initiated no more than 10 minutes ago (or no more than the number of minutes indicated by the template’s code_expiration_minutes property, if present).The package name in the message (defined in the package_name property in the components array upon template creation) matches the package name set on the intent. The match is determined through the getCreatorPackage method called in the PendingIntent object provided by your application.None of the other apps that you included in the template’s list of supported_apps initiated a handshake in the last 10 minutes (or the number of minutes indicated by the template’s code_expiration_minutes property, if present).The app signing key hash in the message (defined in the signature_hash property in the components array upon template creation) matches your installed app’s signing key hash.The message includes the one-tap autofill button text.Your app has defined an activity to receive the password or code. Android notifications Android notifications indicating receipt of a WhatsApp authentication template message will only appear on the user’s Android device if:The user is logged into the WhatsApp app or WhatsApp Business app with the phone number (account) that the message was sent to.The user is logged into your app.Android OS is KitKat (4.4, API 19) or above.Show notifications is enabled (Settings > Notifications) in the WhatsApp app or WhatsApp Business app.Device level notification is enabled for the WhatsApp app or WhatsApp Business app.Prior message threads in the WhatsApp app or WhatsApp Business app between the user and your business are not muted. Using the SDK The OTP Android SDK can be used to perform handshakes, as well as other functions in both one-tap and zero-tap authentication templates. To access SDK functionality, add the following configuration to your Gradle file: dependencies {… implementation 'com.whatsapp.otp:whatsapp-otp-android-sdk:1.0.0'…} To your repositories, add mavenCentral(): repositories {… mavenCentral()…} Activity Declare an activity and intent filter that can receive the one-time password or code. The intent filter must have the action name com.whatsapp.otp.OTP_RETRIEVED. This is the activity that the WhatsApp app or WhatsApp Business app will start once the authentication template message is received and it passes all eligibility checks. Activity class Using the SDK (Preferred) Define the activity public class and instantiate a WhatsAppOtpIncomingIntentHandler object to handle the intent. The .processOtpCode() method validates the handshake ID against the expected value you stored during handshake initiation and handles errors. publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);WhatsAppOtpIncomingIntentHandler incomingIntentHandler =newWhatsAppOtpIncomingIntentHandler();// Retrieve the expected handshake ID that was stored during handshake initiationString expectedHandshakeId = retrieveStoredHandshakeId(); incomingIntentHandler.processOtpCode( getIntent(), expectedHandshakeId,(code)->{// The handshake ID has been validated by the SDK validateCode(code);},// call your function to handle errors(error, exception)-> handleError(error, exception));} Without the SDK Define the activity public class that can accept the code once it has been passed to your app. The activity should validate the request_id (handshake ID) to ensure the OTP code is coming from a legitimate handshake initiated by your app. publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);Intent intent = getIntent();// Extract the handshake ID from the intentString incomingRequestId = intent.getStringExtra("request_id");// Retrieve the previously stored handshake IDString storedRequestId = retrieveStoredRequestId();// Validate the handshake ID matchesif(storedRequestId !=null&& storedRequestId.equals(incomingRequestId)){// use OTP codeString otpCode = intent.getStringExtra("code");// ...}}} Initiating the handshake Using the SDK (Preferred) Performing a handshake can be done by instantiating the WhatsAppOtpHandler object and passing in your context to the .sendOtpIntentToWhatsApp() method. The method returns a UUID (handshake ID) that must be stored and used to validate the incoming OTP code later: WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler(); UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp(context);// Store handshakeId to validate the received OTP code later Without the SDK This example demonstrates one way to initiate a handshake with the WhatsApp client. The handshake includes a request_id (UUID) that must be stored and validated when receiving the OTP code. privateString currentRequestId;publicvoid sendOtpIntentToWhatsApp(){// Generate a unique handshake ID currentRequestId = UUID.randomUUID().toString();// Store this ID for later validation when receiving the OTP storeRequestId(currentRequestId);// Send OTP_REQUESTED intent to both WA and WA Business App sendOtpIntentToWhatsApp("com.whatsapp", currentRequestId); sendOtpIntentToWhatsApp("com.whatsapp.w4b", currentRequestId);}privatevoid sendOtpIntentToWhatsApp(String packageName,String requestId){/** * Starting with Build.VERSION_CODES.S, it will be required to explicitly * specify the mutability of PendingIntents on creation with either * (@link #FLAG_IMMUTABLE} or FLAG_MUTABLE */int flags =Build.VERSION.SDK_INT >=Build.VERSION_CODES.S ? FLAG_IMMUTABLE :0;PendingIntent pi =PendingIntent.getActivity( getApplicationContext(),0,newIntent(), flags);// Send OTP_REQUESTED intent to WhatsAppIntent intentToWhatsApp =newIntent(); intentToWhatsApp.setPackage(packageName); intentToWhatsApp.setAction("com.whatsapp.otp.OTP_REQUESTED");// WA will use this to verify the identity of the caller app.Bundle extras = intentToWhatsApp.getExtras();if(extras ==null){ extras =newBundle();} extras.putParcelable("_ci_", pi);// Add the handshake ID for secure validation intentToWhatsApp.putExtra("request_id", requestId); intentToWhatsApp.putExtras(extras); getApplicationContext().sendBroadcast(intentToWhatsApp);} Checking if WhatsApp is installed on Android You can check WhatsApp installation before offering WhatsApp as an option if you expect both WhatsApp and your app to be on the same device. First, you need to add the following to your AndroidManifest.xml file: Using the SDK (Preferred) Instantiate the WhatsAppOtpHandler object: WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler(); Check if the WhatsApp client is installed by passing the isWhatsAppInstalled method as the clause in an If statement: If(whatsAppOtpHandler.isWhatsAppInstalled(context)){// ... do something} Without the SDK if(this.isWhatsAppInstalled(context)){// ... do something}publicboolean isWhatsAppInstalled(final@NonNullContext context){return isWhatsAppInstalled(context,"com.whatsapp")|| isWhatsAppInstalled(context,"com.whatsapp.w4b");}publicboolean isWhatsAppInstalled(final@NonNullContext context,final@NonNullString type){finalIntent intent =newIntent(); intent.setPackage(type); intent.setAction("com.whatsapp.otp.OTP_REQUESTED");PackageManager packageManager = context.getPackageManager();List receivers = packageManager.queryBroadcastReceivers(intent,0);return!receivers.isEmpty();}} Checking if WhatsApp is installed on iOS Use the following code in your iOS application to check if WhatsApp is installed let schemeURL = URL(string:"whatsapp://otp")!let isWhatsAppInstalled =UIApplication.shared.canOpenURL(schemeURL) Error signals See Error Signals that can help with debugging. Handshake ID error codes The following error codes may be returned when using the SDK with handshake ID validation: Error Code Description HANDSHAKE_ID_MISSING The handshake ID was not included in the intent from WhatsApp HANDSHAKE_ID_INVALID_FORMAT The handshake ID is not a valid UUID format HANDSHAKE_ID_MISMATCH The handshake ID in the intent does not match the expected value Sample app See our WhatsApp One-Time Password (OTP) Sample App⁠ for Android on Github. The sample app demonstrates how to send and receive OTP passwords and codes via the API, how to integrate the one-tap autofill and copy code buttons, how to create a template, and how to spin up a sample server. Zero-tap authentication templates | Developer Documentation Zero-tap authentication templates Updated: Feb 6, 2026 Upcoming deprecation: Starting April 15, 2026, the PendingIntent-based handshake method for authentication templates will be deprecated. If you are currently using PendingIntent to initiate handshakes or verify app identity, the OTP Android SDK is the preferred way to migrate. Zero-tap authentication templates allow your users to receive one-time passwords or codes via WhatsApp without having to leave your app. When a user in your app requests a password or code and you deliver it using a zero-tap authentication template, the WhatsApp client simply broadcasts the included password or code and your app can capture it immediately with a broadcast receiver. From your user’s perspective, they request a password or code in your app and it appears in your app automatically. If your app user happens to check the message in the WhatsApp client, they will only see a message displaying the default fixed text: < code > is your verification code. Like one-tap autofill button authentication templates, when the WhatsApp client receives the template message containing the user’s password or code, we perform a series of eligibility checks. If the message fails this check and we are unable to broadcast the password or code, the message will display either a one-tap autofill button or a copy code button. For this reason, when you create a zero-tap authentication template, you must include a one-tap autofill and copy code button in your post body payload, even if the user may never see one of these buttons. Note: The OTP Android SDK features a simplified workflow for implementing one-tap and zero-tap authentication templates. You can learn how to use it below. Limitations Zero-tap is only supported on Android. If you send a zero-tap authentication template to a WhatsApp user who is using a non-Android device, the WhatsApp client will display a copy code button instead. URLs, media, and emojis are not supported. Best practicesDo not make WhatsApp your default password/code delivery method.Make it clear to your app users that the password or code will be automatically delivered to your app when they select WhatsApp for delivery.Link to our About security codes that automatically fill on WhatsApp⁠ help center article if your users are worried about auto-delivery of the password or code.After the password/code is used in your app, make it clear to your app user that it was received successfully. Here are some examples that make it clear to an app user that their code will automatically appear in the app. App signing key hash You must include your app signing key hash in your post body. To calculate your hash, follow Google’s instructions for computing your app’s hash string⁠. Alternatively, if you follow Google’s instructions and download your app signing key certificate (step 1), you can use your certificate with the sms_retriever_hash_v9.sh⁠ shell script to compute the hash. For example: ./sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/.android/debug.keystore Supported apps The supported_apps array allows you define pairs of app package names and signing key hashes for up to 5 apps. This can be useful if you have different app builds and want each of them to be able to initiate the handshake: Alternatively, if you are using Graph API version 20.0 or older and have only a single app, you can define the app’s package name and signing key hash as buttons object properties, but this is not recommended as we will stop supporting this method starting with version 21.0: Error signals See Error Signals that can help with debugging. Handshake ID Error Codes The following error codes may be returned when using the SDK with handshake ID validation: Error Code Description HANDSHAKE_ID_MISSING The handshake ID was not included in the intent from WhatsApp HANDSHAKE_ID_INVALID_FORMAT The handshake ID is not a valid UUID format HANDSHAKE_ID_MISMATCH The handshake ID in the intent does not match the expected value Copy code authentication templates | Developer Documentation Copy code authentication templates Updated: Nov 4, 2025 Copy code authentication templates allow you to send a one-time password or code along with a copy code button to your users. When a WhatsApp user taps the copy code button, the WhatsApp client copies the password or code to the device’s clipboard. The user can then switch to your app and paste the password or code into your app. Note: The “I didn’t request a code” button is currently in beta and is being rolled out incrementally to business customers. Copy code button authentication templates consist of: Preset text: is your verification code.An optional security disclaimer: For your security, do not share this code.An optional expiration warning (optional): This code expires in minutes.A copy code button. Limitations URLs, media, and emojis are not supported. Sample app See our WhatsApp One-Time Password (OTP) Sample App⁠ for Android on Github. The sample app demonstrates how to send and receive OTP passwords and codes via the API, how to integrate the one-tap autofill and copy code buttons, how to create a template, and how to spin up a sample server. Error Signals | Developer Documentation Error Signals Updated: Feb 6, 2026 Upcoming deprecation: Starting April 15, 2026, the PendingIntent-based handshake method for authentication templates will be deprecated. If you are currently using PendingIntent to initiate handshakes or verify app identity, the OTP Android SDK is the preferred way to migrate. The OTP Android SDK features a simplified workflow for implementing one-tap and zero-tap authentication templates. You can learn how to use it below. This document describes Android-only error signals that can help you debug one-tap autofill authentication templates and zero-tap authentication templates. If your message fails the eligibility check, the one-tap autofill button will be replaced with a copy code button. In addition, there may be device or WhatsApp client settings that prevent message notifications. To help with debugging, our apps surface some error information via the com.whatsapp.OTP_ERROR intent. In these situations you will receive an error key and message instead of the user’s one-time passwords or verification code. Note that some of these error signals will only surface if you are running WhatsApp in the Android emulator. Key Description ambiguous_delivery_destination Emulator only Ambiguous delivery destination There are multiple active OTP requests for the packages specified by this template, and we could not determine which package to deliver the code to. This can happen when multiple applications specified in the template’s supported_apps array have initiated the handshake (sent the com.whatsapp.otp.OTP_REQUESTED intent) within the past 10 minutes. incompatible_os_version Incompatible Android version This can happen when you initiate the handshake (send the com.whatsapp.otp.OTP_REQUESTED intent) but the device is running a version of Android older than v19. incorrect_signature_hash Emulator only Incorrect signature hash This can happen when you initiate the handshake (send the com.whatsapp.otp.OTP_REQUESTED intent) and our app receives an authentication template message that uses a one-tap autofill button, but the package name in the message does not produce the message’s signature hash. missing_handshake_or_disorder Missing handshake / Order of operations This can happen when our app receives an authentication template message with a one-tap autofill button but the handshake was not initiated. otp_request_expired OTP request expired This can happen when an authentication template that uses a one-tap autofill button is delivered to the user but more than 10 minutes (or the number of minutes indicated in the template’s code_expiration_minutes property, if present) have passed since you initiated the handshake. In this situation, we display the copy code button instead. whatsapp_message_notification_disabled Emulator only Message notification disabled in WA settings This can happen when you initiate the handshake (send the com.whatsapp.otp.OTP_REQUESTED intent) but the user has disabled notifications in the WhatsApp app or WhatsApp Business app (within our app settings). whatsapp_notification_disabled Emulator only WA notification disabled in device level This can happen when you initiate the handshake (send the com.whatsapp.otp.OTP_REQUESTED intent) but the user has disabled app notifications for our apps (device level settings). Integration The error signals are delivered via broadcasted intent so you must implement BroadcastReceiver⁠ to listen for error signals. In manifest.xml Receiver class - Using the SDK (Preferred) Implement onReceive and use a WhatsAppOtpIncomingIntentHandler object to process the debug signals. publicclassOtpErrorReceiverextendsBroadcastReceiver{@Overridepublicvoid onReceive(Context context,Intent intent){WhatsAppOtpIncomingIntentHandler whatsAppOtpIncomingIntentHandler =newWhatsAppOtpIncomingIntentHandler(); whatsAppOtpIncomingIntentHandler.processOtpDebugSignals( intent,// your function to handle the signal(debugSignal)-> handleSignal(debugSignal),// your function to handle any error(error, exception)-> handleError(error, exception));}} Receiver class - Without the SDK publicclassOtpErrorReceiverextendsBroadcastReceiver{publicstaticfinalString OTP_ERROR_KEY ="error";publicstaticfinalString OTP_ERROR_MESSAGE_KEY ="error_message";@Overridepublicvoid onReceive(Context context,Intent intent){String otpErrorKey = intent.getStringExtra(OTP_ERROR_KEY);String otpErrorMessage = intent.getStringExtra(OTP_ERROR_MESSAGE_KEY);// Handle errors}} Bulk management | Developer Documentation Bulk management Updated: Nov 10, 2025 If a template already exists with a matching name and language, the template will be updated with the contents of the request, otherwise, a new template will be created. Post Body Properties All template creation properties are supported, with these exceptions:The language property is not supported. Instead, use languages and set its value to an array of language and locale code strings. For example: ["en_US","es_ES","fr"].The text property is not supported.The autofill_text property is not supported. Template previews | Developer Documentation Template previews Updated: Nov 4, 2025 Request parameters Placeholder Description Example Value Comma-separated list Optional. Comma-separated list of language and locale codes of language versions you want returned. If omitted, versions of all supported languages will be returned. en_US,es_ES Boolean Optional. Set to true if you want the security recommendation body string included in the response. If omitted, the security recommendation string will not be included. true Int64 Optional. Set to an integer if you want the code expiration footer string included in the response. If omitted, the code expiration footer string will not be included. Value indicates number of minutes until code expires. Minimum 1, maximum 90. 10 Comma-separated list of strings Required. Comma-separated list of strings indicating button type. If included, the response will include the button text for each button in the response. For authentication templates, this value must be OTP. OTP Templates | Developer Documentation Templates Updated: Dec 5, 2025 Learn about templates, their uses and limitations, and the various types of templates you can create. Templates are WhatsApp Business Account assets that can be sent in template messages via Cloud API or Marketing Messages API for WhatsApp. Template messages are the only type of message that can be sent to WhatsApp users outside of a customer service window, so templates are commonly used when messaging users in bulk, or when you need to message a user, but no customer service window is open between you and the user. Creation Template creation via API uses a common syntax. The bulk of the variation occurs in the category string, which assigns a category to the template, and the components array, which defines the components that make up the template. You can create a maximum of 100 templates in a WhatsApp Business Account per hour. Names Every template must have a name, but names are not unique. This flexibility allows you to create multiple templates with the same name, but in different languages. Template names are limited to a maximum of 512 characters, consisting of lowercase alphanumeric characters and underscores. Categories Each template must be categorized as authentication, marketing, or utility. Our template categorization document describes how to assign the proper category to a template, and what can happen if we determine that a template has been mis-categorized. Note that template categories also factor into pricing. Components Templates are made up of various text, media, and interactive UI components, which you define upon template creation. Our template components document describes all possible components and how to define them. Since there are a lot of components to choose from, we have dedicated authentication, marketing, and utility template documents and sub-documents, each with code examples that show how to create various templates with commonly used components. Languages You must assign a template language code upon template creation. Template strings and variables are not translated by Meta, so you are responsible for supplying strings and example parameters in their appropriate language. If you create multiple templates with the same name but with different languages, each template counts against your template limit. Parameter formats Some template components allow you to define strings that contain one or more parameters (described as “variables” in WhatsApp Manager). These are replaced with values included by you in your send message payload when you send the template. Upon template creation, if a string includes one or more parameters, you can specify their format — either named or positional — and you must include an example value for each parameter. If you do not specify a format, the template will use positional format by default. Named parameters Parameters using the named format must be unique, single strings, composed of lowercase characters and underscores, wrapped in double curly brackets, for example, {{first_name}}. Example values in template creation payloads and real values in template send payloads can appear in any order. Example template creation payload with named parameters: Example template send payload of template that uses named parameters: Positional parameters Positional parameters must be ordered array index numbers, starting from 1, wrapped in double curly brackets: ( {{1}}... {{2}}...and so on). Example values in template creation payloads and real values in template send payloads must appear in the order in which their corresponding placeholders appear in the component text string. Example template creation payload with positional parameter: Example template send payload of template that uses positional parameter: Media Template header components can display media assets. If you are creating a template with a media header, you must use the Resumable Upload API to obtain an asset handle, and include this asset handle in your template creation request. The example asset will be reviewed as part of template review. Template review Templates are automatically reviewed upon creation or after editing. If your template is approved, its status will be set to APPROVED and you can begin sending it in template messages. If it is rejected, or if its status changes to any other value, it cannot be sent in template messages. See our template review document to learn more about the template review process, common rejection reasons, and what you can do if your template is rejected. Template limits The number of templates a WhatsApp Business Account can have is determined by its parent business portfolio. If a parent business portfolio is unverified, each of its WhatsApp Business Accounts is limited to 250 message templates. However, if the portfolio is verified⁠, and at least one of its WhatsApp Business Accounts has a business phone number with an approved display name, each of its WhatsApp Business Accounts can have up to 6,000 templates. Additionally, there are limits on the number of templates you can send, as well as processes that can affect template delivery:Messaging limits — A limit on the number of message templates you can send outside of customer service windows.Template pacing — A process that allows time for WhatsApp users to provide feedback on message templates.Template pausing — A process that can temporarily pause message templates that have received poor feedback.Per-user marketing template message limits — A process that limits the number of marketing message templates a given WhatsApp user may receive from any business. Time-to-live If a message sent to a WhatsApp user cannot be delivered, the system will continue attempting delivery for a period known as the time-to-live (TTL). You can customize the TTL for templates upon template creation. See our time-to-live document for more information. Quality rating Template quality rating is a system used to evaluate the quality of message templates, based on usage, customer feedback, and engagement. This rating helps maintain a high-quality messaging ecosystem and helps ensure that you are sending relevant and well-received messages. See our template quality rating document for more information about quality ratings, how they can affect a template’s status, and how you can be notified of changes to template quality scores. Delivery sequence of multiple messages When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a status messages webhook before sending the next message in your message sequence. Template management See our template management document for a list of endpoints commonly used for getting, updating, and deleting templates. Marketing templates | Developer Documentation Marketing templates Updated: Dec 5, 2025 Marketing templates are typically used to drive engagement, brand awareness, and driving sales. They are the only type of template that can be used with both Cloud API and Marketing Messages API for WhatsApp. Custom templates See our custom marketing templates document for example of how to create and send a custom template, and which components are supported. Specialty templates Some templates use a special component that requires or excludes additional components, or require additional configuration. These are described below. Catalog templates Catalog templates are marketing templates that allow you to showcase your product catalog entirely within WhatsApp. Coupon code templates Coupon code templates are marketing templates that display a single copy code button. When tapped, the code is copied to the customer’s clipboard. Media card carousel templates Media card carousel templates allow you to send a single text message accompanied by a set of up to 10 media cards in a horizontally scrollable view. Call permission request templates Call permission request templates allow your business to call your customers outside of the customer service window. Limited-time offer templates Limited-time offer templates allow you to display expiration dates and running countdown timers for offer codes in template messages, making it easy for you to communicate time-bound offers and drive customer engagement. Multi-product message templates Multi-product message templates allow you to showcase up to 30 products from your ecommerce catalog, organized in up to 10 sections, in a single message. Product card carousel templates Product card carousel templates allow you to send a single text message accompanied by a set of up to 10 product cards in a horizontally scrollable view: Single-product message templates Single-product message templates allow you to send a single text message accompanied by a set of up to 10 product cards in a horizontally scrollable view: Per-user marketing template message limits WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time, starting with delivering fewer marketing conversations to those users who are less likely to engage with them. In most WhatsApp markets, this is determined based on a number of factors, including a dynamic view of an individual’s marketing message read rate. Refer to per-user marketing template message limits document for more information. User preferences for marketing messages WhatsApp provides a setting, Offers and announcements, that allows WhatsApp users to indicate their interest level in marketing messages sent from your business, and to stop or resume delivery of marketing messages from your business entirely. Interested/Not Interested feedback WhatsApp users can use the Offers and announcements setting to indicate how interested they are in receiving marketing template messages from your business. If a user chooses Not interested, it can affect per-user marketing template messaging limits between you and the user. Choosing this option also displays the second modal, which gives the user the option to stop delivery of marketing messages from your business. Stop/Resume controls WhatsApp users can use the Offers and announcements setting to stop or resume delivery of marketing template messages from your business. If you attempt to send a marketing template to a WhatsApp user who has stopped marketing template messages from your business, the API will process the request but not send the message. Instead, the API will trigger a status messages webhook with: status set to failed, code set to 131050, title set to Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business To be notified whenever a WhatsApp user stops or resumes delivery of marketing template messages from your business, subscribe to the user_preferences webhook webhook. For accounts linked with WhatsApp Business app (aka “Coexistence”) To improve the experience for WhatsApp Business Users, marketing messages sent to business customers will not bump chat threads to the top of the inbox. These messages will still be delivered and visible to business customers, but the thread will only move to the top if the customer responds. Note: This feature is currently limited and not generally available (GA) to all users. Coupon code templates | Developer Documentation Coupon code templates Updated: Dec 3, 2025 Coupon code templates are marketing templates that display a single copy code button. When tapped, the code is copied to the customer's clipboard. Limitations Coupon code templates are currently not supported by the WhatsApp web client.Copy code button text cannot be customized.Templates are limited to one copy code button. Limited-time offer templates | Developer Documentation Limited-time offer templates Updated: Nov 4, 2025 This document describes limited-time offer templates and how to use them. Limited-time offer templates allow you to display expiration dates and running countdown timers for offer codes in template messages, making it easy for you to communicate time-bound offers and drive customer engagement. Limitations Only templates categorized as MARKETING are supported.Footer components are not supported.Users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using. Template categorization | Developer Documentation Template categorization Updated: Jan 30, 2025 When creating a new template, or managing existing ones, it’s important to understand how WhatsApp categorizes your template for pricing purposes.Consider template category guidelines before creating a new templateStay updated on your template’s approval status after template creationLearn about automatic category updates to templates in production This information is also available in PDF form in our Message templates category guidelines explainer PDF. Template category guidelines Our template category guidelines define the category of message templates. Message templates can be categorized as:Marketing templates – Enable businesses to achieve a wide range of goals, from generating awareness to driving sales and retargeting customers.Utility templates – Enable businesses to follow up on user actions or requests, since these messages are typically triggered by user actions.Authentication templates – Enable businesses to verify a user’s identity, potentially at various steps of the customer journey. Marketing template guidelines Marketing templates are the most flexible. They enable businesses to achieve a wide range of goals, from generating awareness to driving sales and more. The following templates are also considered marketing:Templates with mixed content (for example, both utility and marketing, such as an order update with a promo or a feedback survey with promotional content).Templates where contents are unclear (for example, where contents are only “{{1}}” or “Congratulations!”). Note: Examples are illustrative only. Templates that contain similar content, or the example text above, might be categorized differently based on the exact content. Message Objective Business Goal Example Templates Awareness Generate awareness of your business, products, or services among customers who have subscribed to receive messages from your business on WhatsApp. Did you know? We installed a {{new_tower}} in your area so you can enjoy a better network experience. To learn more, visit our site.{{Diwali}} is around the corner! Join us at {{location}} on {{date}} to celebrate with friends and family. For more details about our event, click below.Looking for a getaway this fall? Our newest resort just opened in {{location}}: the perfect place to relax and unwind. Sales Send promotional offers to customers related to sales events, coupons, or other content intended to drive sales or renewals. As a thank you for your last order, please enjoy {{15}}% off your next order. Use code {{loyal15}} at checkout. Visit our site here below.We are actively seeking {{donations}} to meet our fundraising goal of {{amount}}. Support our cause and contribute now!Upgrade to our {{premium_cabin}} to enjoy new benefits, like {{more_legroom}} and {{priority_boarding}}. Click below or log into our app to upgrade.You have been {{pre_approved}} for our {{credit_card}}! Enjoy an introductory {{apr_rate}} if you apply via your personalized link below. Retargeting Promote or recommend offers, products or services; attempt to renew subscriptions; or other calls to action to users who might have visited your website, used your app or engaged with you. These are marketing even if requested by users. Your subscription will expire on {{date}}! Renew today to save {{discount}}.You left {{items}} in your cart! Don’t worry, we saved them. Checkout now below.Your loan application is {{pending_approval}}! Please log in to pick up where you left off.We found a {{car}} that meets your saved search. Log in to our app to view.We apologize for the delay in your {{package}} delivery. We have deposited a {{credit}} to your account, available immediately. App Promotion Request customers to install or take a specific action with your app. Did you know? You can now {{checkout}} in our app. Download it below to use our streamlined experience.Thank you for using our app. We noticed you have not used our {{latest_feature}}. Click below to learn more about how this benefits you!In-app only: {{20}}% off this week! Use code {{summer_promo}} to save on select styles.Hi {{name}}, your friend {{name}} recently joined our community. Send them a welcome message in our app today: {{URL}}. Build Customer Relationships Strengthen customer relationships through personalized messages or by prompting new conversations. {{Name}}, did you think we’d forget? No way! {{Happy_birthday}}! We wish you the best in the year ahead.As we approach the end of the year, we reflect on what drives us: {{Name}}. Thank you for being a {{valued_customer}}. We look forward to continuing to serve you.Hello, I am the new {{virtual_assistant}}. I can help you discover products or provide support. Please reach out if I can help! Utility template guidelines Utility templates are typically triggered by a user action or request. For a template to be categorized as utility, it needs to meet both criteria below:Must be non-promotional, not containing any promotional or persuasive intent.Must ALSO be either specific to or requested by the user (clearly related to their order, account, services or transactions) OR essential or critical to the user (for example, to ensure user safety). Message Objective Business Goal Example Templates Opt-In Management on WhatsApp Confirm opt-in to receive messages on WhatsApp as a follow-up to opt-in collected via other channels (for example, website, email) or confirm opt-out. Thanks for confirming opt-in! You’ll now receive notifications via WhatsApp.Thank you for confirming your opt-out preference. You will no longer receive messages from us on WhatsApp. Order Management Confirm, update or cancel an order or transaction with a customer, using specific order or transaction details in the body of your message. These messages should not promote, recommend, upsell, or cross-sell products; include offers; or attempt to secure renewals. Thank you! Your order {{order_number}} is confirmed. We will let you know once your package is on its way.Hooray! Your package from order {{order_number}} is on its way. Your tracking number is {{tracking_ID}} and expected delivery date is {{date}}.Unfortunately, one item from your order {{number}} is backordered. We will follow up with an estimated ship date. If you wish to cancel and receive a refund, please click below.We have received your item from order {{order_number}}. Your refund for ${{amount}} has been processed. Thank you for your business. Account Alerts or Updates Send important or time-sensitive updates or alerts or other information specific to purchased or subscribed products/services. These messages should not promote, recommend, upsell, or cross-sell products; include offers; or attempt to secure renewals. Daily update for account ending in {{four_digit_number}}: Your available balance is {{amount}}.Reminder: Your monthly payment for {{service}} will be billed on {{date}} to the {{card}} you have saved on file.You only have {{number}} minutes remaining in your plan. Remember to top up your account by {{date}} to avoid disruptions.To finish setting up your {{new_profile}}, you need to upload a {{photo}}. Please click below to upload.Please note, we have updated our {{Customer_service}} phone number to {{number}}. Please save this and call if we can be of support. Feedback Surveys Collect feedback on previous orders, transactions or engagements with customers. Specificity of the order or interaction to which these relate is necessary. A general/generic survey or request for feedback will not be approved as utility. We have delivered your order {{order_number}}! Please let us know if there was any issue by reaching out below.Your feedback ensures we continually {{improve}}. Please click below to share your thoughts on your {{recent visit}} at our {{store}} location. Thank you in advance!You chatted with us {{online}} recently about order {{order_number}}. How was your experience? Click below to fill out a short survey. Continue a Conversation on WhatsApp Send a message to begin an interaction on WhatsApp that began in another channel. These messages should not be initiated without a user having requested the conversation to be moved to WhatsApp. Hi! I see you requested support via our {{online_chat}}. I am the virtual assistant on WhatsApp. How can I help?Hi {{name}}, we are following up on your call with customer service on {{issue}}. Your case has progressed to the next step. Please log into your account to continue. For a utility template to be deemed essential or critical to the user, it must reflect one of the use cases below and must also be non-promotional (not containing any promotional or persuasive intent). Use Case Category Use Case Example that meets definition of "essential or critical to the user" Public Safety Severe weather There is a {{tornado}} alert in your area. We recommend you remain indoors until {{time}} today. Public Safety Crisis response We activated support services for the {{crisis}} in the {{zip code}} area. Live updates on our site, available below. Public Service Health awareness Stay up-to-date with your health. Stop by {{location}} by {{time}} to get your free COVID-19 {{vaccine}}. Bring your {{vaccination_card}} and identification document. Public Service Health emergency The {{city}} has just declared a health emergency because of {{issue}}. We will follow up with more details once available. Public Service Voting registration To vote on {{date}}, please ensure your voter {{registration card}} is active. Please click the URL below to understand steps required to renew, if needed. Please disregard this message if your {{registration card}} will be active. Public Service Disbursements Your {{welfare}} disbursement balance is {{amount}}. Kindly note it will expire on {{date}}. Public Disruption System outages We have detected a system outage that impacts zip code {{code}}. We expect to restore service by {{time_and_date}}. We apologize for the inconvenience. Public Disruption Operational disruption This is to notify you that {{trains}} at our {{location}} station are halted because of {{issue}}. Please avoid the area as we work to rectify. Account or Product Protection Fraud awareness We have detected an increase in {{ATM fraud}}. To protect your card ending in {{1234}}, please consider updating your PIN. Click below to see the step-by-step. Account or Product Protection Product recalls The {{product}} you ordered on {{date}} has been recalled. Please click below to let us know how you would like to proceed. Account or Product Protection Warranty alerts Thank you for your purchase of {{product}}. Your warranty is active as of {{date}}. Our {{product manuals}} are below, for your reference Legal/Regulatory Compliance Identity compliance This is to notify you that you need to upgrade to a {{updated_identification_card}} by {{date}}. To avoid any inconveniences when traveling, please ensure you make an appointment at your local {{office}}. Legal/Regulatory Compliance Privacy disclosures We updated our privacy policy on {{date}}. Please click the button below to learn more. Legal/Regulatory Compliance Warranty alerts Thank you for your purchase of {{product}}. Your warranty is active as of {{date}}. Our {{product manuals}} are below, for your reference Authentication template guidelines Note: Only authentication templates can be used to send a one-time passcode for identity verification. Marketing and utility templates cannot be used for this purpose. You can use authentication templates from Template Library. These templates include optional add-ons like security disclaimers and expiry warnings. Authentication templates enable businesses to verify user identity (usually with alphanumeric codes) at various steps of the customer journey:New account creationAccount integrity, access or recoveryNew or existing orders/transactions Authentication templates are our most restrictive, so for a template to be classified as authentication, a business must:Use Cloud API authentication message templates in Template Library: These templates include optional add-ons like security disclaimers and expiry warnings.Configure a one-time password button: Such as copy-code or one-tapFollow content restrictions: URLs, media, and emojis are not allowed for authentication template content or parameters. Parameters are also restricted to 15 characters. Message Objective: Authentication Message Objective Business Goal Example Templates Authentication Authenticate users with one-time passcodes, potentially at multiple steps in the login process (for example, account verification, account recovery, integrity challenges). {{123456}} is your verification code. How WhatsApp assigns a category during template creation When you create a template, you indicate the template’s category, based on the guidelines above. WhatsApp validates the category you indicated per the contents of the template and the guidelines. The template is then created and its status is set to one of the statuses below, based on the outcome of the validation process. a. When you create a template and it is approved, you can request a review up to 60 days from the creation date. b. For utility templates that may be updated to marketing, you can request a review up to 60 days from the date the category was updated. Approved status APPROVED status means WhatsApp agrees with the category chosen in your template creation request and that the template successfully passed template review. It can now be used to send messages. Status updates — An email and WhatsApp Manager alert will inform you that the template was approved, and a message_template_status_update webhook will be triggered with the event property set to APPROVED. Effective April 9, 2025, If you selected UTILITY as the template’s category and WhatsApp determined it should be MARKETING, the template is approved as MARKETING. In WhatsApp Manager, you will see the screen below. When using the API, the behavior will be as outlined above. You can request a review up to 60 days from the date the category was updated. Effective April 9, 2025 – The allow_category_change property during template creation. Previously, if set to true in a template creation request, this allowed us to update a template’s category to marketing, if marketing to be its category was determined to be its category per its content and the guidelines. This is now the default behavior. Pending status PENDING status means WhatsApp agrees with the category chosen in your template creation request, however the template is undergoing template review. Status Alerts — The outcome of template review will be communicated via email and WhatsApp Manager alert. Upon completion, a message_template_status_update webhook will be triggered with the event property set to APPROVED or REJECTED. Rejected status REJECTED status indicates that WhatsApp disagreed with the category you designated in your template creation request. Status Alerts — Rejections are communicated via email and WhatsApp Manager alert. Upon review completion, a message_template_status_update webhook will be triggered and the event property set to REJECTED, with the reason property set to INCORRECT_CATEGORY. If your message template is rejected, you have the following options:Create a new message template via WhatsApp Manager or the API.Edit the template’s category, and resubmit for approval.Request a review. Duplicated Templates from Phone Number Migration All eligible templates are automatically duplicated in the destination WABA and category checks will be performed to ensure that all duplicated templates are correctly categorized. How WhatsApp updates a template’s category after initial approval July 1, 2024 — To ensure templates on the platform are correctly categorized per the template category guidelines, WhatsApp introduced a recurring process to identify and update approved templates that should be of a different category, per the template category guidelines. Effective April 16, 2025 — For any business detected to be abusing the template categorization system and to whom a warning is sent, the 24-hour notice mentioned below will no longer be provided if a utility template that should be marketing is detected. The category will be updated with no advance notice and emails/webhooks will be triggered to confirm the category change Automatic category updates can apply to approved templates only that were not initially approved per the template category guidelines. Advance notice is provided on different surfaces, like through webhook and email, before action is taken on these templates. How it works For templates approved as utility, but should actually be marketingNotice period — A 1-day advance notice is provided before the template category is updated to marketing. As of April 16 2025 — If you are warned for template categorization misuse:24 hour notice will not be provided before changing template categories from UTILITY to MARKETINGCategory changes will be instantTemplate category — The template category is changed to MARKETINGTemplate status — There is no change to template status; it remains APPROVED and can continue to be used to send messages. For templates approved as marketing or utility, but should actually be authentication This process was introduced on October 1, 2024Notice period — Advance notice is provided.Template category — There is no change in the template’s category.Template status — On the first day of the following month, the template status is changed to REJECTED and can no longer be used to send messages. How you are notified For templates approved as utility, but should actually be marketing Advanced notification of category updates Description Via Email An email will be sent to any people in the business’ portfolio with ‘full control’ of the WhatsApp Business Account (WABA).The email will contain a link to the WhatsApp Manager > Message Templates > Manage Templates panel.Templates whose categories will be updated will have an “information” icon beside their name. Hovering over the icon will display the category it will be updated to, and the date when it will be updated.For templates that will be rejected, the icon will display Via Webhook A template_category_update webhook will be triggered for each template whose category will be updated, with a correct_category property in the payload set to what the template’s category should be. The new_category property also exists in the payload indicating the template’s current category. Via WhatsApp Manager The WhatsApp Manager > Message Templates > Manage Templates panel will display a banner with a link to a downloadable CSV identifying these templates.Business Support⁠ will list the name and current category of these templates, as well as the categories they will be updated to. Notification when action is taken Description Via Email An email will be sent to any people in the business portfolio who have been granted full control of the WABA that owns the templates whose categories have been updated.The email will highlight the number of templates whose categories were updated, and will include a link to the WhatsApp Manager > Message Templates > Manage Templates panel where the name and new category of these templates, as well as the categories before automatic update will be listed. It also includes a link to Business Support⁠. Via Webhook A template_category_update webhook will be triggered for each template whose category has been updated. The new_category property will indicate the template’s new category and the previous_category property will indicate the template’s category before automatic update. For templates approved as marketing or utility, but should actually be authentication Advanced notification of category updates Description Via Email An email will be sent to any people in the business portfolio who have been granted full control of the WABA that owns the templates whose categories have been updated.The email will contain a link to the WhatsApp Manager > Message Templates > Manage Templates panel.Templates whose status will be updated to REJECTED will be updated will have an “information” icon beside their name. Hovering over the icon will display the date when the template will be rejected. Via Webhook A template_category_update webhook will be triggered for each template which will be rejected. Via WhatsApp Manager The WhatsApp Manager > Message Templates > Manage Templates panel will display a banner with a link to a downloadable CSV identifying these templates. Business Support⁠ will list these as well. Notification when action is taken Description Via Email An email will be sent to any people in the business portfolio who have been granted full control of the WABA that owns the templates whose categories have been updated.The email will highlight the number of templates that were rejected, and will include a link to the WhatsApp Manager > Message Templates > Manage Templates panel, where the status will reflect the template is rejected.It also includes a link to Business Support⁠. Via Webhook A status webhook will be triggered for each template that has been rejected. whose category has been updated. The webhook will have the event property set to REJECTED and the reason property set to INCORRECT_CATEGORY. Your options in this process When you receive notice that a template’s category will be updated or a template will be rejected, you can:Create a new templateFor utility templates that will be updated to marketing: You can request a review: If the review is approved – The template’s category will not be updated as previously notified.If the review is not approved – The template will be updated to marketing, as previously notified.For marketing or utility templates that will be rejected: You cannot request a review.Businesses on Cloud API can browse the template library to identify available options for your identity verification use case. It is recommended that businesses browse, choose and create a new template from the template library before the utility/marketing template is rejected, to avoid workflow disruptions. You have 60 days to review and appeal these changes in Business Support Home⁠. Learn which template(s) will be updated or have been updated Via API You can use the endpoint to get the list of templates that have been or will be updated. Request the category and correct_category fields, which will return the IDs of all of the WABA’s templates, and each template’s category and correct_category values. You can then compare these values:If the values match (for example, they are both MARKETING), the template’s category has already been updated with the correct_category value.If they mismatch and the correct_category is not an empty string or null (for example, category is UTILITY but correct_category is MARKETING), the template’s category will be updated on the first day of the next month with the correct_category value.If the correct_category value is an empty string or null, the template has not been impacted. Via WhatsApp Manager The WhatsApp Manager’s Manage Templates panel identifies any templates whose categories will be updated. How to update a template category or request a category review This process has been in effect since June 2023, when the marketing, utility and authentication template categories were introduced. Edit your template’s category Via API You can edit template content or just its category.The template will undergo category validation and template review again.If the template passes validation and review, its category will be updated and a template_category_update webhook will be triggered. Via WhatsApp Manager On the Manage Templates tab:Select your templateEdit the content so it aligns to the guidelines of that categoryRe-submit the template for approval Qualifications and outcomes for category review You can request Meta to review the category of your template if:It is categorized as UTILITY or MARKETING and status is REJECTEDIt is categorized as MARKETING and status is APPROVED Possible outcomes after you submit a request of your template’s category:Review is rejected – The category will not change. How to request a category review A review can only be requested via WhatsApp Manager. In the sidebar of WhatsApp Manager, select the Message Templates dropdown, and then Message Templates. You should see a rejection banner with the template in question. Click Go to Business Support. Click Template Category Updates, select the templates you would like reviewed and then click the Request Review button to begin the review process. How to view templates submitted for review In the Business Support sidebar, click Template category Updates, and then the In review tab. How to view template category decisions If the template category change is not approved: The template can be viewed in Business Support under the Template category updates > Unchanged tab. The template’s category will change to the correct category during an automatic category update. If the template category change is approved: the template can be viewed in Business Support under the Template category updates > Reversed tab. If the template category was already changed during automatic category update, it will be reverted to its previous category. Restrictions on businesses misusing the template categorization system How it works Written notice is provided before businesses are restricted from using the WhatsApp Business Platform for utility messaging in the following way:Warning – If a business is detected to be misusing the template categorization system to secure the utility category for templates that should be categorized as marketing, a written warning will be sent before the business is restricted from using utility messaging on the WhatsApp Business Platform. As of April 16 2025 — After you are given a warning:A 24 hour notice will not be provided before changing template categories from UTILITY to MARKETINGCategory changes will be instantRestriction – If misuse is detected after this warning, the following restrictions will be introduced which would prevent the WhatsApp Business Account from using the WhatsApp Business Platform for utility messaging for 7 days: As of April 16 2025 — Previously approved UTILITY templates will no longer be rejected. Instead, they will be re-categorized as MARKETINGFor 7 days – Disable category reviews for these templatesFor 7 days – Disable creation of new utility templates For businesses that have been restricted previously — If continued misuse of the template categorization system is detected, these restrictions might be re-introduced for 30 days. Notices when action is taken The following notices are triggered: Warnings – Email is sent to all WhatsApp Business Account admins (people with Full control of the WhatsApp Business Account). An account_update webhook will be sent out indicating utility restriction WARN for the WhatsApp Business Account. Restrictions – When restrictions are introduced or lifted, email is sent to all WhatsApp Business Account admins (people with Full control of the WhatsApp Business Account). A change to the restriction_info object in the account_update webhook is also triggered. Your options in this process Businesses that believe these restrictions have been applied in error can request a review via Business Support⁠. Template components | Developer Documentation Template components Updated: Nov 21, 2025 Templates are made up of four primary components which you define when you create a template: header, body, footer, and buttons. The components you choose for each of your templates should be based on your business needs. The only required component is the body component. Some components support variables, whose values you can supply when using the Cloud API to send the template in a template message. If your templates use variables, you must include sample variable values upon template creation. Text header Text headers are optional elements that can be added to the top of template messages. Each template may include only one text header. Please note that markdown special characters are not supported in this component, so we recommend avoiding their use. Text headers support 1 parameter. Creation syntax Creation parameters Placeholder Description Example Value String Required. Header body text string. Supports 1 parameter. If this string contains a parameter, you must include the example property and example parameter value. Maximum 60 characters. Our new sale starts {{sale_start_date}}! String Required if using a named parameter. Named parameter name. {{sale_start_date}} String Required if using a parameter. Parameter example value. December 1st Media header Media headers can be an image, video, gif, or a document such as a PDF. All media must be uploaded with the Resumable Upload API. The syntax for defining a media header is the same for all media types. Note: Gifs are currently only available for Marketing Messages API for WhatsApp. Gifs are mp4 files with a max size of 3.5MB and larger files will be displayed as video messages. Creation syntax Creation parameters Placeholder Description Example Value Indicates media asset type. Set to IMAGE, VIDEO, GIF, or DOCUMENT. IMAGE Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle. 4::aW... Location header Location headers appear as generic maps at the top of the template and are useful for order tracking, delivery updates, ride-hailing pickup/dropoff, locating physical stores, etc. When tapped, the app user's default map app will open and load the specified location. Locations are specified when you send the template. Location headers can only be used in templates categorized as UTILITY or MARKETING. Real-time locations are not supported. Creation syntax Creation parameters None. Send syntax Send parameters Placeholder Description Sample Value Location address. 101 Forest Ave, Palo Alto, CA 94301 Location latitude in decimal degrees. 37.44211676562361 Location longitude in decimal degrees. 122.16155960083124 Location name. Philz Coffee Body The body component represents the core text of your message template and is a text-only template component. Templates are limited to one body component. The message text in the body component accepts multiple parameters. Creation syntax Creation parameters Placeholder Description Example Value String Required. Body text string. Supports multiple parameters. Maximum of 1024 characters. Thank you, {{first_name}}! Your order number is {{order_number}}. String Required if using a named parameter. Named parameter name. {{order_number}} String Required if using a parameter. Parameter example value. December 1st Footer Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component. Properties Placeholder Description Example Value Text to appear in template footer when sent. 60 characters maximum. Use the buttons below to manage your marketing subscriptions Buttons Buttons are optional interactive components that perform specific actions when tapped. Templates can have a combination of up to 10 button components in total, although there are limits to individual buttons of the same type as well as combination limits, which are described below. In addition, templates composed of 4 or more buttons, or a quick reply button and one or more buttons of another type, cannot be viewed on WhatsApp desktop clients. WhatsApp users who receive one of these template messages will be prompted to view the message on a phone instead. Buttons are defined within a single buttons component object, packed into a single buttons array. For example, this template uses a voice call button and a URL button: If a template has more than three buttons, two buttons will appear in the delivered message, and the remaining buttons will be replaced with a See all options button. Tapping the See all options button reveals the remaining buttons. Copy code buttons Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button. Properties Placeholder Description Example Value String to be copied to the device's clipboard when tapped by the app user. Maximum 15 characters. 250FF Multi-product message buttons Multi-product message buttons are special, non-customizable buttons that, when tapped, display up to 30 products from your ecommerce catalog, organized in up to 10 sections, in a single message. See Multi-Product Message Templates. One-time password buttons One-time password buttons are a special type of URL button component used with authentication templates. See Authentication Templates. Voice call buttons Voice call buttons make a WhatsApp call to the business when tapped by the app user. See Create and send WhatsApp call button template message to learn more Phone number buttons Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button. Properties Placeholder Description Example Value Alphanumeric string. Business phone number to be called when the user taps the button. Note that some countries have special phone numbers that have leading zeros after the country calling code (for example, +55-0-955-585-95436). If you assign one of these numbers to the button, the leading zero will be stripped from the number. If your number will not work without the leading zero, assign an alternate number to the button, or add the number as message body text. 20 characters maximum. 15550051310 Button label text. 25 characters maximum. Call Quick reply buttons Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. A common use case is a button that allows your customer to easily opt-out of any marketing messages. Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, the API will return an error indicating an invalid combination. Examples of valid groupings:Quick Reply, Quick ReplyQuick Reply, Quick Reply, URL, PhoneURL, Phone, Quick Reply, Quick Reply Examples of invalid groupings:Quick Reply, URL, Quick ReplyURL, Quick Reply, URL When using the API to send a template that has multiple quick reply buttons, you can use the index property to designate the order in which buttons appear in the template message. Properties Placeholder Description Example Value Button label text. 25 characters maximum. Unsubscribe SPM buttons Single-product message (SPM) buttons are special, non-customizable buttons that can be mapped to a product in your product catalog. When tapped, they load details about the product, which it pulls from your catalog. Users can then add the product to their cart and place an order. See Single-Product Message Templates and Product Card Carousel Templates. URL buttons URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons. Properties Placeholder Description Example Value URL of website. Supports 1 variable. If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the button. 2000 characters maximum. https://www.luckyshrub.com/shop?promo=summer2023 Button label text. 25 characters maximum. Shop Now URL of website that loads in the device's default mobile web browser when the button is tapped by the app user. Supports 1 variable, appended to the end of the URL string. 2000 characters maximum. https://www.luckyshrub.com/shop?promo={{1}} Limited-time offer Limited-Time Offer components are special components used to create limited-time offer templates. Template Library | Developer Documentation Template Library Updated: Nov 14, 2025 Template Library makes it faster and easier for businesses to create utility templates for common use cases, like payment reminders, delivery updates - and authentication templates for common identity verification use cases. These pre-written templates have already been categorized as utility or authentication. Library templates contain fixed content that cannot be edited and parameters you can adapt for business or user-specific information. You can browse and create templates using Template Library in WhatsApp Manager, or programmatically via the API. Creating Templates via WhatsApp Manager (WAM) Follow the instructions below to create templates using the Template Library in WhatsApp Manager?. 1: In the sidebar of WAM, under Message Templates, select Create Template. 2: Under Browse the WhatsApp Template Library, select Browse Templates. 3: You will now see all currently available templates. Use the search bar to search by topic or use case, or use the dropdown options on the sidebar to filter the results. Note that hovering over a template will show you its parameter values. 4: To create a template, select one by clicking on it. Then, add your template name, select the language, and fill out the button details. Once you have completed these steps, click Submit. Note: If you choose Customize template, your template will have to go through review before you are able to send messages. Template Parameters and Restrictions When a template contains the value library_template_name in the GET /message_templates?name= response, it is a template created from the Template Library and is subject to type checks and restrictions. Templates in the library contain both fixed content and parameters. The parameters represent spaces in the template where variable information can be inserted, such as names, addresses, and phone numbers. In the example above, parameters like the name Jim or the business name CS Mutual can be modified to accept variables like your customer's name and your business's name. Messages sent using templates from Template Library are subject to parameter checks during send time. Values used in parameters that are outside of the established ranges listed below will cause the message send to fail. List of parameters and sample values All parameters are length restricted. If you receive an error, try again with a shorter value. Parameter Type Description Sample Value ADDRESS A location address. Must be a valid address 1 Hacker Way, Menlo Park, CA 94025 TEXT Basic text. regarding your order. 12 pack of paper towels your request purchase Jasper's Market AMOUNT A number signifying a quantity. May contain a prefix or suffix for monetary values such as USD or RSMay contain decimals (.) and commas (,)May contain valid currency symbols such as $ and ? 145 USD $375.32 ?1,376.22 EUR RS 1200 DATE A standard calendar date. 2021-04-19 13/03/2021 5th January 1982 08.22.1991 January 1st, 2024 05 12 2022 PHONE NUMBER A telephone number. May contain numbers, spaces, dashes (-), parentheses, and plus symbols (+) +1 4256789900 +91-7884-789122 +39 87 62232 EMAIL A standard email address. Must be a valid email address 1hackerway@meta.com yourcustomername@gmail.com abusinessorcustomername@hotmail.com NUMBER A number. Must be a number.Cannot contain spaces. 23444 90001234921388904 453638 Sending Template Messages To learn how to send templated messages, view the Send Templates guide Template management | Developer Documentation Template management Updated: Nov 14, 2025 Learn about common endpoints used to manage templates. Edit templates LimitationsOnly templates with an APPROVED, REJECTED, or PAUSED status can be edited.You can only edit a template's category, components, or time-to-live.You cannot edit individual template components; all components will be replaced with the components in the edit request payload.You cannot edit the category of an approved template.Approved templates can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window. Rejected or paused templates can be edited an unlimited number of times.After editing an approved or paused template, it will automatically be approved unless it fails template review. Delete templates LimitationsIf you delete a template that has been sent in a template message but has yet to be delivered (e.g. because the customer's phone is turned off), the template's status will be set to PENDING_DELETION and we will attempt to deliver the message for 30 days.If you delete an approved template, you cannot create a new template with the same name for 30 days.Templates that are in a disabled status cannot be deleted. Delete template by name Deleting a template by name deletes all templates that match that name (meaning templates with the same name but different languages will also be deleted). Delete template by ID To delete a template by ID, include the template's ID along with its name in your request; only the template with the matching template ID will be deleted. Business portfolio pacing | Developer Documentation Business portfolio pacingUpdated: Dec 8, 2025This feature is being released gradually over the coming weeks so may not apply to you immediately.Business portfolio pacing is a template message delivery batching mechanism that allows time to gather feedback on any template sent as part of a large-scale messaging campaign.Note that business portfolio pacing is different from template pacing, which only affects marketing and utility templates.Business portfolio pacing applies to: business portfolios that have sent less than 500K template messages collectively, across all of their business phone numbers, within a moving 365-day lookback periodbusiness portfolios that are currently being monitored for suspicious activity (for example, for violating our WhatsApp Business Messaging Policy⁠ or WhatsApp Messaging Guidelines⁠)If pacing applies to your business portfolio and you attempt to send a large number of templates within a short period of time using any of your portfolio’s business phone numbers: an initial set of messages will be processed normallysubsequent messages will be held, and the message_status property in API responses will be set to held_for_quality_assessmentWe will then deliver messages in batches, monitoring feedback before releasing each new batch. If feedback suggests suspicious activity, all remaining held messages will be dropped, and a status messages webhook with status set to failed and code set to 132015 will be triggered for each dropped message. Portfolio admins will be informed of dropped messages by Meta Business Suite notification, WhatsApp Manager banner, and email.In addition, the business portfolio will be prevented from sending or creating templates while it undergoes further review. If messaging activity has been found to violate our policies or guidelines, it may be fully disabled completely. Portfolio admins will be notified of any enforcement actions and will have the option to appeal any decisions. Template pacing | Developer Documentation Template pacing Updated: Dec 8, 2025 Template pacing is a mechanism that allows time for customers to provide early feedback on templates. This identifies and pauses templates that have received poor feedback or engagement, giving you enough time to adjust their contents before they are sent to too many customers, thereby reducing the likelihood of negative feedback impacting your business. Template pacing is valid for marketing and utility templates. Newly created templates, paused templates that are unpaused, and templates that may have been created previously but don’t have a GREEN quality rating are potentially subject to pacing. Template quality history — for example, low quality resulting in a template pause — is one of the primary reasons for template pacing and you may see other templates get paced. When a template is paced, messages will be sent normally until an unspecified threshold is reached. Once this threshold is reached, subsequent messages using that template will be held to allow enough time for customer feedback. Once we receive a good quality signal, subsequent messages using that template will be scaled to the entire target audience. If we receive a bad quality signal, subsequent messages using that template will be dropped, giving you the opportunity to adjust content, targeting, etc. Utility template pacing Utility templates are subject to pacing only if you have had a utility template paused. Once a utility template has been paused, newly created templates, paused templates that are unpaused, and templates that may have been created previously but don’t have GREEN quality rating are potentially subject to pacing for the next 7 days. API Behavior The immediate response from the messages endpoint will indicate if the message was sent or held with the new message_status property in the messages object. This response will be available on all versions of the API.Cloud API will always include a message_status property that will have a value of accepted for messages that are processed, and held_for_quality_assessment for messages that are held. Messages that are accepted will trigger the sent and delivered webhooks when they are actually sent (this is the same behavior that existed before pacing). A full example response can be found in the Cloud API docs. If the feedback is positive and changes the template’s quality rating to high quality, the held messages will be released and sent normally. The message_template_quality_update will send the quality update and the messages webhook will send the sent and delivered updates. If the feedback is negative and changes the template’s quality to low quality:The template’s status will be set to PAUSEDA message_template_status_update will be sent with an event value of pausedEach held message will be dropped and trigger a messages webhook with and (Cloud API users).A message_template_quality_update webhook will be triggered with the quality changeAdmins of the WhatsApp Business Account owning business will be informed of the dropped messages by Meta Business Suite notification, WhatsApp Manager banner, and email See Template Pausing to learn how to unpause a template that has been paused due to pacing. Note that we have internal guardrails in place to ensure that we evaluate and make a pacing decision within a reasonable time to avoid impact on time sensitive campaigns. Our goal is that even if paced, campaign messages with highest throughput still get delivered within an hour (99 percentile). Thus, if our internal guardrails are reached before a template has received enough feedback to change its quality to high or low, the held messages will be released normally along with any appropriate messages webhooks. Template pausing | Developer Documentation Template pausingUpdated: Oct 22, 2025If a message template reaches the lowest quality rating (a status of Active - Low quality in WhatsApp Manager, or a quality_score of RED via API), it will automatically be paused for a period of time to protect the quality rating of phone numbers that have used the template. Pausing durations are as follows: 1st Instance: Paused for 3 hours2nd Instance: Paused for 6 hours3rd Instance: DisabledWhen a message template is paused (status of Paused) it can’t be sent to customers, so you should halt any automated messaging campaigns that rely on that template. Although you won’t be charged for attempting to send a paused message template to a customer, and the attempt won’t count against your messaging limit, the API will reject these attempts anyway. You should only resume these campaigns when the template’s status has been set to Active again.You may wish to edit a paused template if you feel that editing its content will reduce the amount of negative feedback it may receive and increase user engagement. Keep in mind, however, that once you edit a message template and resubmit it for approval, its status will change to In Review and it can’t be sent to customers again until it has been re-approved and its status set to Active.You may also wish to make changes to your business logic (targeting, delivery parameters, etc.) if you feel it is contributing to negative feedback or low engagement.Pausing will initially not impact the business phone number from which the message template was sent. Other high quality message templates can continue to be sent from the phone number. However, if a business consistently sends message templates that reach a Low quality status, the phone number may eventually be impacted. Pause NotificationsWhen a message template has been paused we will notify you by WhatsApp Manager notification, email, and a message_template_status_update webhook will be triggered. UnpausingA template will unpause on its own after satisfying the pause duration outlined above. Once unpaused, the template’s status will be set to Active and you may begin sending it to customers again. If you didn’t halt any automated messaging campaigns that relied on a paused template, they should start working again. However, we recommend that you halt any campaigns that rely on a template that has been paused until it is unpaused, because our APIs will reject your requests anyway.The template’s quality rating will also be reset to a value based on the most recent customer feedback the template has received.Similar to pause notifications, we will notify you by WhatsApp Manager notification, email, and webhook once the template’s status has been set to Active.Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.With the introduction of Template Pacing, we’re also introducing the ability to unpause any paused template through: The API by making a POST request to /{whats_app_message_template_id}/unpauseWhatsApp Manager by clicking the manually unpause it link highlighted in the screenshots below.Note that templates paused during Template Pacing must be manually unpaused (API or WhatsApp Manager) before they can be used again. AppealsIf your submission is rejected you may file an appeal. Note that appeals must include a sample. If an approved template has become disabled, you may also edit it and resubmit it for approval.In the WhatsApp Manager: Mouseover the suitcase icon (Account tools) and click Message templates.If you have multiple WhatsApp Business Accounts, use the dropdown menu in the top-right corner to select the account whose templates you want to manage.Find the message template that you would like to edit and click it.Edit the template’s contents.Click the Add Sample button and add sample variable values and images.Click Submit.The appeal will be reviewed and a decision made within 24 hours. Per-user marketing template message limits | Developer Documentation Per-user marketing template message limitsUpdated: Feb 26, 2026Upcoming changesStarting March 3, 2025, we will take into account the overall volume of personal and business messages in a user’s inbox in addition to their recent marketing message read rates when determining if a given WhatsApp user should receive fewer marketing template messages, and what their limit should be. This means that if a person has low inbox activity or they have not engaged with many of the marketing messages they received lately they may receive fewer marketing messages to ensure a healthy balance of messages in their inbox. From late Q2 we will also align the per user marketing limit with upcoming per-message pricing changes so that all marketing messages delivered will now count towards the per user marketing limit.Starting April 1, 2025, we will temporarily pause delivery of all marketing template messages to WhatsApp users who have a United States phone number (a number composed of a +1 dialing code and a US area code). This pause is intended to allow us to focus on building a better consumer experience in the US, which will ultimately lead to improved outcomes for businesses. Attempting to send a template message to a WhatsApp user with a US phone number after this date will result in an error. What is it?WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time where users are less likely to be receptive and engage with them. This is determined based on a number of factors, including a dynamic view of an individual’s recent marketing message read rate and how many messages they currently have in their inbox from friends, family and businesses.Starting April 1, 2025, to focus on building the consumer experience, WhatsApp will not deliver any marketing template messages to individuals with United States phone numbers (numbers composed of a +1 dialing code and a US area code).Messages sent from a business phone number in the European Economic Area, United Kingdom, Japan, or South Korea, or to a consumer in these countries, will not receive delivery optimizations. Note that per-user marketing message template limits are also not active in these countries, so a lack of delivery optimizations will not have any effect on message delivery. Why is it important?WhatsApp has found that per-user marketing template limits maximize marketing message engagement and improve the user experience, measured through improvements in user read rates and sentiment. This limit helps WhatsApp users find business messaging more valuable and feel less like they receive too many business messages. How this Applies to Your BusinessOur per user marketing limit adapts automatically over time based on a person’s recent engagement levels. While this may mean delivering fewer messages to some users during periods of lower marketing read rates or overall inbox activity, rest assured your ability to reach people when they are most engaged will not change. Aligning per-user marketing limits with upcoming per message pricing changesGradually rolling out from late Q2 2025, the per user marketing limit will align with upcoming per-message pricing changes. Previously, the limit only applied to marketing template messages that would normally open a new marketing conversation, and businesses could send one additional marketing template message if a marketing conversation is already open between you and a WhatsApp user.Now businesses will be able to send an unlimited number of marketing messages, however each message delivered will now count towards the per user marketing limit. One exception is, if a person responds to a marketing message it will start a 24h customer service window. Marketing messages sent within this window will not count towards a person’s limit. How we notify via error codeIf a marketing template message is not sent due to per-user marketing template limit enforcement, a messages webhook will be triggered with status set to failed and (error) code set to 131049 (for Cloud API).If you do receive this error code and suspect it is due to the limit, wait at least 24 hours before 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.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. Template quality rating | Developer Documentation Template quality rating Updated: Oct 29, 2025 Every template has a quality rating based on usage, customer feedback, and engagement. Templates can have the following ratings, as reported by the API: GREEN - Indicates high quality. The template has received little to no negative feedback from WhatsApp users. The template can be sent. YELLOW - Indicates medium quality. The template has received negative feedback from multiple WhatsApp users, or low read-rates, and may soon become paused or disabled. Message templates with this status can still be sent. RED - Indicates low quality. The template has received negative feedback from multiple WhatsApp users, or low read-rates. The template can be sent, but is in danger of being paused or disabled soon. We recommend that you address the issues that users are reporting. are reporting. UNKNOWN - Indicates a quality score is still pending, because it has yet to receive WhatsApp user feedback or read-rate data. The template can be sent. Newly created templates have a quality score of UNKNOWN, but their rating will change automatically as usage, feedback, and engagement signal is collected over time. Quality ratings factor into template pacing and template pausing, which can affect template delivery. If a template continuously receives negative feedback or low engagement, it can eventually affect the template's status. If the status changes to anything other than APPROVED, the template cannot be sent in template messages unless its APPROVED status is restored. Get template quality rating via WhatsApp Manager The Manage templates? panel in WhatsApp Manager also displays template quality ratings for templates that have an approved status: Active - Quality pending (equates to an UNKNOWN quality score)Active - High quality (equates to a GREEN quality score)Active - Medium quality (equates to a YELLOW quality score)Active - Low quality (equates to a RED quality score) See also About your WhatsApp Business message template's quality rating? Template review | Developer Documentation Template reviewUpdated: Oct 31, 2025Cloud API reviews templates and variable parameters using machine learning to protect the security and integrity of Cloud API services. When Cloud API reviews templates and variable text, no information is shared with WhatsApp.When you submit a template creation request, the content undergoes validation through a combination of automated systems and manual reviews. This process ensures that the template complies with WhatsApp’s policies and quality standards. Templates that contain spam, scam-like content, or violate WhatsApp policies are rejected during this review process. Approval processOnce you have created your template you can submit it for approval. It can take up to 24 hours for an approval decision to be made. Once a decision has been made, a notification will appear in your WhatsApp Manager and we will send an email to your Business Manager admins. In addition, we will send a message_template_status_change webhook.If your message template is approved, its status will be set to Active - Quality pending ( APPROVED in the API) and you can begin sending it to customers. If it is rejected, you can edit it and resubmit for approval, or appeal the decision. SamplesIf your template uses variables you must include sample variable values (media assets, text strings, etc.) with your submission. This makes it easier for us to visualize how your template will appear to customers.To include a sample with your submission in the WhatsApp Manager, first create your template, adding any variables that it requires, then click the Add Sample button. The preview pane will render any sample media assets or sample text values you provide. Common rejection reasonsSubmissions are commonly rejected for the following reasons, so make sure you avoid these mistakes. Parameter formatting Variable parameters are missing or have mismatched curly braces. The correct format is {{1}} for positional parameters .Variable parameters contain special characters such as a #, $, or %.Variable parameters are not sequential. For example, {{1}}, {{2}}, {{5}}, {{4}}.The template contains too many variable parameters relative to the message length. You need to decrease the number of variable parameters or increase the message length.The message template cannot start or end with a parameter i.e. dangling parameters are not allowed. Content and Policy Violations The message template contains content that violates WhatsApp’s Commerce Policy: When you offer goods or services for sale, we consider all messages and media related to your goods or services, including any descriptions, prices, fees, taxes and/or any required legal disclosures, to constitute transactions. Transactions must comply with the WhatsApp Commerce Policy.The message template contains content that violates the WhatsApps Business Policy: Do not request sensitive identifiers from users. For example, do not ask people to share full length individual payment card numbers, financial account numbers, National Identification numbers, or other sensitive identifiers. This also includes not requesting documents from users that might contain sensitive identifiers. Requesting partial identifiers (ex: last 4 digits of their Social Security number) is OK.The content contains potentially abusive or threatening content, such as threatening a customer with legal action or threatening to publicly shame them. Character limits and text formatThe body component will have different character limits depending on the format and tag of the template. The number of emojis allowed in the body component may also be limited. DuplicationThe message template is a duplicate of an existing template. If a template is submitted with the same wording in the body and footer of an existing template, the duplicate template will be rejected. Rejection NotificationsA rejection notification that includes the rejection reason will appear in Business Support Home. You can view rejections in the Business Support Home by navigating to Account Overview > View my accounts (button) > (your Meta Business Account) > (your WABA) > Rejected message templates.Rejection info will also be sent via email.You can refer to the Business Support Home notification to see the name and language of the existing template with the same content as the rejected duplicate template. You may also choose to edit the template and resubmit.Note: This check does not apply to templates categorized as AUTHENTICATION. AppealsIf your submission is rejected you may file an appeal. Note that appeals must include a sample. If an approved template has become disabled, you may also edit it and resubmit it for approval. In the WhatsApp Manager: Mouseover the suitcase icon (Account tools) and click Message templates. If you have multiple WhatsApp Business Accounts, use the dropdown menu in the top-right corner to select the account whose templates you want to manage.Find the message template that you would like to edit and click it.Edit the template’s contents.Click the Add Sample button and add sample variable values and images.Click Submit.The appeal will be reviewed and a decision made within 24 hours. Template review webhooksYou can receive updates via the message_template_status_update webhook, which notifies whether a template is approved, pending, or rejected.If your template is rejected and you disagree with the decision, you have the option to submit an appeal for reconsideration. Tap target title URL override | Developer Documentation Tap target title URL override Updated: Nov 13, 2025 This document explains how to send approved message templates using the tap_target_configuration component within a template message. Tap target override enables image-based, text-based, and header-less message templates to function as interactive Call-to-Action URL buttons. These buttons display a custom title and open the destination linked to the first URL button. WhatsApp Business Accounts (WABAs) must be fully verified and consistently maintain high-quality standards to ensure compliance and access to this component. Configure message time-to-live | Developer Documentation Configure message time-to-live Updated: Feb 27, 2026 If a message cannot be delivered to a WhatsApp user, delivery is retried for a period of time known as time-to-live (“TTL”), or the message validity period. You can customize the default TTL for authentication and utility templates sent via Cloud API, and for marketing templates sent via Marketing Messages API for WhatsApp. Set a TTL for all authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Defaults, min/max values, and compatibility table Authentication Utility Marketing Default TTL 10 minutes 30 days for authentication templates created before October 23, 2024 30 days 30 days Compatibility Cloud API Cloud API only Marketing Messages API for WhatsApp Customizable range 30 seconds to 15 minutes 30 seconds to 12 hours 12 hours to 30 days Template groups | Developer Documentation Template groups Updated: Feb 27, 2026 This document describes how to create, manage, and measure template groups. Template groups allow you to associate a set of templates so it's easier to track their performance as a set when querying template metrics. Limitations a template can only be a part of a single template group at a timetemplate group names must be uniqueremoving a template from a template group does not remove any template metrics it may have contributed to the group Template group analytics See the Template group analytics document. Template Comparison | Developer Documentation Template Comparison Updated: Nov 14, 2025 You can compare two templates by examining how often each one is sent, which one has the lower ratio of blocks to sends, and each template's top reason for being blocked. Requirements A User or System User access token.The whatsapp_business_management permission. Limitations Only two templates can be compared at a time.Both templates must be in the same WhatsApp Business Account.Templates must have been sent at least 1,000 times in the queries specified timeframe.Lookback windows are limited to 7, 30, 60 and 90 days from the time of the request. Template migration | Developer Documentation Template migration Updated: Nov 14, 2025 This document describes how to migrate templates from one WhatsApp Business Account (WABA) to another. Note that migration doesn't move templates, it recreates them in the destination WABA. LimitationsTemplates can only be migrated between WABAs owned by the same Meta business.Only templates with a status of APPROVED and a quality_score of either GREEN or UNKNOWN are eligible for migration. Throughput Throughput | Developer Documentation Throughput Updated: Nov 21, 2025 For each registered business phone number, Cloud API supports up to 80 messages per second (mps) by default, and up to 1,000 mps by automatic upgrade. Throughput is inclusive of inbound and outbound messages and all message types. Note that business phone numbers, regardless of throughput, are still subject to their WhatsApp Business Account rate limit and template messaging limits. If you attempt to send more messages than your current throughput level allows, the API will return error code 130429 until you are within your allowed level again. Also, throughput levels are intended for messaging campaigns involving different WhatsApp user phone numbers. If you attempt to send too many messages to the same WhatsApp user number, you may encounter a pair rate limit error. WhatsApp Business app phone numbers In order to remain compatible with the WhatsApp Business app, business phone numbers that are in use with both the WhatsApp Business app and Cloud API (“coexistence numbers”) have a fixed throughput of 20 mps. Higher throughput If you meet our eligibility requirements, we will automatically upgrade your business phone number to 1,000 mps at no cost to you. Higher throughput does not incur additional charges or affect pricing. The upgrade process itself can take up to 1 minute. During this time the number will not be usable on our platform. If used in an API request, the API will return error code 131057. Once a business phone number has been upgraded, it will automatically be upgraded for any future throughput increases with no downtime. Once your number is upgraded to higher throughput, a phone_number_quality_update webhook will be triggered with event set to THROUGHPUT_UPGRADE and max_daily_conversations_per_business set to TIER_UNLIMITED. EligibilityThe business portfolio associated with the phone number must have an unlimited messaging limit.The business phone number must be used to message 100K or more unique WhatsApp user phone numbers, outside of a customer service window, within a moving 24-hour period.The business phone number must have a quality_score of YELLOW (shown as a Medium quality rating⁠ in WhatsApp Manager) or higher. Media messages To take full advantage of higher throughput, we recommend that you upload your media assets to our servers and use the returned media IDs, instead of hosting the assets on your own servers and using media asset URLs, when sending messages that include a media asset. If you prefer (or must) host the assets on your own servers, we recommend that you use media caching. Getting throughput level Use the WhatsApp Business Phone Number endpoint to get a phone number’s current throughput level: Typing Indicators Typing indicators | Developer Documentation Typing indicators Updated: Oct 21, 2025 When you get a messages webhook indicating a received message, you can use the message.id value to mark the message as read and display a typing indicator so the WhatsApp user knows you are preparing a response. This is good practice if it will take you a few seconds to respond. The typing indicator will be dismissed once you respond, or after 25 seconds, whichever comes first. To prevent a poor user experience, only display a typing indicator if you are going to respond. Request parameters Placeholder Description Example value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp message ID. This ID is assigned to the messages.id property in received message messages webhooks. wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQjZCMzlEQUE4OTJBMTE4RTUA Upcoming Messaging Limits Changes Upcoming changes to messaging limits | Developer Documentation Upcoming changes to messaging limitsUpdated: Oct 26, 2025The changes described in this document are now live, and are only here for reference purposes. Our Messaging limits document has been updated to reflect these changes.Messaging limits are currently calculated and set on a per-number basis. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio.Existing business portfolios will have their messaging limit set to the highest limit of any phone number within their portfolio (e.g. if a portfolio has a phone number with a limit of 100K and other phone numbers with lower limits, the portfolio’s limit will be set to 100K).These changes will result in: Faster access to higher limits, with upgrades within 6 hours (compared to the current 24 hours) and immediate access to the portfolio’s limits for newly registered numbers.Greater flexibility, allowing you to have as many phones as needed without requiring additional phones to access higher limits, since all phones share the portfolio’s limit.Reduced administrative burden and operational costs, by minimizing the need for unnecessary phone numbers. Changes Before Oct 7th, 2025 Starting Oct 7th, 2025 Where are limits set? On individual business phone numbers.For example, phone number A could have a limit of 10K but phone number B could have a limit of 100K. On individual business portfolios.For example, a portfolio with two business phone numbers could have a limit of 100K, and both phone numbers share the 100K limit. Starting limit for newly created business portfolios Not applicable 250 Starting limit for a newly registered number 250 Shares the messaging limit set on the business portfolio. Limit upon becoming eligible for automatic scaling 1,000 2,000 Time to increase limit via automatic scaling Limit increased 24 hours after meeting criteria. Limit increased 6 hours after meeting criteria. Phone number quality states The Flagged phone number quality⁠ state is possible.If your business phone number quality rating has been set to Flagged for the last 7 days, we will decrease its limit by one level, immediately. The Flagged phone number quality⁠ state is no longer possible.If your business phone number quality rating drops, its messaging limit will not be downgraded. Automatic scaling criteria Your business phone number is connectedYour business phone number quality rating is Medium or High)In the last 7 days, your business has utilized at least half of your current messaging limit You are sending high-quality messages across all of your business phone numbers and templates.In the last 7 days, your business has utilized at least half of your current messaging limit Webhooks business_capability_update webhook: max_daily_conversation_per_phone value indicates business phone numbers’s messaging limit.phone_number_quality_update webhook: current_limit value indicates business phone numbers’s messaging limit or throughput level. business_capability_update webhook: A new max_daily_conversations_per_business parameter will be included, which indicates the business portfolio’s messaging limit ( 2000, 10000, 100000, or UNLIMITED).The existing max_daily_conversation_per_phone parameter will now indicate the business portfolio’s messaging limit (values same as above). The parameter will be removed in February, 2026.phone_number_quality_update webhook: A new max_daily_conversations_per_business parameter will be included that describes the portfolio’s messaging limit (values same as above).The existing current_limit value will now indicate the business portfolio’s messaging limit or the business phone number’s throughput level. The parameter will be removed in February, 2026. Throughput eligibility requirements For a business phone number to become eligible for 1,000 messages per second: The business phone number must be able to initiate an unlimited number of messages in a rolling 24-hour period.The business phone number must have a Medium quality rating⁠ or higher. For a business phone number to become eligible for 1,000 messages per second: The business portfolio associated with the phone number must have an unlimited messaging limit.The business phone number must be used to message 100K or more unique WhatsApp user phone numbers, outside of a customer service window, within a moving 24-hour period.The business phone number must have a Medium quality rating⁠ or higher.If you meet our eligibility requirements, we will automatically upgrade your business phone number to 1,000 mps within 12 hours. Endpoints To get a business phone number’s current messaging limit, request the messaging_limit_tier field on the business phone number. To get a business portfolio’s current messaging limit, request the (new) whatsapp_business_manager_messaging_limit field on the business portfolio, or a WhatsApp Business Account or business phone number within the portfolio.You can request this field directly on any of these resources, or indirectly using field expansion with any endpoints that return business portfolios, WhatsApp Business Accounts, or business phone numbers. WhatsApp Manager changesStarting October 7, 2025, the WhatsApp Manager⁠ > Overview panel’s Limits section will be updated to reflect portfolio-based limits and scaling information: In addition, a new Messaging Limits panel will be added to WhatsApp Manager, displaying your business portfolio’s current limit and scaling information: Upcoming change supportIf you are an Enterprise Developer and run into any issues or have technical questions related to changes mentioned in Messaging limits, please open a Direct Support ticket, using Topic: “WABiz: Account & WABA” and Request Type: “Messaging Limits”. If you have multiple Meta business accounts, be sure to select the appropriate account. Webhooks Webhooks | Developer Documentation Webhooks Updated: Dec 2, 2025 This document describes webhooks and how they are used by the WhatsApp Business Platform. Webhooks are HTTP requests containing JSON payloads that are sent from Meta’s servers to a server of your designation. The WhatsApp Business Platform uses webhooks to inform you of incoming messages, the status of outgoing messages, and other important information, such as changes to your account status, messaging capability upgrades, and changes to your template quality scores. For example, this is a webhook describing a message sent from a WhatsApp user to a business: Create a webhook endpoint To receive webhooks, you must create and configure a webhook endpoint. To create your own endpoint, see our Create a webhook endpoint document If you aren’t ready to create your own endpoint yet, you can create a test webhook endpoint that logs webhook payloads to the console. Note, however, that before you can use your app in a production capacity, you must create your own endpoint. Permissions You will need the following permissions to receive webhooks:whatsapp_business_messaging — for messages webhookswhatsapp_business_management — for all other webhooks If you are a direct developer, use your system user to grant your app these permissions when generating your system token. If you are a solution provider and need these permissions to provide appropriate services to your business customers, you must be approved for advanced access for the permissions via App Review before your business customers will be able to grant your app these permissions during onboarding. Fields Once you created and configured your webhook endpoint (or have set up a test webhook endpoint), use the App Dashboard > WhatsApp > Configuration panel to subscribe to individual webhook fields. Note that if you created your app using the Connect with customers through WhatsApp use case, navigate to App Dashboard > Use cases > Customize > Configuration instead. Field name Description account_alerts The account_alerts webhook notifies you of changes to a business phone number’s messaging limit, business profile, and Official Business Account status. account_review_update The account_review_update webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines. account_update The account_update webhook notifies of changes to a WhatsApp Business Account’s partner-led business verification submission, its authentication-international rate eligibility, or primary business location, when it is shared with a Solution Partner, policy or terms violations, offboarding, reconnection, or when it is deleted. automatic_events The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting. business_capability_update The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.). history The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider. message_template_components_update The message_template_components_update webhook notifies you of changes to a template’s components. message_template_quality_update The message_template_quality_update webhook notifies you of changes to a template’s quality score. message_template_status_update The message_template_status_update webhook notifies you of changes to the status of an existing template. messages The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user. partner_solutions The partner_solutions webhook describes changes to the status of a Multi-Partner Solution. payment_configuration_update The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil. phone_number_name_update The phone_number_name_update webhook notifies you of business phone number display name verification outcomes. phone_number_quality_update The phone_number_quality_update webhook notifies you of changes to a business phone number’s throughput level. security The security webhook notifies you of changes to a business phone number’s security settings. smb_app_state_sync The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider. smb_message_echoes The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider. template_category_update The template_category_update webhook notifies you of changes to template’s category. user_preferences The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences. Override webhooks You can use an alternate webhook endpoint for certain webhook fields for your WhatsApp Business Account (WABA) or business phone number. This can be useful for testing purposes, or if you are a solution provider and wish to use unique webhook endpoints for each of your onboarded customers. See our Webhook overrides document to learn how to override webhooks. Payload size Webhook payloads can be up to 3 MB. Webhook delivery failure If we send a webhook request to your endpoint and your server responds with an HTTP status code other than 200, or if we are unable to deliver the webhook for another reason, we will keep trying with decreasing frequency until the request succeeds, for up to 7 days. Note that retries will be sent to all apps that have subscribed to webhooks (and their appropriate fields) for the WhatsApp Business Account. This can result in duplicate webhook notifications. Mutual TLS Webhooks support mutual TLS (mTLS) for added security. See Graph API’s mTLS for webhooks document to learn how to enable and use mTLS. IP addresses You can get the IP addresses of our webhook servers by running the following command in your terminal: whois -h whois.radb.net —'-i origin AS32934'| grep '^route'| awk '{print $2}'| sort You can also use our geofeed to download a CSV⁠ that lists our IP addresses. Note, however, that we periodically change our IP addresses, so to avoid having to regenerate your list of allowed IP addresses, we recommend that you use mTLS instead. Troubleshooting If you are not receiving webhooks:Make sure your endpoint is accepting requests.Send a test payload to your endpoint via the App Dashboard > WhatsApp > Configurations panel.Make sure your app is in Live mode; some webhooks will not be sent if your app is in Dev mode.Use our test webhook endpoint. If the test endpoint is digesting webhook payloads and displaying them in the console, the issue is likely with your endpoint code. Learn moreSee our Using Node.js to implement webhooks⁠ WhatsApp Business blog post. Create a webhook endpoint | Developer Documentation Create a webhook endpoint Updated: Nov 7, 2025 Learn about webhook requests and responses so you can set up and configure your own webhook endpoint on a public server. Before you can use your app in a production capacity, you must create and configure your own webhook endpoint on a public server that can accept and respond to GET and POST requests, and that can validate and capture webhook payloads. TLS/SSL Your webhook endpoint server must have a valid TLS or SSL digital security certificate, correctly configured and installed. Self-signed certificates are not supported. mTLS Webhooks support mutual TLS (mTLS) for added security. See Graph API's mTLS for webhooks document to learn how to enable and use mTLS. Note that enabling and disabling mTLS is not supported at the WABA or business phone number level. If you have more than one application accessing the platform, you will need to enable mTLS for each application. GET requests GET requests are used to verify your webhook endpoint. Anytime you set or edit the Callback URL field or the Verify token field in the App Dashboard, Meta will send a GET request to your webhook endpoint. You must validate and respond to this request. Request parameters Placeholder Description Example value Your webhook endpoint URL. Add this URL to the Callback URL field in the App Dashboard when you configure webhooks later. https://www.luckyshrub.com/webhooks A random string that Meta will generate. 1158201444 A verification string of your own choosing. Store this string on your server. Add this string to the Verify token field in the App Dashboard when you configure webhooks later. vibecoding Validation To validate GET requests, compare the hub.verify_token value in the request to the verification string you have stored on your server. If the values match, the request is valid, otherwise it is invalid. Response If the request is valid, respond with HTTP status 200 and the hub.challenge value. If the request is invalid, respond with a 400-level HTTP status code, or anything other than status 200. When you configure webhooks, Meta will send a GET request to your webhook endpoint. If it returns status 200 and the hub.challenge value included in the request, Meta will consider your webhook endpoint verified, and begin sending you webhooks. If your webhook endpoint responds with anything else, however, Meta will consider your webhook endpoint unverified, and webhooks will not be sent to your endpoint. Configure webhooks Once you have created your webhook endpoint, navigate to the App Dashboard > WhatsApp > Configuration panel, and add your webhook endpoint URL to the Callback URL field, and your verification string to Verify token field. Note that if you created your app using the Connect with customers through WhatsApp use case, navigate to App Dashboard > Use cases > Customize > Configuration instead. If your webhook endpoint is responding to webhook verification GET requests properly, the panel will save your changes, and a list of fields you can subscribe to will appear. You can then subscribe to any fields that fulfill your business needs. Note that you can use the POST Application Subscriptions endpoint to configure webhooks as an alternative method, but it requires the use of an app token. See Graph API's Subscriptions edge document to learn how to do this, and use whatsapp_business_account as the object value. Create a test webhook endpoint | Developer Documentation Create a test webhook endpoint Updated: Nov 7, 2025 If you aren’t ready to create your own webhook endpoint yet, you can deploy a test webhook app on Render.com⁠ that accepts webhook requests and dumps their contents to Render’s console. Only use this app for testing purposes. Requirements A Render⁠ account.A GitHub⁠ account. Step 1: Create a GitHub repository Sign into your GitHub account and create a new repo (public or private) with a name of your choice. Within the repo, create an app.js file and paste this code into it: Step 2: Deploy a Node Express app on Render Follow Render’s instructions for deploying a Node Express app⁠, with these differences: Skip step 1Use these settings for step 3: Build command: npm install expressStart command: node app.jsIn the Environment Variables section, add the variable VERIFY_TOKEN and set it to a string of your choice (e.g. vibecode). When you’re done, click the Deploy your web service button. This will take you to the app log where you will see your app being built, which can take a few minutes. You’ll know it’s done when you see “Your service is live” in the log. Copy your deployed test webhook app URL, which is displayed at the top of the page under your GitHub repo name. (If you view the URL, you’ll get a 403 error, which is expected). Step 3: Add your test webhook app URL to your Meta app Open a new window/tab, and navigate to the (Meta) App Dashboard > WhatsApp > Webhooks > Configuration panel. Paste your test webhook app URL in the Callback URL field, and add the VERIFY_TOKEN environment variable string you set earlier to the Verify token field, then click Verify and save. If verification is successful, the Meta app dashboard should refresh and you should see a list of webhook fields you can subscribe to. Subscribe to the messages webhook field if you haven’t already. Also, in Render’s app log, if you see “WEBHOOK VERIFIED”, your test webhook app URL has been successfully verified. Step 4: Send a test message Back in the Meta app dashboard Configuration panel, scroll down to the messages webhook field, subscribe to the field if you haven’t already, then click the Test link. This will send a test message to your test webhook app. Confirm that it appears in Render app log with “Webhook received” followed by a test JSON payload: Troubleshooting If the test messages webhook doesn’t appear in the Render app dashboard log: Confirm that you successfully added your test webhook app URL to your Meta app (Step 3).Confirm that your app is subscribed to the messages webhook field.Make sure you are sending a messages test webhook; some test webhooks only work when your app is in Live mode, while others only work in Development mode (messages test webhooks work in both modes). business_capability_update webhook reference | Developer Documentation business_capability_update webhook reference Updated: Nov 14, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account business_capability_update webhook. The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.). TriggersA WhatsApp Business Account is created.A WhatsApp Business Account or business portfolio business capability (e.g. messaging limits, phone number limits) is increased or decreased. Parameters Placeholder Description Example value Integer This parameter will be removed in February, 2026. Use max_daily_conversations_per_business instead. Business portfolio's messaging limit. Values can be: 250 2000 10000 100000 -1 A value of -1 indicates unlimited messaging. 2000 Integer Business portfolio's messaging limit. Value can be: TIER_250 TIER_2K TIER_10K TIER_100K TIER_UNLIMITED TIER_UNLIMITED Integer Maximum number of business phone numbers the business portfolio can have. This property is only included if max_daily_conversation_per_phone is set to 250. 2 Integer Maximum number of business phone numbers allowed per WABA. This property is only included if max_daily_conversation_per_phone is not set to 250. 25 Integer Unix timestamp indicating when the webhook was triggered. 1739321024 String WhatsApp Business Account ID. 102290129340398 history webhook reference | Developer Documentation history webhook reference Updated: Dec 12, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account history webhook. The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider. Triggersa solution provider synchronize the WhatsApp Business app chat history of a business customer who they have onboarded with a WhatsApp Business app phone number, and who has agreed to share their chat historya solution provider synchronize the WhatsApp Business app chat history of a business customer who they have onboarded with a WhatsApp Business app phone number, but the customer has declined to share their chat history Chat history sharing approved Chat history contents If the business customer has already approved chat history sharing when the solution provider requests the business's chat history, a series of history webhooks will be triggered, describing all messages sent or received within 180 days of the time when the business was onboarded onto Cloud API.Messages that are part of a group chat will not be included.Media messages will not include media asset IDs. Instead, additional history webhooks containing media message asset IDs will be sent separately, but only for media messages sent within 14 days of onboarding. Note that for efficiency purposes, a single webhook could potentially describe thousands of messages, so we recommend that you capture its contents first, then process the contents asynchronously. Phases and chunks Webhooks are divided into three history phases, where day 0 indicates the time when the business was onboarded onto Cloud API:phase 0: day 0 through day 1phase 1: day 1 through day 90phase 2: day 90 through day 180 For each phase, chat history webhooks may be sent in separate chunks, depending on the total number of messages that comprise the thread.You can use the chunk_order parameter value to arrange these chunks in their sequential order, as they may not be delivered sequentially.You can use the phase parameter value to monitor phase progress. A value of 2 indicates that the current phase is complete.You can use the progress parameter value to monitor the overall progress. A value of 100 indicates that synchronization is complete. If there is no chat history available for a given phase, no corresponding webhooks will be sent. Parameters Placeholder Description Example value String The business customer's phone number, or the WhatsApp user's phone number. If the value is the business's phone number, the message object describes a message sent by the business to a WhatsApp user. If the value is the WhatsApp user's phone number, the message object describes a message sent by the WhatsApp user to the business. 15550783881 Integer Indicates chunk number, which you can use to order sets of webhooks sequentially. 1 String The business customer's WhatsApp Business Account ID. 102290129340398 String The business customer's business phone number. 15550783881 String The business customer's business phone number ID. 106540352242922 String Unix timestamp indicating when the message was received by the recipient's device. 1738796547 Object An object describing the message's contents. This value will vary based on the message type, as well as the contents message. For example, if a business sends an image message without a caption, the object would not include the caption property. See Sending messages for examples of payloads for each message type. String Indicates the message's most recent delivery stats. Values can be: DELIVERED ERROR PENDING PLAYED READ SENT READ String Message type. Note that this placeholder appears twice in the syntax above, as it serves as a placeholder for the type property's value and its matching property name. See the example payload below for a thread with various message types. If this value is set to media_placeholder, the message object describes a message that contained a media asset. In this case, the message contents will be omitted. Instead, a separate history webhook will follow, describing the content of the message and the media asset ID, but only if the message was sent within the last two weeks of your query. See the example payloads below describing a media message's contents. text Integer Indicates history phase. Values can be: 0 - indicates messages are from day 0 (business onboarding time) through day 1 1 - indicates messages are from day 1 through day 90 2 - indicates messages are from day 90 through day 180 1 Integer Indicates percentage total of synchronization progress. Minimum 0, maximum 100. 55 String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= String The WhatsApp user's phone number. The to property is only included if the message object represents an SMB message echo. 16505551234 Chat history sharing declined Parameters Placeholder Description Example value String The business customer's business phone number. 15550783881 String The business customer's business phone number ID. 106540352242922 message_template_components_update webhook reference | Developer Documentation message_template_components_update webhook reference Updated: Nov 14, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account message_template_components_update webhook. The message_template_components_update webhook notifies you of changes to a template's components. Triggers A template is edited. Parameters Placeholder Description Example value String Button label text. Email support String Button phone number. +15550783881 String Button type. Values can include: CATALOG COPY_CODE EXTENSION FLOW, MPM ORDER_DETAILS OTP PHONE_NUMBER POSTBACK REMINDER SEND_LOCATION SPM QUICK_REPLY URL VOICE_CALL URL String Button URL. https://www.luckyshrub.com/support String Template body text. Thank you for your order, {{1}}! Your order number is {{2}}. If you have any questions, contact support using the buttons below. Thanks again! String Template footer text. Lucky Shrub: the Succulent Specialists! String Template header text. Your order is confirmed! Integer Template ID. 1315502779341834 String Template language and locale code. en_US String Template name. order_confirmation Integer Unix timestamp indicating when the webhook was triggered. 1739321024 String WhatsApp Business Account ID. 102290129340398 message_template_quality_update webhook reference | Developer Documentation message_template_quality_update webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account message_template_quality_update webhook. The message_template_quality_update webhook notifies you of changes to a template's quality score. Triggers A template's quality score changes. Parameters Placeholder Description Example value String New template quality score. Values can be: GREEN - Indicates high quality. RED - Indicates low quality. YELLOW - Indicates medium quality. UNKNOWN - Indicates quality pending. GREEN String Previous template quality score. Values can be: GREEN - Indicates high quality. RED - Indicates low quality. YELLOW - Indicates medium quality. UNKNOWN - Indicates quality pending. YELLOW Integer Template ID. 806312974732579 String Template name. welcome_template String Template language and locale code. en-US Integer Unix timestamp indicating when the webhook was triggered. 1739321024 String WhatsApp Business Account ID. 102290129340398 message_template_status_update webhook reference | Developer Documentation message_template_status_update webhook reference Updated: Nov 14, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account message_template_status_update webhook. The message_template_status_update webhook notifies you of changes to the status of an existing template. Triggers A template is approved.A template is rejected.A template is disabled. Parameters Placeholder Description Example value String String describing why the template was locked or unlocked. Your WhatsApp message template has been unpaused. Integer Unix timestamp indicating when the template was disabled. 1751234563 String Template status event. Values can be: APPROVED - Indicates the template has been approved and can now be sent in template messages. ARCHIVED: Indicates the template has been archived to keep the list of templates in WhatsApp manager clean. DELETED - Indicates the template has been deleted. DISABLED - Indicates the template has been disabled due to user feedback. FLAGGED - Indicates the template has received negative feedback and is at risk of being disabled. IN_APPEAL - Indicates the template is in the appeal process. LIMIT_EXCEEDED - Indicates the WhatsApp Business Account template is at its template limit. LOCKED - Indicates the template has been locked and cannot be edited. PAUSED - Indicates the template has been paused. PENDING - Indicates the template is undergoing template review. REINSTATED - Indicates the template is no longer flagged or disabled and can be sent in template messages again. PENDING_DELETION - Indicates template has been deleted via WhatsApp Manager. REJECTED - Indicates the template has been rejected. You can edit the template to have it undergo template review again or appeal the rejection. APPROVED Integer Template ID. 1689556908129832 String Template name. order_confirmation String Template language and locale code. en-US String Template rejection reason, if rejected. If the template is scheduled for deletion, the value will be null instead of a string. Otherwise, values can be: ABUSIVE_CONTENT - Indicates template contains content that violates our policies. CATEGORY_NOT_AVAILABLE - (Deprecated) Indicates an authentication templates for an unsupported region. INCORRECT_CATEGORY - Indicates the template's content doesn't match the category designated at the time of template creation. INVALID_FORMAT - Indicates template has an invalid format. NONE: Indicates template was paused. PROMOTIONAL - Indicates template contains content that violates our policies. SCAM - Indicates template contains content that violates our policies. TAG_CONTENT_MISMATCH - Indicates the template's content doesn't match the category designated at the time of template creation. INVALID_FORMAT String Title of template pause or unpause event. Values can be: FIRST_PAUSE - Indicates template has been paused for the first time. SECOND_PAUSE - Indicates the template has been paused a second time. RATE_LIMITING_PAUSE - Indicates template has been paused due to rate limiting. UNPAUSE - Indicates template has been unpaused. DISABLED - Indicates template has been disabled. FIRST_PAUSE <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <MESSAGE_TEMPLATE_CATEGORY> String The template category. Values can be: MARKETING - Indicates template is categorized as MARKETING. UTILITY - Indicates the template is categorized as UTILITY. AUTHENTICATION - Indicates template is categorized as AUTHENTICATION. MARKETING <REASON_INFO> String Provides a detailed explanation for why the template was rejected. This field describes the specific issue detected in the template content. Your template has parameters placed next to each other (like {{1}}{{2}}) without text or punctuation between them. <RECOMMENDATION_INFO> String Offers actionable guidance on how to modify the template to resolve the rejection reason. This field suggests best practices for editing the template content. Separate parameters with descriptive text and ensure each parameter is clearly contextualized. messages webhook reference | Developer Documentation messages webhook reference Updated: Oct 22, 2025 The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user. Payload structures Incoming messages Messages webhooks describing a message sent by a WhatsApp user - either directly, via an ad, or via a UI component in a previously received message - all have the same common structure. You can easily identify these webhooks because they include a messages array. For example, this webhook describes a text message sent a business: Objects in the messages array can vary greatly based on message type (indicated by the object's type property). For this reason, each incoming message type has a dedicated reference, linked in the menu on the left. Outgoing messages Messages webhooks describing a message sent by a business to a WhatsApp user have a different structure. You can easily identify these because they include a statuses array. For example, this webhook describes a message that has been delivered to a WhatsApp user's device: Note that these webhooks don't describe the contents of the outgoing message itself, only its status, and each outgoing message can have up to three separate webhooks (one for a status of sent, one for delivered, and one for read). Status webhooks also have a dedicated reference. Errors Errors in messages webhooks can be surfaced in three places:System-, app-, and account-level errors appear as a value object property ( entry.changes.value.errors). See the errors reference.Incoming message errors appear in the messages array ( entry.changes.value.messages.errors). These webhooks have type set to unsupported. See the unsupported reference.Outgoing message errors appear in the statuses array ( entry.changes.value.statuses.errors). See the status reference. Button messages webhook reference | Developer Documentation Button messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for quick-reply button messages. Triggers A WhatsApp user taps a quick-reply button in a template message. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <BUTTON_LABEL_TEXT> String Quick-reply button label text. Unsubscribe <CONTEXTUAL_WHATSAPP_MESSAGE_ID> String WhatsApp message ID of the message containing the button the WhatsApp user tapped. wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA= <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Contacts messages webhook reference | Developer Documentation Contacts messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing one or more contacts. Triggers A WhatsApp user sends one or more contacts to a business.A WhatsApp user sends one or more contacts to a business via a Click to WhatsApp ad. Parameters Placeholder Description Example value <AD_CLICK_ID> String Click to WhatsApp ad click ID. The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements?). Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50 <AD_GREETING_TEXT> String Click to WhatsApp ad greeting text. Hi there! Let us know how we can help! <AD_HEADLINE> String Click to WhatsApp ad headline. Chat with us <AD_ID> String Click to WhatsApp ad ID. 120226305854810726 <AD_IMAGE_URL> String Click to WhatsApp ad image URL. Only included if the ad is an image ad. https://scontent.xx.fbcdn.net/v/t45.1... <AD_MEDIA_TYPE> String Click to WhatsApp ad media type. Values can be: image - Indicates an image ad. video - Indicates a video ad. image <AD_PRIMARY_TEXT> String Click to WhatsApp ad primary text. Summer succulents are here! <AD_URL> String Click to WhatsApp ad URL. https://fb.me/3cr4Wqqkv <AD_VIDEO_THUMBNAIL> String Click to WhatsApp ad video thumbnail URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.3... <AD_VIDEO_URL> String Click to WhatsApp ad video URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.2... <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CONTACT_ADDRESS_TYPE> String Type of address, such as home or work. Home <CONTACT_BIRTHDAY> String Contact birthday. 1999-01-23 <CONTACT_CITY> String City mentioned in the contact address. Menlo Park <CONTACT_COUNTRY_CODE> String ISO country code on the contact address. US <CONTACT_COUNTRY> String Country mentioned in the contact address. United States <CONTACT_EMAIL_TYPE> String Type of email, such as personal or work. Personal <CONTACT_EMAIL> String Email address of the contact. bjohson@socialtsunami.com <CONTACT_FIRST_NAME> String Contact's first name. Barbara <CONTACT_FORMATTED_NAME> String Contact's formatted name. Barbara J. Johnson <CONTACT_LAST_NAME> String Contact's last name. Johnson <CONTACT_MIDDLE_NAME> String Contact's middle name. Joana <CONTACT_NAME_PREFIX> String Contact's name prefix. Dr. <CONTACT_NAME_SUFFIX> String Contact's name suffix. Esq. <CONTACT_ORG_COMPANY> String Name of the company where the contact works. Social Tsunami <CONTACT_ORG_DEPARTMENT> String Name of the department where the contact works. Engineering <CONTACT_ORG_TITLE> String Contact's job title. Software Engineer <CONTACT_PHONE_TYPE> String Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. CELL <CONTACT_PHONE> String Contact's phone number. +14125550829 <CONTACT_STATE> String State mentioned in the contact address. CA <CONTACT_STREET> String Street mentioned in the contact address. 1 Hacker Way <CONTACT_URL_TYPE> String Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. Company <CONTACT_URL> String Website URL associated with the contact or their company. socialtsunami.com <CONTACT_WHATSAPP_PHONE_NUMBER> String Contact's WhatsApp number. 14125550829 <CONTACT_ZIP> String Zip code in the contact address. 94025 <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Edit messages webhook reference | Developer Documentation Edit messages webhook reference Updated: Dec 3, 2025 The edit webhook is only available to WhatsApp Business app users (aka “Coexistence”) This reference describes edit events and payload contents for the WhatsApp Business Account messages webhook for replies to messages. Triggers A WhatsApp user edits a previously sent message (text, media with caption).A WhatsApp user edits a previous sent message within 15 minutes after being sent. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> Business phone number ID. 106540352242922 <WHATSAPP_USER_PROFILE_NAME> WhatsApp user’s profile name. Sheena Nelson <WHATSAPP_USER_ID> WhatsApp user ID. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> WhatsApp user phone number. 16505551234 <WHATSAPP_MESSAGE_ID> WhatsApp message ID for the edit event. wamid.HBgLMTY1MDM4Nzk0MzkV... <WEBHOOK_TRIGGER_TIMESTAMP> Unix timestamp when the webhook was triggered. 1739321024 <ORIGINAL_WHATSAPP_MESSAGE_ID> ID of the original message being edited. wamid.HBgLMTQxMjU1NTA4MjkV... <CONTEXT_ID> Contextual message ID (if applicable). M0 <MEDIA_ASSET_CAPTION> Caption for the media asset. Updated image caption <MEDIA_ASSET_MIME_TYPE> MIME type of the media asset. image/jpeg <MEDIA_ASSET_SHA256_HASH> SHA256 hash of the media asset. a1b2c3d4e5f6... <MEDIA_ASSET_ID> Media asset ID. 1234567890 <MEDIA_ASSET_URL> URL to the media asset. https://media.example.com/... Errors messages webhooks reference | Developer Documentation Errors messages webhooks reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for errors messages. Triggers We are unable to process a request due to a system level problem.We are unable to process a request due to an app or account level problem. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <ERROR_CODE> Integer Error code. 130429 <ERROR_CODES_URL> String Link to error code documentation. /docs/whatsapp/cloud-api/support/error-codes/ <ERROR_DETAILS> String Error code details. Message failed to send because there were too many messages sent from this phone number in a short period of time <ERROR_MESSAGE> String Error code message. This value is the same as the title property value. Rate limit hit <ERROR_TITLE> String Error code title. This value is the same as the message property value. Rate limit hit <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 Group messages webhook reference | Developer Documentation Group messages webhook reference Updated: Nov 10, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages that are sent to a group, or received from a group. Triggers A WhatsApp user or a business sends a message to a group.A WhatsApp user or a business receives a message within a group. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <GROUP_ID> String The string identifier of a group made using the Groups API. This field shows when messages are sent, received, or read from a group. Learn more about the Groups API "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD" <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <MESSAGE_TEXT_BODY> String Text body of the message. What do you all think about this? <MESSAGE_TYPE> String The type of message being sent. Will change depending on the message sent to the group. Currently, the Groups API supports: TextMediaText-based templatesMedia-based templates text <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 Interactive messages webhook reference | Developer Documentation Interactive messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for replies to interactive messages. TriggersA WhatsApp user taps a row in an interactive list message.A WhatsApp user taps a button in an interactive reply button message. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <BUTTON_ID> String Button ID. cancel-button <BUTTON_LABEL_TEXT> String Button label text. Cancel <CONTEXTUAL_WHATSAPP_MESSAGE_ID> String WhatsApp message ID of the message containing the button the WhatsApp user tapped. wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA= <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <ROW_DESCRIPTION> String Row description. Next Day to 2 Days <ROW_ID> String Row ID. priority_express <ROW_TITLE> String Row title. Priority Mail Express <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. 16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Location messages webhook reference | Developer Documentation Location messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing location information. Triggers A WhatsApp user sends a location message to a business.A WhatsApp user sends a location to a business via a Click to WhatsApp ad. Parameters Placeholder Description Example value <AD_CLICK_ID> String Click to WhatsApp ad click ID. The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements?). Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50 <AD_GREETING_TEXT> String Click to WhatsApp ad greeting text. Hi there! Let us know how we can help! <AD_HEADLINE> String Click to WhatsApp ad headline. Chat with us <AD_ID> String Click to WhatsApp ad ID. 120226305854810726 <AD_IMAGE_URL> String Click to WhatsApp ad image URL. Only included if the ad is an image ad. https://scontent.xx.fbcdn.net/v/t45.1... <AD_MEDIA_TYPE> String Click to WhatsApp ad media type. Values can be: image - Indicates an image ad. video - Indicates a video ad. image <AD_PRIMARY_TEXT> String Click to WhatsApp ad primary text. Summer succulents are here! <AD_URL> String Click to WhatsApp ad URL. https://fb.me/3cr4Wqqkv <AD_VIDEO_THUMBNAIL> String Click to WhatsApp ad video thumbnail URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.3... <AD_VIDEO_URL> String Click to WhatsApp ad video URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.2... <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <LOCATION_ADDRESS> String Location address. 101 Forest Ave, Palo Alto, CA 94301 <LOCATION_LATITUDE> Float Location latitude in decimal degrees. 37.44221496582 <LOCATION_LONGITUDE> Float Location longitude in decimal degrees. -122.16165924072 <LOCATION_NAME> String Location name. Philz Coffee <LOCATION_URL> String Location URL. Usually only included for business locations. https://philzcoffee.com/ <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Order messages webhook reference | Developer Documentation Order messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for order messages. Triggers A WhatsApp user orders one or more products via a catalog, single-, or multi-product message. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CURRENCY_CODE> String Catalog currency code. USD <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <ORDER_TEXT> String Text accompanying the order. Love these! <PRODUCT_CATALOG_ID> String Product catalog ID. 194836987003835 <PRODUCT_ID> String Product ID. di9ozbzfi4 <PRODUCT_PRICE> Integer Individual product price. 7.99 <PRODUCT_QUANTITY> Integer Product quantity. 2 <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. 16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Reaction messages webhook reference | Developer Documentation Reaction messages webhook reference Updated: Nov 14, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing a reaction to a previous message sent by a business. Note: when an end user removes a reaction emoji, a webhook without the “emoji” field will be sent as shown in the sample webhooks below TriggersA WhatsApp user reacts to a previous message sent by a business within the last 30 days.A WhatsApp user removes a previously sent reaction to a previous message sent by a business within the last 30 days Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CONTEXTUAL_WHATSAPP_MESSAGE_ID> String WhatsApp message ID of the message the WhatsApp user reacted to. wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA= <EMOJI_UNICODE> String Unicode of emoji sent by the WhatsApp user as a reaction. If the user removes their initial reaction, another webhook is triggered, but the emoji property will be omitted from the payload. U+1F44D <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <REACTION_TIMESTAMP> String Unix timestamp indicating when the customer sent the reaction. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user’s ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user’s phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user’s name as it appears in their profile in the WhatsApp client. Sheena Nelson Sample Webhooks Receiving a reaction Reaction Removed by end user Status messages webhook reference | Developer Documentation Status messages webhook reference Updated: Nov 20, 2025 This reference describes trigger events and payload contents for WhatsApp Business Account status messages webhook. TriggersYour message is sent to a WhatsApp user.Your message is delivered to a WhatsApp user’s device.Your message is displayed (i.e. “read”) in the WhatsApp client on a WhatsApp user’s device.Your message is unable to be sent to a WhatsApp user.Your message is unable to be delivered to a WhatsApp user’s device.Your message is sent to a WhatsApp user in a group chat.Your voice message is played by the WhatsApp user’s device. Note that the triggers above also apply to a WhatsApp user who is part of a group chat. A status is considered read only if it has been delivered. In some cases, like when a user receives a message while in the chat screen, the message is both delivered and read at the same time. In these cases, the “delivered” webhook is not sent because it’s implied that the message was delivered since it was read. This behavior is due to internal optimization. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_OPAQUE_DATA> String String assigned by the business to the biz_opaque_callback_data property in the send message request. Only included if the business set a biz_opaque_callback_data value when sending the message. 1744434060 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CONVERSATION_CATEGORY> String Conversation category. Values can be: authentication — Indicates an authentication conversation. authentication_international — Indicates an authentication-international conversation. marketing — Indicates a marketing conversation. marketing_lite — Indicates a Marketing Messages API for WhatsApp conversation. referral_conversion — Indicates a free entry point conversation. service — Indicates a service conversation. utility — Indicates a utility conversation. service <CONVERSATION_EXPIRATION_TIMESTAMP> String Unix timestamp indicating when the conversation will expire. The expiration_timestamp property is only included for sent status. 1744434060 <CONVERSATION_ID> String Version 24.0 and higher: The conversation object will be omitted entirely, unless the webhook is for a message sent within an open free entry point window, in which case the value will be unique per window. Version 23.0 and lower: Value will now be set to a unique ID per-message, unless the webhook is for a message sent with an open free entry point window, in which case the value will be unique per window. 8f842dbba350821654c9dfed31f5635c <ERROR_CODE> Integer Error code. 131050 <ERROR_CODES_URL> String Link to error code documentation. /docs/whatsapp/cloud-api/support/error-codes/ <ERROR_DETAILS> String Error code details. In order to maintain a healthy ecosystem engagement, the message failed to be delivered. <ERROR_MESSAGE> String Error code message. This value is the same as the title property value. This message was not delivered to maintain healthy ecosystem engagement. <ERROR_TITLE> String Error code title. This value is the same as the message property value. This message was not delivered to maintain healthy ecosystem engagement. <GROUP_PARTICIPANT_USER_PHONE_NUMBER> String WhatsApp user phone number. Property only included if message was sent to a group. 16505551234 <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <IS_BILLABLE?> Boolean Indicates if the message is billable ( true) or not ( false). Note that the billable property will be deprecated in a future versioned release, so we recommend that you start using pricing.type and pricing.category together to determine if a message is billable, and if so, its billing rate. true <PRICING_CATEGORY> String Pricing category (rate) applied if billable. Values can be: authentication — Indicates authentication rate applied. authentication-international — Indicates authentication-international rate applied. marketing — Indicates marketing rate applied. marketing_lite — Indicates a Marketing Messages API for WhatsApp pricing applied. referral_conversion — Indicates a free entry point conversation. service – Indicates service rate applied. utility — Indicates utility rate applied. service <PRICING_MODEL> String Pricing model. Values can be: CBP — Indicates conversation-based pricing applies. Will only be set to this value if the webhook was sent before July 1, 2025. PMP — Indicates per-message pricing applies. PMP <PRICING_TYPE> String Pricing type. regular — Indicates the message is billable. free_customer_service — Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window. free_entry_point — Indicates the message is free because it was sent within an open free entry point window. regular <STATUS> String Message status. Values can be: delivered — Indicates message was successfully delivered to the WhatsApp user’s device.WhatsApp UI equivalent: Two checkmarks. failed — Indicates failure to send or deliver the message to the WhatsApp user’s device.WhatsApp UI equivalent: Red error triangle. played — Indicates the first time a voice message is played by the WhatsApp user’s device.WhatsApp UI equivalent: Blue microphone. read — Indicates the message was displayed in an open chat thread in the WhatsApp user’s device.WhatsApp UI equivalent: Two blue checkmarks. sent — Indicates the message was successfully sent from our servers.WhatsApp UI equivalent: One checkmark. read <USER_PHONE_NUMBER_OR_GROUP_ID> String WhatsApp user phone number or group ID. Value set to the WhatsApp user’s phone number if the message was sent to their phone number, or set to a group ID if sent to a group ID. If sent to a group ID, the WhatsApp user’s phone number is instead assigned to the recipient_participant_id property. 16505551234 <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= System messages webhook reference | Developer Documentation System messages webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for system messages. Note that unlike other incoming messages webhooks, system messages webhooks don't include a contacts array. Triggers A WhatsApp user changes their WhatsApp phone number. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <NEW_WHATSAPP_USER_ID> String New WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 12195555358 <NEW_WHATSAPP_USER_PHONE_NUMBER> String New WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. 12195555358 <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. Note that a WhatsApp user's phone number and ID may not always match. 16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Text messages webhook reference | Developer Documentation Text messages webhook reference Updated: Oct 27, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing only text. TriggersA WhatsApp user sends a text message to a WhatsApp business phone number.A WhatsApp user forwards a text message to a business phone number.A WhatsApp user uses the Message business button in a catalog, single-, or multi-product message to send a message to the business.A WhatsApp user sends a text message to a business via a Click to WhatsApp ad? (an ad with a WhatsApp message destination). Parameters Placeholder Description Example value <AD_CLICK_ID> String Click to WhatsApp ad click ID. The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements?). Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50 <AD_GREETING_TEXT> String Click to WhatsApp ad greeting text. Hi there! Let us know how we can help! <AD_HEADLINE> String Click to WhatsApp ad headline. Chat with us <AD_ID> String Click to WhatsApp ad ID. 120226305854810726 <AD_IMAGE_URL> String Click to WhatsApp ad image URL. Only included if the ad is an image ad. https://scontent.xx.fbcdn.net/v/t45.1... <AD_MEDIA_TYPE> String Click to WhatsApp ad media type. Values can be: image - Indicates an image ad. video - Indicates a video ad. image <AD_PRIMARY_TEXT> String Click to WhatsApp ad primary text. Summer succulents are here! <AD_URL> String Click to WhatsApp ad URL. https://fb.me/3cr4Wqqkv <AD_VIDEO_THUMBNAIL> String Click to WhatsApp ad video thumbnail URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.3... <AD_VIDEO_URL> String Click to WhatsApp ad video URL. Only included if ad is a video ad. https://scontent.xx.fbcdn.net/v/t45.2... <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CONTEXTUAL_WHATSAPP_MESSAGE_ID> String WhatsApp message ID of the message the WhatsApp user used to access the Message business button. wamid.HBgLMTY1MDM4Nzk0MzkVAgARGA9wcm9kdWN0X2lucXVpcnkA <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <MESSAGE_TEXT_BODY> String Text body of the message. Is it available in another color? <PRODUCT_CATALOG_ID> String Product catalog ID. 194836987003835 <PRODUCT_ID> String Product ID. di9ozbzfi4 <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson Unsupported messages webhook reference | Developer Documentation Unsupported messages webhook reference Updated: Mar 20, 2026 This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for unsupported messages. TriggersA WhatsApp user sends a message type not supported by Cloud API.You use the API to send a message to a number already in use with the API. In this case, the webhook is sent to the owner of the recipient number.A WhatsApp user messages a business that has been onboarded with a WhatsApp Business app phone number, for the first time. This is especially common when users tap one of the business's ads that click to WhatsApp? and immediately send a message. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <IDENTITY_KEY_HASH> String Identity key hash. Only included if you have enabled the identity change check feature. DF2lS5v2W6x= <ERROR_CODE> The error code. Possible values: 131051 - Cloud API does not support the message type. 131060 - The message is currently unavailable. This typically occurs when a WhatsApp user messages a business onboarded with a WhatsApp Business app phone number, for the first time. 131051 <ERROR_DETAILS> A human-readable description of the error. Message type is currently not supported. <ERROR_MESSAGE> A human-readable error message. Same as ERROR_TITLE. Message type unknown <ERROR_TITLE> A human-readable error title. Possible values: Message type unknown - Corresponds to error code 131051. This message is currently unavailable. - Corresponds to error code 131060. Message type unknown <UNSUPPORTED_TYPE> Contains the type of message that is unsupported. Values can be: errors gif group_invite hsm image interactive keep_in_chat link_preview list location media_placeholder order pin poll_creation poll_update product reaction poll_update <WEBHOOK_TRIGGER_TIMESTAMP> String Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user's phone number and ID may not always match. +16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson partner_solutions webhook reference | Developer Documentation partner_solutions webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account partner_solutions webhook. The partner_solutions webhook describes changes to the status of a Multi-Partner Solution. Triggers A multi-partner solution is saved as a draft.A multi-partner solution request is sent to a partner.A multi-partner solution partner accepts a solution request.A multi-partner solution partner rejects a solution request.A multi-partner solution partner requests deactivation of a solution.A multi-partner solution is deactivated. Parameters Placeholder Description Example value <BUSINESS_PORTFOLIO_ID> String Business portfolio ID. 506914307656634 <EVENT> String Change event. Values can be: SOLUTION_CREATED - Indicates a new solution was saved as a draft or sent as a request to a partner. SOLUTION_UPDATED - Indicates an existing solution has been updated. SOLUTION_CREATED <SOLUTION_ID> String Solution ID. 774485461512159 <SOLUTION_STATUS> String Solution status. Values can be: ACTIVE - The solution partner accepted the solution request and the solution can now be used. DEACTIVATED - The solution has been deactivated. DRAFT - The solution has been drafted but an invitation request has not been sent to a partner. INITIATED - The solution has been created and the invitation request sent, but it has not been accepted or rejected yet. PENDING_DEACTIVATION - The solution owner requested deactivation of the solution but the solution partner has yet to accept or decline the deactivation request. REJECTED - The solution partner has rejected the solution request. INITIATED <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 payment_configuration_update webhook reference | Developer Documentation payment_configuration_update webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account payment_configuration_update webhook. The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil. TriggersThe payment configuration associated with a WhatsApp Business Account has been connected to a payment gateway account.The payment configuration associated with a WhatsApp Business Account has been disconnected from a payment gateway account.The payment configuration associated with a WhatsApp Business Account is now active. Parameters Placeholder Description Example value <PAYMENT_CONFIGURATION_CREATION_TIMESTAMP> Integer UNIX timestamp indicated when the payment configuration was created. 1748827100 <PAYMENT_CONFIGURATION_NAME> String Payment configuration name to be used in the Order Details messages. razorpay-prod <PAYMENT_CONFIGURATION_STATUS> String Payment configuration status. Values can be: Active - Indicates the payment configuration has been tested in WhatsApp manager and can now be used with Payments API. Needs Connecting - Indicates the payment configuration has been disconnected from the payment gateway and needs to be connected again. Needs Testing - Indicates the payment configuration has been connected to the payment gateway but still needs testing in WhatsApp Manager. Needs Connecting <PAYMENT_CONFIGURATION_UPDATE_TIMESTAMP> Integer UNIX timestamp indicated when the payment configuration was updated. 1749320300 <PAYMENT_GATEWAY_MERCHANT_ACCOUNT_ID> String Payment gateway merchant account ID. acc_GP4lfNA0iIMn5B <PAYMENT_GATEWAY_PROVIDER_NAME> String Name of the payment gateway provider associated with the payment configuration. Values can be: billdesk payu razorpay zaakpay razorpay <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 phone_number_name_update webhook reference | Developer Documentation phone_number_name_update webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account phone_number_name_update webhook. The phone_number_name_update webhook notifies you of business phone number display name verification outcomes. Triggers A newly created business phone number's display name is reviewed.A business phone number's already approved display name is edited and reviewed. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <DECISION> String Indicates the outcome of the business phone number display name verification process. APPROVED - Indicates the display name has been approved and will now appear at the top of the business phone number's profile in the WhatsApp client. DEFERRED - Indicates a decision has been deferred. PENDING - Indicates a decision is still pending further review. REJECTED - Indicates the display name has been rejected. You can edit the name using WhatsApp Manager?. Review our display name guidelines? before editing. APPROVED <REJECTION_REASON> String The reason why the business phone number display name was rejected, if it was rejected. Review our display name guidelines for common rejection reasons. Values can be: NAME_EMPLOYEE_ISSUE - Rejected because the display name included a person's name or employee identifier. NAME_ENDCLIENT_NOTRELATED - Rejected because the display name included an unrelated business's name. NAME_FORMAT_UNACCEPTABLE - Rejected because the display name used an unacceptable format. NAME_INDIVIDUAL_ISSUE - Rejected because the display name included a person's name or employee identifier. NAME_NOT_CONSISTENT - Rejected because the display name was not consistent with the business's branding. null - Indicates name was accepted. UNKNOWN - Rejected for an unknown reason. Please contact support. APPROVED <REQUESTED_DISPLAY_NAME> String The business phone number display name collected when the number was created, or name submitted when editing an already approved display name. Lucky Shrub <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 phone_number_quality_update webhook reference | Developer Documentation phone_number_quality_update webhook reference Updated: Nov 14, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account phone_number_quality_update webhook. The phone_number_quality_update webhook notifies you of changes to a business phone number's throughput level. Triggers A business phone number's throughput level changes. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <CURRENT_LIMIT> String This field will be removed in February, 2026. Use max_daily_conversations_per_business instead. Indicates current messaging limit or throughput level. Values can be: TIER_50 - Indicates a messaging limit of 50. TIER_250 - Indicates a messaging limit of 250. TIER_2K - Indicates a messaging limit of 2,000. TIER_10K - Indicates a messaging limit of 10,000. TIER_100K - Indicates a messaging limit of 100,000. TIER_NOT_SET - Indicates the business phone number has not been used to send a message yet. TIER_UNLIMITED - Indicates the business phone number has higher throughput. TIER_UNLIMITED <EVENT> String Messaging limit change or throughput change event. Values can be: ONBOARDING - Indicates the business phone number is still being registered. THROUGHPUT_UPGRADE - Indicates the business phone number's throughput level has increased to higher throughput. THROUGHPUT_UPGRADE <MAX_DAILY_MESSAGES_LIMIT> String Indicates a change to the owning business portfolio's messaging limit or throughput change. Values can be: TIER_50 - Indicates a messaging limit of 50. TIER_250 - Indicates a messaging limit of 250. TIER_2K - Indicates a messaging limit of 2,000. TIER_10K - Indicates a messaging limit of 10,000. TIER_100K - Indicates a messaging limit of 100,000. TIER_NOT_SET - Indicates the business phone number has not been used to send a message yet. TIER_UNLIMITED - Indicates the business phone number has higher throughput. TIER_2K <OLD_LIMIT> String This parameter will be removed in February, 2026. Use max_daily_conversations_per_business instead. Indicates old messaging limit. Values can be: TIER_50 - Indicates a messaging limit of 50. TIER_250 - Indicates a messaging limit of 250. TIER_2K - Indicates a messaging limit of 2,000. TIER_10K - Indicates a messaging limit of 10,000. TIER_100K - Indicates a messaging limit of 100,000. TIER_NOT_SET - Indicates the business phone number has not been used to send a message yet. TIER_UNLIMITED <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 security webhook reference | Developer Documentation security webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account security webhook. The security webhook notifies you of changes to a business phone number's security settings. Triggers A Meta Business Suite user clicks the Turn off two-step verification button in WhatsApp Manager?.A Meta Business Suite user completes the instructions in the WhatsApp Two-Step Verification Reset email to turn off two-step verification.A Meta Business Suite user changes or enables the business phone number PIN using WhatsApp Manager?. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <EVENT> String The security event that triggered the webhook. Values can be: PIN_CHANGED - indicates a Meta Business Suite user changed or enabled the business phone number's PIN using WhatsApp Manager?. PIN_RESET_REQUEST - Indicates a Meta Business Suite user clicked the Turn off two-step verification button in WhatsApp Manager?. PIN_REQUEST_SUCCESS - a Meta Business Suite user completed the instructions in the WhatsApp Two-Step Verification Reset email to turn off two-step verification. PIN_RESET_REQUEST <META_BUSINESS_SUITE_USER_ID> String The Meta Business Suite user ID of the user who requested to turn off two-step verification using WhatsApp Manager?. This parameter is only included for PIN reset requests. 61555822107539 <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 smb_app_state_sync webhook reference | Developer Documentation smb_app_state_sync webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account smb_app_state_sync webhook. The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider. Triggers A solution provider synchronizes the WhatsApp Business app contacts of a business customer with a WhatsApp Business app phone number who the provider has onboarded.A business customer with a WhatsApp Business app phone number who has been onboarded by a solution provider adds a contact to their WhatsApp Business app contacts?.A business customer with a WhatsApp Business app phone number who has been onboarded by a solution provider removes a contact from their WhatsApp Business app contacts?.A business customer with a WhatsApp Business app phone number who has been onboarded by a solution provider edits a contact in their WhatsApp Business app contacts?. Parameters Placeholder Description Example value <ACTION> String Indicates if the business customer added, edited, or deleted a contact from their WhatsApp Business app phone address book. Values can be: add - Indicates the WhatsApp Business app user added or edited a contact. remove - Indicates the WhatsApp Business app user removed a contact. add <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CONTACT_FIRST_NAME> String The contact's first name, as it appears in the business customer's WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book. Pablo <CONTACT_FULL_NAME> String The contact's full name, as it appears in the business customer's WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book. Pablo Morales <CONTACT_PHONE_NUMBER>String The contact's WhatsApp phone number. 16505551234 <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 smb_message_echoes webhook reference | Developer Documentation smb_message_echoes webhook reference Updated: Oct 22, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account smb_message_echoes webhook. The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider. TriggersA business customer with a WhatsApp Business app phone number, who has been onboarded by a solution provider, sends a message using the WhatsApp Business app or a companion device to a WhatsApp user or another business. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <MESSAGE_CONTENTS> Object An object describing the message’s contents. This value will vary based on the message type, as well as the contents of the message. For example, if a business sends an image message without a caption, the object would not include the caption property. See Sending messages for examples of payloads for each message type. <MESSAGE_TYPE> String Message type. Note that this placeholder appears twice in the syntax above, as it serves as a placeholder for the type property’s value and its matching property name. text <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String The business customer’s WhatsApp Business Account ID. 102290129340398 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_USER_PHONE_NUMBER> String WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user’s phone number and ID may not always match. +16505551234 template_category_update webhook reference | Developer Documentation template_category_update webhook reference Updated: Nov 11, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account template_category_update webhook. The template_category_update webhook notifies you of changes to template's category. TriggersThe existing category of a WhatsApp template is going to be changed by an automated process.The existing category of a WhatsApp template is changed manually or by an automated process. Parameters Placeholder Description Example value <CORRECT_CATEGORY> String The category that the template will be recategorized as in 24 hours. MARKETING <CURRENT_CATEGORY> String The template's current category. MARKETING <NEW_CATEGORY> String The template's new category. MARKETING <CATEGORY_UPDATE_TIMESTAMP> Integer The Unix timestamp (in seconds) indicating when the template's category will be updated to the <CORRECT_CATEGORY> specified in the webhook. This value represents the moment the update is scheduled to occur. 1760711433 <PREVIOUS_CATEGORY> String The template's previous category. UTILITY <TEMPLATE_ID> Integer Template ID. 278077987957091 <TEMPLATE_LANGUAGE> String Template language and locale code. en-US <TEMPLATE_NAME> String Template name. welcome_template <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 user_preferences webhook reference | Developer Documentation user_preferences webhook reference Updated: Nov 5, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account user_preferences webhook. The user_preferences webhook notifies you of changes to a WhatsApp user's marketing message preferences. Triggers A WhatsApp user stops marketing messages.A WhatsApp user resumes marketing messages. Parameters Placeholder Description Example value <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <PREFERENCE> String Marketing message preference. Values can be: stop - Indicates the WhatsApp user has opted to stop receiving marketing messages from you. resume - Indicates the WhatsApp user has opted to resume receiving marketing messages from you. stop <PREFERENCE_DESCRIPTION> String Description of marketing message preference. Values can be: User requested to stop marketing messages User requested to resume marketing messages User requested to stop marketing messages <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 <WHATSAPP_USER_ID> String WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match. 16505551234 <WHATSAPP_USER_PROFILE_NAME> String WhatsApp user's name as it appears in their profile in the WhatsApp client. Sheena Nelson automatic_events webhook reference | Developer Documentation automatic_events webhook reference Updated: Nov 5, 2025 This reference describes trigger events and payload contents for the WhatsApp Business Account automatic_events webhook. The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting. TriggersA lead event is detected in a chat thread between a business and user who has messaged the business via a Click to WhatsApp Ad.A purchase event is detected in a chat thread between a business and user who has messaged the business via a Click to WhatsApp Ad. Parameters Placeholder Description Example value <AD_CLICK_ID> String Click to WhatsApp ad click ID. The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements?). Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50 <AMOUNT> String Purchase amount, calculated as product price multiplied by 1000. 25000 <BUSINESS_DISPLAY_PHONE_NUMBER> String Business display phone number. 15550783881 <BUSINESS_PHONE_NUMBER_ID> String Business phone number ID. 106540352242922 <CURRENCY_CODE> String Currency code. USD <EVENT_NAME> String Event name. Values can be: LeadSubmitted - Indicates a lead event. Purchase - Indicates a purchase event. Purchase <WEBHOOK_TRIGGER_TIMESTAMP> Integer Unix timestamp indicating when the webhook was triggered. 1739321024 <WHATSAPP_MESSAGE_ID> String WhatsApp message ID. wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA= <WHATSAPP_BUSINESS_ACCOUNT_ID> String WhatsApp Business Account ID. 102290129340398 Webhook overrides | Developer Documentation Webhook overrides Updated: Mar 23, 2026 Webhooks are sent to the callback URL set on your app, but you can override this for your own app by designating an alternate callback URL for the WhatsApp Business Account (WABA) or business phone number. When a webhook is triggered for a supported field, the system first checks if your app has designated an alternate callback URL for the business phone number associated with the event. If set, the webhook is sent to your alternate callback URL. If the phone number has no alternate, the system checks if the WABA associated with the number has an alternate callback URL, and if set, sends it there. If the WABA also has no alternate, the webhook falls back to your app's callback URL. Supported webhook fields The override applies only to the following webhook field types. Webhooks for field types not listed here are always sent to your app's default callback URL. messages message_echoes calls consumer_profile messaging_handovers group_lifecycle_update group_participants_update group_settings_update group_status_update smb_message_echoes smb_app_state_sync history account_settings_update Note: Template webhooks ( message_template_status_update, message_template_quality_update, message_template_components_update, template_category_update) and account-level webhooks ( account_update, account_review_update, account_alerts) do not support callback overrides. These webhooks are always delivered to your app's default callback URL. Requirements Before setting an alternate callback URL, make sure your app is subscribed to webhooks on the WABA and verify that your alternate callback endpoint can receive and process webhooks correctly. Get WABA alternate callback Delete WABA alternate callback Delete phone number alternate callback Whatsapp Business Accounts WhatsApp Business Accounts | Developer Documentation WhatsApp Business Accounts Updated: Oct 30, 2025 WhatsApp Business Accounts (“WABAs”) represent a business on the WhatsApp Business Platform. You must have a WABA to send and receive messages to and from WhatsApp users, and to create and manage templates. There are several ways to create a WABA, which are described below. Once created, we recommend that you connect your phone number⁠ and set up a payment method⁠. LimitationsA WhatsApp Business Account (WABA) can have a maximum of 250 message templates.Meta Business Accounts are initially limited to 2 registered business phone numbers, but this limit can be increased to up to 20. See Registered Number Limits.Meta Business Accounts are initially limited to 20 WABAs.A WABA must belong to only one Business Manager. You cannot have two or more Business Managers owning one WABA.A WABA’s time zone and currency cannot be edited once a line of credit has been attached to it. You cannot migrate a WABA from one business to another. Create a WABA via the App Dashboard If you are going to be using Cloud API directly to send and receive messages, follow the steps in the Cloud API Get Started documentation. Once you have completed these steps, you will have a test WABA and test business number, and have access to the App Dashboard > WhatsApp > API Setup panel. The API Setup panel allows you to add a production business phone number, which generates a new WABA, which is then associated with that number. Create a WABA via a solution provider If you are working with a solution provider (a business that offers WhatsApp messaging services to other businesses) who offers WhatsApp messaging services for you via the API, the solution provider will provide you with instructions. Typically this involves you completing the Embedded Signup flow, which gathers information about your business and generates a WABA for you, then using the provider’s app to access your newly created WABA and related assets. See our Create your WhatsApp Business Account with WhatsApp Business solution providers⁠ Help Center article for more information. Create a WABA via Meta Business Suite This feature is being released gradually over the next few weeks and may not be available to you immediately. Business portfolios with a Brazil or India address are currently unable to use this feature. You can create a WABA using Meta Business Suite⁠. Use this method if you are working with a solution provider who provides WhatsApp messaging-related services via Meta Business Suite instead of Cloud API. To create a WABA using Meta Business Suite:Go to https://business.facebook.com/⁠ and create a business portfolio, or sign into your existing account and select your existing portfolio if you already have one.Navigate to the Settings (gear icon) > Accounts > WhatsApp accounts panel.Click the blue +Add button and in the dropdown menu select Create a new WhatsApp Business account.In the Create a WhatsApp Business account window that appears (pictured below), complete the flow. Share your WABA with a solution provider You can share your WABA (or any of your business assets) with any business-verified solution provider (aka “partner”) using Meta Business Suite. Once shared, the partner can then use the Meta Business Suite to access your WABA and provide services. NotesIf you are sharing your WABA with a Solution Provider (a type of partner who has a credit line), they must share their credit line with you before you will be able to use their app to send messages.You can share a WABA with up to two partners. If you have not shared an asset with the partner beforeAsk the partner for their business portfolio ID. You will need this ID to complete the remaining steps.Sign into Meta Business Suite⁠. Use the top-left dropdown menu to select the business portfolio if you have multiple portfolios.Navigate to the Settings (gear icon) > Accounts > WhatsApp accounts panel.In the list of WABAs, select your WABA, or click its Details link.In the details overlay that appears to the right (pictured below), click the Assign partner button.In the Share this WhatsApp Account with a partner overlay that appears, enter the partner’s business portfolio ID and use the toggles to define which permissions to grant to the partner, then click the Assign button.If your WABA is shared with the partner successfully, a Partner added message will appear. Click the Done button to dismiss it.Back in the details overlay, click the Partners tab.In the Partners tab, confirm that the partner’s name appears as a partner with appropriate permissions.Inform the partner that you have successfully shared your WABA with them (and ask them to share their credit line if appropriate; see note above). If you have already shared an asset with the partnerSign into Meta Business Suite⁠. Use the top-left dropdown menu to select the business portfolio if you have multiple portfolios.Navigate to the Settings (gear icon) > Users > Partners panel.In the list of partners, click the name of the partner, or its Details link.In the details overlay that appears to the right (pictured below), click the Assign assets button.In the Assign assets and permissions window that appears, click the WhatsApp accounts asset type.Check the checkbox next to your WABA, then use the toggles to define which permissions to grant to the partner and click the Assign button.If successful, an Assets assigned message will appear. Click the Done button to dismiss the window.Confirm that your WABA appears in the Assets you assigned tab with appropriate permissions.Inform the partner that you have successfully shared your WABA with them (and to share their credit line if appropriate; see note above). Access your WABA with WhatsApp Manager You can access your WABA in WhatsApp Manager to see basic information like business phone number status, messaging metrics, and to perform basic tasks like template creation and editing. To access your WABA in WhatsApp Manager:Sign into Meta Business Suite⁠. Use the top-left dropdown menu to select the business portfolio if you have multiple portfolios.Navigate to the Settings (gear icon) > Accounts > WhatsApp accounts panel.In the list of WABAs, select your WABA, or click its Details link.In the Summary tab, click the WhatsApp Manager button. Webhooks Subscribe to the account_update webhook to be notified of changes to a WhatsApp Business Account’s status, including changes due to policy and terms violations. Every time your WABA has violated a policy, you will get a notification looking like this: See our WhatsApp Business Platform Policy Violations document for a list of policy violations. If a restriction has been imposed, an account_update webhook will be triggered, describing the violation. Messaging On-Behalf-Of The On-Behalf-Of WABA ownership model is deprecated is no longer possible. See OBO model deprecation for details.