Remote pairing — hosted pairing link

For SaaS platforms that manage numbers for end customers, Remote Pairing lets you generate a pairing link instead of displaying the QR code yourself. Your customer opens the link, scans the QR (or runs Meta Embedded Signup), and the number connects to your account.

Pairing Link modal with the hosted connect link — A remote pairing session — send the hosted link to your customer; when they scan the QR, the number.connected webhook fires.

POST /v1/numbers/remote-pairing

Same body as POST /v1/numbers, plus pairing-specific options:

curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "Customer João",
    "number": "+5511999999999"
  }'

Response 201:

{
  "provider": "PILOT_STATUS",
  "instance": { "id": "wa_abc", "instanceName": "PS-5511999999999-0", "number": "5511999999999", "displayName": "Customer João", "state": "CLOSE" },
  "remotePairingUrl": "https://pilotstatus.com.br/connect/abc123-def456-...",
  "maskedNumber": "+5511****9999",
  "linkedApiKeyId": null
}

Differences from POST /v1/numbers:

The instance is created in CLOSE state (disconnected) — no QR code is returned.
remotePairingUrl is the public link for the end customer. The endpoint only hands the link back — you deliver it to your customer yourself (your own UI, email, chat, wherever they are).
When the end customer opens the URL and connects, the number.connected webhook fires normally.

`linkToApiKey` — retired

Accepted but does nothing. Sending it is not an error, and no API key is touched: linkedApiKeyId in the response is always null. It used to re-point a number-scoped key at the number you had just paired, silently unscoping it from the number it was bound to.

`warnings` on the `201`

A successful pairing may come back with a warnings array of strings. It is present only when there is something to report. For provider=PILOT_STATUS, externalRef and redirectUrl are accepted but cannot be honored: they ride the Meta signed session, and the QR pairing link carries no session. Each one you send is reported in warnings — and the pairing still succeeds. It is not a 400:

{
  "provider": "PILOT_STATUS",
  "remotePairingUrl": "https://pilotstatus.com.br/connect/abc123-def456-...",
  "warnings": ["redirectUrl is only supported for provider=META and was ignored"]
}

They used to be discarded in silence. If you need either of them, use provider=META — the Meta branch is the one that carries them through the signed session.

History: decide it on this call

Whoever opens the link connects on the spot, and the provider hands the device history over right after — once. There is no moment in between for a PATCH, so this route accepts the settings block of number settings, for both providers:

curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{ "provider": "META", "settings": { "historyImportEnabled": false } }'

Response 201 for META:

{
  "provider": "META",
  "numberId": "num_01HZX...",
  "remotePairingUrl": "https://connect.pilotstatus.com.br/connect/eyJhbGciOi...",
  "expiresAt": "2026-09-16T14:06:38.000Z",
  "settings": {
    "historyImportEnabled": false,
    "webhookHistoricalMessages": false,
    "ignoreNewsletters": false,
    "alwaysOnline": null,
    "rejectCall": null,
    "msgRejectCall": null,
    "readMessages": null,
    "ignoreGroups": null,
    "ignoreStatus": null,
    "appliesTo": { "history": "all", "advanced": "none" }
  }
}

settings.historyImportEnabled defaults to true. Omit the block to keep the device history; send false to drop it.
numberId is the placeholder the connection lands on. Use it to follow the connection (GET /v1/numbers/{id}/status) or to PATCH it before the person finishes.
An invalid block answers 400 INVALID_SETTINGS and nothing is created.
For PILOT_STATUS, the block is applied only when this call creates the number.

Changed on 2026-09-16. Before that, provider=META ignored settings without a word and the 201 carried no numberId: the only way to set history on a Meta link was a PATCH on the placeholder, with the id taken from inside the link’s token. Read numberId from the body — the token is an internal format and can change.

Per-link branding (white-label)

The body also accepts an optional branding object to override the connect page’s logo/colors/title for just this link (snapshotted onto the token). It overrides the tenant’s saved branding. See Connect page branding.

Meta numbers: `metaFlow`

For official Meta Cloud API numbers the pairing link can run Meta flows instead of QR pairing:

metaFlow: "embedded" — the hosted page runs Meta Embedded Signup. Whoever opens the link authenticates with Facebook inside Meta’s own dialog and picks the business portfolio and the phone number there.
metaFlow: "credentials" — the hosted page collects an existing WABA’s credentials. It also shows a route inbound webhooks to Pilot Status checkbox (on by default) that auto-subscribes that WABA to Pilot’s callback, so no manual webhook setup is needed — see webhook delivery.

Who authenticates decides who owns the WABA

The hosted page runs the same Embedded Signup component the dashboard runs, with the same app and the same configuration. Nothing in the pairing token pins a business portfolio. So the WABA lands in the portfolio of whoever logs into Facebook in that dialog — the end customer if they open the link, or you if an operator on your team opens it and selects your own portfolio. If your model is “the WABA is ours and we pay Meta”, have your operator run the link; if it is “the customer owns their WABA”, send the link to the customer. The API call is identical either way.

Embedded Signup here is configured with featureType: "whatsapp_business_app_onboarding" — Meta’s coexistence onboarding. The dialog shows the QR the number’s owner scans with the WhatsApp Business app on their phone, so the phone still has to be reachable at that moment, whoever is driving the dialog.

The portfolio picker does not appear for the Facebook profile that owns the developer app. That is Meta’s rule, not a bug: a portfolio that owns the app is excluded from its own Embedded Signup, and Meta hides an empty picker. Any other profile — including yours as a customer of this platform — sees it. If you are testing, use a Facebook profile with no role on the app.

`POST /v1/numbers/meta` — the BYO-WABA alternative

If you already hold metaPhoneId + metaWabaId + a system-user token server-side, POST /v1/numbers/meta attaches the number with no link and no end-customer interaction. It is agnostic about coexistence — it attaches a coexistence number and a pure Cloud API number alike. What it does not do is anything Embedded Signup does for you:

	Embedded Signup (`remote-pairing`, `metaFlow: "embedded"`)	`POST /v1/numbers/meta`
Creates the WABA / runs the coexistence QR	Yes — inside Meta’s dialog	No. The WABA and the phone number must already exist
Requests the on-device history sync	Yes	No
Records `metaIsCoexistence`	Yes, from Meta’s answer to that request	No — stays `null`
`coexistence.evidence` right after	`history_sync`, upgraded to `meta_is_on_biz_app` on the first `?refresh=1`	`UNKNOWN` until the first `?refresh=1`

BYO-WABA cannot perform the coexistence pairing itself. Turning a phone that is live in the WhatsApp Business app into a Cloud API number happens inside Meta’s Embedded Signup dialog — there is no API for it, ours or Meta’s. POST /v1/numbers/meta is how you register a number that pairing already produced, not how you pair one.It also never asks Meta for the on-device history, so nothing is imported for that number. If you need the history, pair through Embedded Signup.

Link lifetime: two different TTLs

The two providers mint two different credentials, and they do not expire on the same clock.

Provider	Credential	Lifetime
`META`	Signed Embedded Signup session, returned as `expiresAt` on the `201`	30 minutes
`PILOT_STATUS`	QR pairing token on the number row	24 hours, or until the number connects (single-use)

Read expiresAt off the 201 rather than hardcoding either number. For a META link, the number also shows up immediately as a placeholder whose GET /v1/numbers/{id}/status answers PENDING and then EXPIRED — that is the signal to show your customer an “the link expired” message and mint a new one.

The connect page origin (`postMessage`)

When you embed the connect page in your own site, it talks to the host page over postMessage (connect:paired, connect:error, connect:expired). Both providers use the same host — it comes from one platform-wide setting, not from the provider — and in production that host is:

https://connect.pilotstatus.com.br

Lock your listener to it, and reject every other origin.

Better than hardcoding it: derive it from the link the API just handed you — new URL(response.remotePairingUrl).origin. The host is a deployment setting; a receiver pinned to a literal breaks silently if it ever changes, while one derived from remotePairingUrl cannot drift.

Errors

Status	Body	Meaning
`400`	`{ "error": "Validation error", "details": … }`	Invalid body. For `provider=PILOT_STATUS`, `name` and `number` are both required.
`402`	`{ "error": "PLAN_NUMBER_LIMIT_REACHED", "code": "PLAN_NUMBER_LIMIT_REACHED", … }`	The plan’s own number allowance is full. On the Free plan money does not clear it — free a slot, buy an extra number yourself or move up a plan — and it is also the answer when the phone already exists in your workspace but never connected. On a paid plan it is answered only when no extra number was ever bought and the next one cannot be funded: credits or a saved card do clear it.
`402`	`{ "error": "INSUFFICIENT_FUNDS", "code": "INSUFFICIENT_FUNDS", … }`	Paid plans only. The next number is a paid extra and there is neither wallet balance nor a saved card.
`403`	`{ "error": "…", "code": "NUMBERS_GRANT_NOT_ALLOWED" }`	A per-number OAuth connection cannot pair new numbers.

Both 402s carry the numbers behind the refusal — plan, maxNumbers, currentNumberCount, extras, proratedTotal, walletBalance and currency — alongside error and code. The Free-plan refusal for a phone that already exists carries only plan, maxNumbers and currentNumberCount. Branch on the code: the two share a status but not a remedy. See capacity errors.

Fixed: INSUFFICIENT_FUNDS on this route now answers 402, the same status as POST /v1/numbers. It used to come back as a 500.

Changed. A plan whose allowance was simply full used to answer INSUFFICIENT_FUNDS here too, and the body carried nothing but the code repeated in both fields. It now answers PLAN_NUMBER_LIMIT_REACHED, with the capacity figures attached.

Public token endpoints (no authentication)

The pairing page uses these token-based endpoints — you can also call them to build your own connect UI:

Method	Endpoint	Returns
`GET`	`/v1/remote-pairing/{token}`	`{ valid, name, maskedNumber, state, branding }`
`POST`	`/v1/remote-pairing/{token}/connect`	`{ qrcodeBase64, pairingCode }` — or `402 PLAN_NUMBER_LIMIT_REACHED` on a full Free plan (see the notes)
`GET`	`/v1/remote-pairing/{token}/status`	`{ state, isFullyConnected }`
`GET`	`/v1/connect/{token}/branding`	`{ branding }` (also used by the Meta Embedded Signup flow)

Notes:

Free plan: when the workspace that issued the link is on Free, its allowance is already full and this number never connected, POST /v1/remote-pairing/{token}/connect answers 402 with { "error": "PLAN_NUMBER_LIMIT_REACHED", "code": "PLAN_NUMBER_LIMIT_REACHED", "message": "…", "plan": "FREE", "maxNumbers": 1, "currentNumberCount": 1 }, and no QR code is generated. message is a bilingual sentence, English | Português. The person holding the link cannot fix it: the workspace has to buy an extra number or move up a plan. See Free plan.
This is the PILOT_STATUS (QR) token: it expires after 24 hours or upon successful connection (single-use). A META Embedded Signup link is a different credential with a 30-minute TTL — see Link lifetime.
POST .../connect only works when the state is not OPEN.
The same connection state shown in the dashboard and the webhooks (number.created, number.connected) apply.

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

POST /v1/numbers/remote-pairing — Hosted Pairing Link

Remote pairing — hosted pairing link

POST /v1/numbers/remote-pairing

`linkToApiKey` — retired

`warnings` on the `201`

History: decide it on this call

Per-link branding (white-label)

Meta numbers: `metaFlow`

Who authenticates decides who owns the WABA

`POST /v1/numbers/meta` — the BYO-WABA alternative

Link lifetime: two different TTLs

The connect page origin (`postMessage`)

Errors

Public token endpoints (no authentication)

​Remote pairing — hosted pairing link

​POST /v1/numbers/remote-pairing

​linkToApiKey — retired

​warnings on the 201

​History: decide it on this call

​Per-link branding (white-label)

​Meta numbers: metaFlow

​Who authenticates decides who owns the WABA

​POST /v1/numbers/meta — the BYO-WABA alternative

​Link lifetime: two different TTLs

​The connect page origin (postMessage)

​Errors

​Public token endpoints (no authentication)

Remote pairing — hosted pairing link

POST /v1/numbers/remote-pairing

`linkToApiKey` — retired

`warnings` on the `201`

History: decide it on this call

Per-link branding (white-label)

Meta numbers: `metaFlow`

Who authenticates decides who owns the WABA

`POST /v1/numbers/meta` — the BYO-WABA alternative

Link lifetime: two different TTLs

The connect page origin (`postMessage`)

Errors

Public token endpoints (no authentication)