WhatsApp Cloud API with Meta Embedded Signup

Overview

Guided setup opens Meta authorization and links the selected number to a WhatsApp Cloud inbox. Creating an inbox requires WhatsApp Embedded Signup Flow enabled for the account on both self-hosted and cloud installations. The installation also needs its Meta app configured. An administrator or authorized native role with the appropriate inbox management scope can run setup.

Prerequisites

• Permission to manage the inbox within the appropriate access scope.
• A Meta app configured for the installation and access to the business managing the number.
• WhatsApp Embedded Signup Flow enabled to create an inbox; WhatsApp Manual Transfer enabled for manual transfer.
• Recovering an existing inbox uses permission to manage that inbox.

Step by step

1. Open Settings → Inboxes → Add inbox → WhatsApp.
2. Choose guided Meta setup and sign in to the business account managing the number.
3. Select the correct WABA and number, then complete the steps requested by Meta.
4. Wait for the platform to confirm configuration. Closing the popup or receiving only part of the authorization does not complete the connection.
5. Send and receive a test message with a contact you control before starting normal operation.

Settings & options

Reconnect or reconfigure an existing inbox

Open Configuration → Reconfigure or use the inbox reconnection notice. Authorized administrators can recover an existing inbox even when new inbox creation or the legacy reconfigure flag is disabled. Do not create another inbox to repair its connection.

Select the same number. Recovery preserves the inbox, conversations and the hybrid WhatsApp Web partner. An identifier belonging to a different number is rejected. Coex uses this same guided flow.

If you see configuration pending, credentials were saved but the platform has not confirmed all required setup. The inbox remains available for another recovery attempt. This does not mean the connection is complete, and creating another inbox is unnecessary. The message names the step that is still pending — phone number registration or message delivery (webhook) — and the retry is done from the inbox's reconnect banner.

Read account health

Account Health shows what Meta reports today about the number. The top says when Meta last confirmed the data (Checked with Meta on). Check now asks Meta again; the platform does that at most once every 30 seconds per inbox, and the button stays disabled during that interval.

• Sending status: the status Meta computes before each message, considering the number, the WhatsApp Business Account, the business portfolio and the app: Available, Limited or Blocked. When something limits or blocks, the tab shows the affected item, Meta's explanation and what to do, in Meta's own words. The notices Meta attaches to an item also appear, even when the item is available; the most serious is "the app is not subscribed to the message webhook", which means the number does not receive customer messages. The Receiving calls over SIP line shows Not configured when the number does not use SIP, which is normal on the platform.
• Attention points: warnings the platform records from Meta's notifications. Number reconnecting after a device change, connection removed, authorization that must be renewed, restrictions in force with their end date, policy violation, conversations with another responder in Conversation Routing, account events or messages delivered to another address, and an inbox connected for more than 24 hours without receiving any message. Connection warnings lead to Go to Configuration.
• Phone number: number, display name and its status, platform (Cloud API only, or also the WhatsApp Business app), official business account (blue badge), account mode (Production or Test), number status and code verification.
• Capacity and limits: sending speed, messaging limit, quality rating and, for users who may view costs, the estimate of free service messages for the month. See the next section.
• Business account: WhatsApp Business Account, portfolio, business verification and account review.
• Webhook: the configured address and the webhook fields subscribed in the Meta app: this installation's app for an inbox created with Embedded Signup, or your own app for a manual inbox with an App Secret. If the messages field is not subscribed, the app receives no customer messages and the inbox stays silent: the tab says so first. Without an App Secret, or when Meta refuses the secret, the list becomes a checklist to confirm in the Meta App Dashboard. The tab also lists the apps subscribed to the WhatsApp Business Account and warns when more than one delivers webhooks here. If the app callback points to another system, the tab warns you: Meta always delivers account updates, alerts and template status to the app callback, so this installation stops receiving them.

Information Meta did not return does not break the tab: the affected block says so and keeps the last known value. Failure to query the business account does not erase valid phone details. Diagnostics identify the failed stage and provide Try again.

An unavailable-object or permissions error alone does not prove the token expired. Check the number, WABA, permissions and reported stage; use Reconfigure when authorization needs renewal. The query time and stale-data notice distinguish retained history from a current successful check.

Number capacity and limits

Sending speed. How many messages per second Meta accepts for this number, counting messages sent and received. The pace follows the number limit at Meta: 80 messages per second at first, up to 1,000 if Meta upgrades it, and 20 on a coexistence number. Campaigns use up to the limit minus 5.

• Meta raises the number to the high level by itself when it qualifies: unlimited messaging limit, at least 100,000 unique customers outside a service window in 24 hours, and Medium quality or better. The platform reads the level every 6 hours and updates it at once when Meta announces the upgrade.
• The block shows Confirmed by Meta on with the date and time of the last confirmation.
• When Meta has not confirmed the level yet, or the last confirmation is older than 24 hours, the block says so and uses the standard limit of 80. The platform never assumes the high level without that confirmation.
• Nothing is reserved for replies: they share the same room as other sends. Sending above the limit makes Meta refuse the message.
• A WhatsApp Web inbox has no such limit: it follows its own pacing against bans.

Messaging limit. How many different customers can receive messages outside the customer service window in a moving 24-hour period. The limit belongs to the business portfolio and applies to all of its numbers. The tab shows an estimate of the use in the last 24 hours: customers who received a template outside an open service window from the numbers of this account connected to ConversaLabs. Other apps and accounts on the same portfolio are not counted; use the value as a reference, not as Meta's official number. How the limit rises, according to Meta:

1. from 250 to 2,000 after one path: verify the business, have your partner verify it, or deliver 2,000 messages outside service windows to unique customers in 30 days with high-quality templates;
2. after that, Meta raises it one level (10,000, 100,000, unlimited) within 6 hours when message quality is high and at least half of the current limit was used in the last 7 days.

Quality rating. High, Medium, Low or No rating, based on how customers received the number's messages in recent days. Meta does not date a quality change; the tab shows the last change the platform observed between two checks.

Free service messages. The block uses an estimated monthly allowance of 1,000 service messages per number. Estimated monthly allowance; Meta does not publish this limit in the documentation tracked here. It shows estimated usage and remaining allowance based on Meta's delivery confirmations, which do not confirm that limit, and leads to the Costs tab. It appears only for users who may view WhatsApp costs.

Switch to manual setup

WhatsApp Manual Transfer must be enabled. This transition supports Cloud inboxes outside Coex: the server checks with Meta that the number is no longer on the Business App, verifies that the new identifiers represent the same phone and refuses an existing hybrid pair. Incomplete health data does not establish eligibility.

1. Configure the webhook in your Meta app before migrating. Meta only delivers the number's messages through an app that has a WhatsApp webhook configured; without one, the migration is refused. In your app's App Dashboard, open WhatsApp → Configuration (or Use cases → Customize → Configuration if the app was created with the WhatsApp use case) and:

• in Callback URL, paste the URL the wizard shows for this number;
• in Verify token, paste this inbox's verify token, also shown in the wizard, and click Verify and save;
• in Webhook fields, subscribe messages (and calls if the inbox receives calls). Also subscribe the recommended ones: account_update, smb_message_echoes, history, smb_app_state_sync, message_template_status_update, message_template_quality_update, template_category_update and user_preferences;
• keep the app in Live mode: in Development mode, Meta does not send some webhooks.

2. Run the wizard. Open Start manual migration in the inbox banner and follow the steps: business details (WABA and phone number IDs), a permanent System User access token, App Secret (optional, recommended), Webhook of your Meta app (copy the URL and the token and confirm you set them) and review.

3. The platform checks everything before saving. With the token you entered, it checks with Meta the app that owns the token, that the token does not expire, that it has whatsapp_business_management and whatsapp_business_messaging for this WhatsApp Business Account, and that the app's Callback URL points at this installation — template updates and account alerts always go to that URL. With the App Secret, it also checks that the secret belongs to the app and that messages is subscribed. Even without the App Secret, when Meta reports that the app is not subscribed to the message webhook, the migration is refused. If anything is missing, nothing is saved and the message says what to configure, naming the app.

