Set up Meta Cloud API connections
Connect Numbers through Meta's Cloud API, use your own Meta app and keep credentials valid.
A Meta Cloud API Number runs on Meta's Cloud API instead of a linked device. The business completes Meta's Embedded Signup inside a QuickLink, and Polymorfa checks the WhatsApp Business Account before the Number starts. Meta bills the business's WhatsApp Business Account directly for messaging.
Before you begin#
- Meta Cloud API onboarding requires access for your team, and the project must be active. Configuring Meta app IDs alone does not turn it on. Without access, Meta Cloud API choices are hidden from QuickLinks, and a project that forces Meta Cloud API cannot issue a link.
- The business needs a WhatsApp Business Account with a payment method, managed by someone who can complete Embedded Signup.
- Choose how the phone is used. Meta Cloud API setup offers Keep using the WhatsApp Business app for an eligible existing app number (coexistence), or Use WhatsApp without the Business app for a new or existing Cloud API number.
Withdrawing access stops new onboarding and history requests. Operations Meta already accepted are still reconciled. A pending link can then report cloud_onboarding_unavailable; this does not report success or delete Meta assets.
Connect a Number#
- Create a QuickLink whose
connectionPreferenceofferscloud, or force it with"connectionPreference": "cloud", "connectionEnforcement": "force". See Connect a number with QuickLink. - Send the link to the person who manages the business's Meta assets.
- They confirm the phone number, choose Meta Cloud API and complete Embedded Signup.
- Polymorfa runs the readiness checks. The link stays
linkedwhile they run. - The recipient confirms and the link becomes
connected.
Meta decides which number options Embedded Signup offers. With no pre-filled number, eligible links can open Meta's number setup. Polymorfa does not guarantee that Meta accepts a supplied number.
The readiness checks do not send a message. Send and receive a test message before you use the Number.
Readiness checks #
After Meta accepts event delivery for the WhatsApp Business Account, Polymorfa checks the Number before starting it. The first check that fails moves the link to failed with its own errorCode, and the Number does not start.
| Check | Passes when Meta reports | errorCode when it fails | Recovery |
|---|---|---|---|
| Access | The saved access token is valid, belongs to the Meta app and grants whatsapp_business_messaging and whatsapp_business_management for this account. | meta_credentials_invalid | The team owner checks the app's permissions in Meta Business Suite, then creates a new link. |
| Phone registration | The number's status is CONNECTED on Cloud API. | meta_phone_not_registered (status BANNED, DELETED, DISCONNECTED, MIGRATED, RESTRICTED or RATE_LIMITED, or another platform) | The account owner checks the number in WhatsApp Manager, then creates a new link. |
| Webhook subscription | The Meta app is subscribed to the account with the Polymorfa callback. | meta_webhook_not_subscribed | The team owner checks the app's webhook subscription, then creates a new link. |
| Payment method | The WhatsApp Business Account has a payment method. | meta_payment_method_missing | The account owner adds a payment method in WhatsApp Manager under Overview, then creates a new link. |
| Quality | The number is not FLAGGED and its quality rating is not RED. A new number without a rating passes. | meta_quality_flagged | The account owner checks the quality rating in WhatsApp Manager and creates a new link after Meta clears the flag. |
When Meta does not answer a check, for example during a Meta outage, the link stays linked and onboarding.errorCode is meta_readiness_unknown. Polymorfa checks again every two minutes and continues when Meta answers. You can cancel the link while it waits. If the link expires first, it fails with meta_readiness_unknown.
The checks run once, during setup. Afterwards, sends return a specific error when Meta reports a problem: whatsapp_authorization_required, whatsapp_payment_method_required or whatsapp_number_not_registered.
Onboarding errors#
errorCode | Meaning | What to do |
|---|---|---|
meta_registration_rejected | Meta refused number registration. | Correct the registration restriction before another attempt. |
existing_cloud_registration_unverified | Meta did not report the number as connected to Cloud API or ready for a new registration. Polymorfa stops before sending a registration PIN, so a PIN held by the current provider is not replaced. | The account owner resolves the registration and PIN with that provider, then creates a new link. |
meta_subscription_rejected | Meta refused the WhatsApp Business Account webhook subscription. | Correct the app permissions or account access, then create a new link. |
meta_subscription_status_unknown | Meta reports a different webhook callback for the Polymorfa app on that account. Polymorfa does not overwrite it and checks again every 10 minutes. | Ask the account owner to check the app's webhook subscription, or cancel the link. |
cloud_start_failed | The Meta Cloud API connection could not start. | Correct the reported restriction, then create a new link. Polling the failed link does not retry startup. |
sync_status_unknown | Meta did not confirm a contacts or history request. The connection can stay active. | Check incoming history events and contact support with the QuickLink ID. Do not create another link to retry the import. |
An uncertain request or subscription result stays pending until it can be reconciled. If Meta signup times out before returning its result, check the link's status and reload the page before starting another signup.
Receive history from a coexistence Number#
When the business keeps using the WhatsApp Business app, Meta can share chat history and contacts once.
- Subscribe a project webhook to
history.sync,contact.syncandmessage.echo. QuickLink settings remind you to configure a destination. - Create the link with a history consent of
askorforce_on. - Track progress through those webhooks or the link's
onboardingstatus.
history.sync delivers Meta's refusal, progress and history batches. Cloud history payloads contain kind: "history" and value. contact.sync contains kind: "contacts" and value. message.echo reports messages sent from the Business app with source: "whatsapp_business_app" and value.
The business can decline history sharing in WhatsApp even when the link asks for it. Confirming the connection does not wait for the import, and an accepted request is separate from a completed import. History sync never turns on hosted message storage. When storage is on, media references marked mediaStorage: "not_fetched" do not mean the media bytes were stored.
A one-time contacts sync with an uncertain result cannot be confirmed from a later contact-change event. Contact support before retrying. Repeating Meta's one-time sync can require the business to disconnect the Meta Cloud API connection and complete Embedded Signup again, which interrupts that connection.
Drive Meta signup from your server#
To run Embedded Signup in your own interface, advance a QuickLink from your backend with a credential that has quicklink:manage and access to the link's project.
- Create the QuickLink.
- Confirm the phone with Confirm QuickLink phone (API Confirm quick link phone).
- If both connection types are offered, select Meta Cloud API with Select QuickLink connection and
{ "connection": "cloud" }. A link that allows only Cloud selects it after phone confirmation. - For an initial link with history consent
askorforce_on, record the recipient's choice with Choose QuickLink history and{ "historySync": true }orfalse. Advancing while consent is pending returns409. - Call Embedded signup (API Embedded signup) with the
quicklinkId. Includeresultwhen you submit the Embedded Signup result. To request history after the recipient accepted, setresult.historySynctotrue. - Poll Get a QuickLink until
onboarding.stageisconnected. - Call Confirm QuickLink (API Confirm quick link). Confirmation finishes the link, completes any attached Customer pairing and returns the success URL.
The Embedded Signup call uses the link's reserved Number and saved Meta app settings; it cannot choose another Number or supply app credentials. A link that adds Meta Cloud API to an existing Number reuses that Number's history decision. Console-only links and test numbers cannot use this endpoint. For a Hybrid Link, complete Linked Devices pairing for the same Number and wait for hybridPhase: "ready" before confirming.
Use your own Meta app#
Teams with an active Branded QuickLink add-on and Meta Cloud API onboarding access can connect their own Meta app and Embedded Signup configuration. QuickLinks then run signup under your app. Your app needs the Meta permissions and approvals for the numbers you connect; saving credentials does not grant them.
- The app secret is submitted once and is never returned.
- Replacing a configuration applies to new links. Existing links keep their saved app.
- Disconnecting asks you to confirm, then revokes saved configurations for unfinished onboarding. It does not delete customer-owned Meta assets or disconnect established Numbers.
- A payment dispute blocks use of the saved app until it is resolved. Its settings stay visible.
Saving a team-owned Meta app without the add-on returns 403.
When Branded QuickLink ends #
Your app stays in use while the add-on is active, after you cancel renewal until the paid period ends, and during the three-day recovery period after a failed renewal payment. When access ends:
- New QuickLinks and Customer invitations use Polymorfa's standard Meta app and presentation, according to the project's connection policy.
- Unfinished links issued with your app stop before their next Meta step. Send a new link.
- Connected Numbers keep running. Polymorfa does not stop, disconnect or delete a Number because the add-on ended or because you disconnected your app.
- Your saved configuration is kept until you disconnect it, and is used again when the add-on is active again.
Team members receive a billing notice when a cancellation is scheduled, when a renewal payment fails (with the recovery deadline) and when access ends. Delivery follows your notification preferences.
Check and renew credentials#
Polymorfa periodically validates the saved Meta credentials of each Meta Cloud API Number. A check confirms that the access token is valid, has the whatsapp_business_messaging and whatsapp_business_management permissions for the account, that Meta reports the phone number as connected, and that the app is subscribed to the account's webhooks. A check only reads from Meta; it never stops or restarts the Number.
Read the latest result#
Call Get cloud credential health with API Get cloud credential health. checkedAt is the time of the last completed check.
status | Meaning |
|---|---|
healthy | Every check passed. |
action_required | A check failed. failureCode names the first failure. |
unknown | Meta could not be reached or returned an incomplete answer. The check is retried sooner. |
pending | The credentials have not been checked since they were saved. |
failureCode is one of token_expired, token_invalid, token_app_mismatch, app_credentials_rejected (the saved app secret no longer matches the Meta app), permission_missing, phone_not_registered, webhook_not_subscribed, credentials_unreadable, meta_unavailable or meta_response_invalid.
Renew the authorization#
- Stop the Number.
- With a project token that has
quicklink:manage, call Reauthorize cloud credentials (API Reauthorize cloud credentials). - Share the returned QuickLink with the person who manages the Number's Meta assets. It is bound to the same Number and phone number, always uses Meta Cloud API, and uses your own app while Branded QuickLink is active.
- Track it with Get a QuickLink. Its purpose is
reauthorization.
After Embedded Signup, the Number starts with the renewed credentials and is checked again within minutes. A reauthorization link checks access, phone registration and the webhook subscription, but not the payment method or quality.
A reauthorization link must select the same WhatsApp Business Account and Cloud API number that the Number already uses. Selecting another account or number fails with reauthorization_asset_mismatch, and the existing Number stays in Polymorfa.
When Meta Cloud API setup fails for a reason without its own recovery step, the hosted page says that setup did not finish and asks the recipient to have the link creator check the Number's status before requesting a new link. A Hybrid Link that fails during Official API setup stops. It does not continue with Linked Devices only.
You can cancel the link before Meta work starts; the Number stays in your project. After Meta work starts, cancellation returns 409. Reauthorization returns 409 state_conflict while the Number is running, and 501 operation_not_supported for a Number that also has a linked-device connection. Both credential endpoints return 403 feature_unavailable without Meta Cloud API onboarding access.
Move a Meta Cloud API integration #
An integration built on Meta's Cloud API can keep its requests and move to Polymorfa through the Graph API:
- Send requests to
https://api.polymorfa.com/graph/whatsapp/v26.0instead of Meta's Graph host, with the same version segment. - Authenticate with a Polymorfa team key or project token instead of a Meta access token.
- Keep the phone number IDs and WhatsApp Business Account IDs Meta assigned to your Numbers.
- Create a webhook with
format: "meta"so your webhook consumer keeps receiving Meta's envelope. See Delivery formats.
Each task guide states what the Graph API supports for the task. For example, see Send messages and Message templates.
Phone numbers through the Graph API#
| Method | What it does |
|---|---|
| List phone numbers | Lists your project's Numbers recorded under a WhatsApp Business Account, in Meta's phone-number shape. Needs sessions:read. |
| Register, Deregister | Registers or deregisters a Meta Cloud API Number with Cloud API. |
| Request code, Verify code | Requests and checks a verification code for the number. |
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/phone_numbers" \
-H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"Registration and verification need messages:write. Polymorfa forwards their request bodies to Meta unchanged, so send the body Meta documents for each method. Deregistering a Number takes it off Cloud API: sends then fail with whatsapp_number_not_registered until the number is registered again. Connecting a new Number still goes through a QuickLink; the Graph API has no Embedded Signup.