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.
Requirements
Limitations
Unsupported countries
WhatsApp Business account phone numbers with country codes from the following countries are not supported:
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.
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 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.
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:
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: "<CUSTOMER_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.
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:
curlExample 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 1:2: Initiate contactsmessage history synchronization
Use the POST /<BUSINESS_PHONE_NUMBER_ID>/smb_app_data endpoint again, this time to requestinitiate themessaging businesshistory customer’ssynchronization.
Upon information.
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.
Example
request
curl -X POST \ 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data \ -H 'Authorization: <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'
Example response
{ "messaging_product": "whatsapp", "request_id" : "<REQUEST_ID>" }
request_idStep 2: Initiate message history synchronization
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.Example
request
curl -X POST \ 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data \ -H 'Authorization: <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "sync_type": "history" }'
Example response
{ "messaging_product": "whatsapp", "request_id" : "<REQUEST_ID>" }
request_idStep 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
You cannot use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregister endpoint to deregister a business phone number from Cloud API if it is already in use with both Cloud API and the WhatsApp Business app.
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:If you receive this webhook, instruct the business to check the WhatsApp Business app for the message.
Webhooks
account_update
Trigger events
Payload syntax
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID>", "time": <WEBHOOK_TIMESTAMP>, "changes": [ { "value": { "phone_number": "<BUSINESS_PHONE_NUMBER>", "event": "<EVENT>", }, "field": "account_update" } ] } ] }
Example payload
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "time": 1739212624, "changes": [ { "value": { "phone_number": "15550783881", "event": "PARTNER_REMOVED", }, "field": "account_update" } ] } ] }
account_offboarded
Trigger events
Payload syntax
{ "entry": [ { "id": "<WABA_ID>", "time": "<WEBHOOK_TIMESTAMP>", "changes": [ { "value": { "event": "ACCOUNT_OFFBOARDED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
Example payload
{ "entry": [ { "id": "862475293675413", "time": 1768477204, "changes": [ { "value": { "event": "ACCOUNT_OFFBOARDED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
account_reconnected
Trigger events
Payload syntax
{ "entry": [ { "id": "<WABA_ID>", "time": "<WEBHOOK_TIMESTAMP>", "changes": [ { "value": { "event": "ACCOUNT_RECONNECTED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
Example payload
{ "entry": [ { "id": "862475293675413", "time": 1768477203, "changes": [ { "value": { "event": "ACCOUNT_RECONNECTED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
Edit
Trigger events
Payload syntax
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "contacts": [ { "profile": { "name": "<WHATSAPP_USER_PROFILE_NAME>" }, "wa_id": "<WHATSAPP_USER_ID>" } ], "messages": [ { "from": "<WHATSAPP_USER_PHONE_NUMBER>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", "type": "edit", "edit": { "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID>", "message": { "context": { "id": "<CONTEXT_ID>" }, "type": "image", "image": { "caption": "<MEDIA_ASSET_CAPTION>", "mime_type": "<MEDIA_ASSET_MIME_TYPE>", "sha256": "<MEDIA_ASSET_SHA256_HASH>", "id": "<MEDIA_ASSET_ID>", "url": "<MEDIA_ASSET_URL>" } } } } ] }, "field": "messages" } ] } ] }
Parameters
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
Example
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "timestamp": "1749854575", "type": "edit", "edit": { "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=", "message": { "context": { "id": "M0" }, "type": "image", "image": { "caption": "Updated image caption", "mime_type": "image/jpeg", "sha256": "a1b2c3d4e5f6...", "id": "1234567890", "url": "https://media.example.com/updated-image.jpg" } } } } ] }, "field": "messages" } ] } ] }
Revoke
Trigger events
Syntax
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "contacts": [ { "profile": { "name": "<WHATSAPP_USER_PROFILE_NAME>" }, "wa_id": "<WHATSAPP_USER_ID>" } ], "messages": [ { "from": "<WHATSAPP_USER_PHONE_NUMBER>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", "type": "revoke", "revoke": { "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID>" } } ] }, "field": "messages" } ] } ] }
Parameters
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
Example
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "timestamp": "1749854575", "type": "revoke", "revoke": { "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=" } } ] }, "field": "messages" } ] } ] }
History
Trigger events
Chat history contents
Phases and chunks
chunk_orderphase2progress100Payload syntax — chat history sharing approved
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "history": [ { "metadata": { "phase": <PHASE>, "chunk_order": <CHUNK_ORDER>, "progress": <PROGRESS> }, "threads": [ /* First chat history thread object */ { "id": "<WHATSAPP_USER_PHONE_NUMBER>", "messages": [ /* First message object in thread */ { "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>", "to": "<WHATSAPP_USER_PHONE_NUMBER>", // only included if SMB message echo "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<DEVICE_TIMESTAMP>, "type": "<MESSAGE_TYPE>", "<MESSAGE_TYPE>": { <MESSAGE_CONTENTS> }, "history_context": { "status": "<MESSAGE_STATUS>" } }, /* Additional message objects in thread would follow, if any */ ] }, /* Additional chat history thread objects would follow, if any */ ] } ] }, "field": "history" } ] } ] }
Payload contents — chat history sharing approved
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
Example payload — chat history sharing approved
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "history": [ { "metadata": { "phase": 0, "chunk_order": 1, "progress": 55 }, "threads": [ { "id": "16505551234", "messages": [ { "from": "15550783881", "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "timestamp": "1739230955", "type": "text", "text": { "body": "Here's the info you requested! https://www.meta.com/quest/quest-3/" }, "history_context": { "status": "READ" } }, { "from": "15550783881", "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA", "timestamp": "1739230970", "type": "media_placeholder", "history_context": { "status": "PLAYED" } }, { "from": "16505551234", "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0", "timestamp": "1739230970", "type": "text", "text": { "body": "Thanks!" }, "history_context": { "status": "READ" } } ] }, { "id": "12125557890", "messages": [ { "from": "15550783881", "id": "wamid.BIyNDlBOEI5N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGQUQ4NDc0", "timestamp": "1739230970", "type": "text", "text": { "body": "Thanks for your order! As a thank you, use code THANKS30 to get 30% of your next order." }, "history_context": { "status": "DELIVERED" } } ] } ] } ] }, "field": "history" } ] } ] }
Example payload for media message asset
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "messages": [ { "from": "16505551234", "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA", "timestamp": "1738796547", "type": "image", "image": { "caption": "Black Prince echeveria", "mime_type": "image/jpeg", "sha256": "3f9d94d399fa61c191bc1d4ca71375a035cd9b9f5b1128e1f0963a415c16b0cc", "id": "24230790383178626" } } ] }, "field": "history" } ] } ] }
Payload syntax — chat history sharing declined
{ "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "history": [ { "errors": [ { "code": 2593109, "title": "History sync is turned off by the business from the WhatsApp Business App", "message": "History sync is turned off by the business from the WhatsApp Business App", "error_data": { "details": "History sharing is turned off by the business" } } ] } ] }
Example payload — chat history sharing declined
{ "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "history": [ { "errors": [ { "code": 2593109, "title": "History sync is turned off by the business from the WhatsApp Business App", "message": "History sync is turned off by the business from the WhatsApp Business App", "error_data": { "details": "History sharing is turned off by the business" } } ] } ] }
smb_app_state_sync
Trigger events:
Payload syntax
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "state_sync": [ { "type": "contact", "contact": { "full_name": "<CONTACT_FULL_NAME>", "first_name": "<CONTACT_FIRST_NAME>", "phone_number": "<CONTACT_PHONE_NUMBER>" }, "action": "<ACTION>", "metadata": { "timestamp": "<WEBHOOK_TIMESTAMP>" } }, * Additional contacts would follow, if any */ ] }, "field": "smb_app_state_sync" } ] } ] }
Payload contents
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| |
smb_message_echoes
Trigger events
Payload syntax
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "message_echoes": [ { "from": "<BUSINESS_PHONE_NUMBER>", "to": "<WHATSAPP_USER_PHONE_NUMBER>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_TIMESTAMP>", "type": "<MESSAGE_TYPE>", "<MESSAGE_TYPE>": { <MESSAGE_CONTENTS> } } ] }, "field": "smb_message_echoes" } ] } ] }
Payload contents
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
Example payload
typetext{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "message_echoes": [ { "from": "15550783881", "to": "16505551234", "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "timestamp": "1700255121", "type": "text" "text": { "body": "Here's the info you requested! https://www.meta.com/quest/quest-3/" } } ] }, "field": "smb_message_echoes" } ] } ] }
Need support?
For Coexistence onboarding, choose:
For Coexistence API issues, choose: