# 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](https://docs.polymorfa.com/numbers/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

1. Create a QuickLink whose `connectionPreference` offers `cloud`, or force it
   with `"connectionPreference": "cloud", "connectionEnforcement": "force"`.
   See [Connect a number with QuickLink](https://docs.polymorfa.com/numbers/quicklink#connection-preference).
2. Send the link to the person who manages the business's Meta assets.
3. They confirm the phone number, choose Meta Cloud API and complete Embedded
   Signup.
4. Polymorfa runs the [readiness checks](#readiness-checks). The link stays
   `linked` while they run.
5. 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`](https://docs.polymorfa.com/api/errors#whatsapp-authorization-required),
[`whatsapp_payment_method_required`](https://docs.polymorfa.com/api/errors#whatsapp-payment-method-required)
or [`whatsapp_number_not_registered`](https://docs.polymorfa.com/api/errors#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.

1. Subscribe a project webhook to `history.sync`, `contact.sync` and
   `message.echo`. QuickLink settings remind you to configure a destination.
2. Create the link with a history consent of `ask` or `force_on`.
3. Track progress through those webhooks or the link's `onboarding` status.

`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](https://docs.polymorfa.com/messaging/history). 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.

1. Create the QuickLink.
2. Confirm the phone with
   [Confirm QuickLink phone](https://docs.polymorfa.com/api/quicklinks/confirm-quick-link-phone)
   (`POST /quicklink/{token}/phone`).
3. If both connection types are offered, select Meta Cloud API with
   [Select QuickLink connection](https://docs.polymorfa.com/api/quicklinks/select-quick-link-connection)
   and `{ "connection": "cloud" }`. A link that allows only Cloud selects it
   after phone confirmation.
4. For an initial link with history consent `ask` or `force_on`, record the
   recipient's choice with
   [Choose QuickLink history](https://docs.polymorfa.com/api/quicklinks/choose-quick-link-history)
   and `{ "historySync": true }` or `false`. Advancing while consent is pending
   returns `409`.
5. Call [Embedded signup](https://docs.polymorfa.com/api/cloud-api/embedded-signup)
   (`POST /messaging/cloud-api/embedded-signup`) with the `quicklinkId`.
   Include `result` when you submit the Embedded Signup result. To request
   history after the recipient accepted, set `result.historySync` to `true`.
6. Poll [Get a QuickLink](https://docs.polymorfa.com/api/quicklinks/get-quick-link) until
   `onboarding.stage` is `connected`.
7. Call [Confirm QuickLink](https://docs.polymorfa.com/api/quicklinks/confirm-quick-link)
   (`POST /quicklink/{token}/confirm`). 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](https://docs.polymorfa.com/api/numbers/get-cloud-credential-health)
with `GET /messaging/{session}/cloud-credentials`. `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

1. [Stop the Number](https://docs.polymorfa.com/numbers/manage#start-stop-and-restart).
2. With a project token that has `quicklink:manage`, call
   [Reauthorize cloud credentials](https://docs.polymorfa.com/api/numbers/reauthorize-cloud-credentials)
   (`POST /messaging/{session}/cloud-credentials/reauthorize`).
3. 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.
4. Track it with [Get a QuickLink](https://docs.polymorfa.com/api/quicklinks/get-quick-link).
   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](https://docs.polymorfa.com/api/graph):

1. Send requests to `https://api.polymorfa.com/graph/whatsapp/v26.0` instead
   of Meta's Graph host, with the same version segment.
2. Authenticate with a Polymorfa team key or project token instead of a Meta
   access token.
3. Keep the phone number IDs and WhatsApp Business Account IDs Meta assigned
   to your Numbers.
4. Create a webhook with `format: "meta"` so your webhook consumer keeps
   receiving Meta's envelope. See
   [Delivery formats](https://docs.polymorfa.com/development/webhooks#delivery-formats).

Each task guide states what the Graph API supports for the task. For example,
see [Send messages](https://docs.polymorfa.com/messaging/send) and
[Message templates](https://docs.polymorfa.com/messaging/templates).

### Phone numbers through the Graph API

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Partly supported.

Registration and verification work only for Meta Cloud API Numbers. Linked
Devices Numbers return capability error `131026` for them.

| Method | What it does |
| --- | --- |
| [List phone numbers](https://docs.polymorfa.com/api/graph/phone-numbers/list-phone-numbers) | Lists your project's Numbers recorded under a WhatsApp Business Account, in Meta's phone-number shape. Needs `sessions:read`. |
| [Register](https://docs.polymorfa.com/api/graph/phone-numbers/register), [Deregister](https://docs.polymorfa.com/api/graph/phone-numbers/deregister) | Registers or deregisters a Meta Cloud API Number with Cloud API. |
| [Request code](https://docs.polymorfa.com/api/graph/phone-numbers/request-code), [Verify code](https://docs.polymorfa.com/api/graph/phone-numbers/verify-code) | Requests and checks a verification code for the number. |

```bash Graph API
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`](https://docs.polymorfa.com/api/errors#whatsapp-number-not-registered)
until the number is registered again. Connecting a new Number still goes
through a [QuickLink](#connect-a-number); the Graph API has no Embedded Signup.

## See also

- [Connect a number with QuickLink](https://docs.polymorfa.com/numbers/quicklink)
- [Graph API reference](https://docs.polymorfa.com/api/graph)
- [Message templates](https://docs.polymorfa.com/messaging#templates)
- [Errors](https://docs.polymorfa.com/api/errors)