App Secret. Find it in App settings → Basic. With it, the platform configures your app's WhatsApp webhook by itself during the migration (this installation's Callback URL, the verify token and the webhook fields, including messages), and step 1 becomes reference only. If your app already sends its webhooks to another system, nothing is changed: the migration is refused and the message shows the current address. With it, every webhook from your app also has its signature checked; without it, your app's webhooks are accepted without that check, and the Account Health tab warns about it. It is never shown again after saving.

Pending transfer. If Meta refuses the setup after the credentials were saved, the inbox shows the Manual transfer pending banner with the cause. When Meta refuses because the app has no webhook subscribed to messages, the banner names the app and shows the URL to configure. Fix it in the App Dashboard and use Retry transfer, entering the token again. With automatic webhook registration on, the retry redoes the setup even when Meta does not answer the preliminary check. If the platform cannot reach Meta at that moment, nothing is changed and the message asks you to try again in a few minutes.

4. Remove the previous app. After the migration, the installation's app is still subscribed to the WhatsApp Business Account and delivers the same webhooks as your app, so they arrive twice. In Account Health → Webhook, the platform lists the subscribed apps and shows the Remove the app action. Before removing it, it checks with Meta that your app is subscribed and delivers this number here, that no other inbox on the same account depends on the previous app, and that delivery was proven: a webhook signed with your App Secret arrived after the migration or, without an App Secret, you confirm that a test message arrived in the inbox. Meta stops delivering to the previous app immediately; you can undo the removal for 72 hours. When the platform can no longer remove the app for you, the notice asks you to remove it from the WhatsApp Business Account in Meta's tools.

Use Reconfigure to recover Coex or a hybrid inbox. Manual transfer does not remove a pair or silently replace the number served by the inbox.

A number another partner already uses

In Meta's account model in force since September 2026, a phone number can no longer be migrated between partners. To bring to the platform a number that another WhatsApp partner serves today:

1. The client shares the WhatsApp account that owns the number with the platform, through this Embedded Signup (choosing that number) or in Meta Business Suite. The number does not move and conversations continue.
2. The previous partner stays on the number until the client removes it in Meta Business Suite.
3. With two partners on the number, Meta routes each conversation to a single responder. Ask the client to open Conversation Routing in Meta Business Suite and set the platform as the primary responder for the entry points the team will handle (for example, Service).
4. Until then, the new inbox may receive no messages, even with the connection completed.

Meta's first screen asks for the number before any other choice. If the number is already in use in the WhatsApp Business app, Meta opens the coexistence flow by itself.

Use cases

• Connect a Cloud number to the platform for the first time.
• Renew Cloud or Coex authorization while preserving conversations and history.
• Move an eligible Cloud inbox to a manually managed Meta application.

Tips, limits & best practices

• Confirm the number and WABA before completing authorization.
• Preserve the existing inbox during recovery; creating another can separate its history.
• Test sending and receiving with a contact you control after setup or recovery. A pending configuration notice requires completing the indicated step.

Troubleshooting

• Popup cancelled or timed out: start the flow again for the same inbox.
• Creation option missing: check the feature and the installation's Meta app configuration.
• Cannot recover an inbox: check inbox management permission and its scope.
• Configuration pending: retry recovery, confirm the webhook and test actual inbound delivery.
• The migration was refused because the app has no webhook: set the Callback URL, the verify token and the messages field in the App Dashboard of the named app and try again. Nothing was saved.
• The App Secret was refused: copy it from App settings → Basic of the same app as the token, or leave the field empty.
• Messages and events arrive twice after the migration: the previous app is still subscribed. Remove it in Account Health → Webhook.
• Different number: select the number already linked to this inbox; recovery cannot replace it.
• The inbox was connected but receives no messages: the number probably still has another partner as the primary responder. Ask the client to adjust Conversation Routing in Meta Business Suite.
• Sending status Limited or Blocked: follow What to do on the indicated item. The texts come from Meta; after fixing it in WhatsApp Manager, use Check now.
• Sending speed Not confirmed: Meta has not confirmed the level in the last 24 hours. Use Check now; meanwhile the standard limit of 80 messages per second applies.

See also

• WhatsApp conversation routing: Meta Business Agent and other partners
• WhatsApp Cloud Coexistence
• WhatsApp hybrid inbox