Messaging
Connect WhatsApp
Attach a merchant’s WhatsApp Business Account to their project through a hosted page — no Meta code, business token or PIN ever touches your servers.
Hosted connect lets your integration connect a merchant’s WhatsApp Business Account to the key’s project without handling anything from Meta. You ask for a link, open it for the merchant, and Trovacast’s own page runs Meta’s Embedded Signup — including the number’s two-step PIN when Meta asks for one. Your server only follows the session’s status.
your server ── POST /v1/whatsapp/connect-sessions ──▶ { id, url, expiresAt }
your app ── window.open(url) ──▶ the hosted Trovacast page
merchant ── Meta's popup ──▶ Trovacast connects the account, asks for the PIN if needed
your server ── GET /v1/whatsapp/connect-sessions/{id} until it settlesCreate a session
POST /v1/whatsapp/connect-sessions needs whatsapp:manage. returnUrl (optional) is where the page offers a “Back to …” button when the merchant is done: an https URL whose origin the deployment allows (in production, the Shopify admin) — anything else is 400 RETURN_URL_NOT_ALLOWED.
curl -X POST 'https://api.trovacast.com/v1/whatsapp/connect-sessions' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: connect-click-7f3a' \
-H 'Content-Type: application/json' \
-d '{
"returnUrl": "https://admin.shopify.com/store/example/apps/trovacast"
}'{
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"url": "https://trovacast.com/connect/whatsapp#t=…",
"status": "CREATED",
"expiresAt": "2026-11-06T10:00:00.000Z"
}Follow the session
Poll GET /v1/whatsapp/connect-sessions/{sessionId} every few seconds while the window is open (or GET /v1/whatsapp/account until it reports the account connected); whatsapp.account.updated webhooks report the connection too. Stop on REGISTERED, on CONNECTED with a registration other than PIN_REQUIRED, on FAILED or on EXPIRED.
| `status` | Meaning |
|---|---|
CREATED | Issued, not opened yet. The link must be opened within 24 hours. |
OPENED | The merchant has the page open. From the first open, the whole signup — Meta’s popup and the PIN — must finish within 10 minutes (activeUntil). |
CONNECTED | The account is connected. With registration: "PIN_REQUIRED" the page is waiting for the number’s PIN; with "NOT_REQUESTED" Meta reported no number and the session is final (add a number in WhatsApp Manager). |
REGISTERED | Done: the number is on the Cloud API (registration is NOT_REQUIRED — it already was — or REGISTERED, with its PIN, here). |
FAILED | Ended without connecting; failureReason is CANCELLED, META_ERROR, CONNECT_FAILED, PIN_ATTEMPTS_EXHAUSTED, NUMBER_UNAVAILABLE, KEY_INVALID (the issuing key was revoked, expired or lost whatsapp:manage, or the project is no longer active) or NOT_ENTITLED (messaging was switched off). |
EXPIRED | Ran out of time before settling. |
{
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"status": "CONNECTED",
"registration": "PIN_REQUIRED",
"failureReason": null,
"returnUrl": "https://admin.shopify.com/store/example/apps/trovacast",
"expiresAt": "2026-11-06T10:00:00.000Z",
"activeUntil": "2026-11-05T10:12:00.000Z",
"createdAt": "2026-11-05T10:00:00.000Z"
}FAILED and EXPIRED are final: offer “Try again”, which issues a new session. A session completes at most once, and it acts as the key that issued it — revoking that key, suspending the project or switching messaging off ends its open links immediately. Any key of the same project may read a session; another project’s id is a 404.
Endpoints
- POST
/v1/whatsapp/connect-sessionsCreates a hosted WhatsApp connect link - GET
/v1/whatsapp/connect-sessions/{sessionId}Where a hosted WhatsApp connect session stands - GET
/v1/whatsapp/accountThe WhatsApp connection: status, numbers, display-name review, quality, messaging limit and billing currency - POST
/v1/whatsapp/account/disconnectDisconnects the WhatsApp account (idempotent); sending stops until it is connected again
Events
| Event | When it is sent | Key scopes |
|---|---|---|
whatsapp.account.updated | The WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, change | whatsapp:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
API_KEY_SCOPE_MISSING | 403 | The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed. |
ENTITLEMENT_MESSAGING_DISABLED | 403 | Messaging is not enabled for this project (it is calling-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn messaging on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then. |
NOT_FOUND | 404 | No such resource for this key: another project's id is indistinguishable from one that does not exist. Some endpoints name what is missing with a more specific 404 code; treat any 404 as not found.What to do: Check the id, and that the key belongs to the project and mode that hold it — a test key reads only test records, a live key only live ones. Do not retry unchanged. |
RETURN_URL_NOT_ALLOWED | 400 | A connect session’s returnUrl is not an https URL on an origin this deployment allows.What to do: Use an https returnUrl on an allowed origin — contact us to have yours added — or leave returnUrl out. |
WHATSAPP_CONNECT_UNAVAILABLE | 503 | Hosted connect is not configured on this deployment, or its session store is unavailable. No link was issued.What to do: Retry with backoff — with the same Idempotency-Key if you like: the key is released, not spent. If it persists, contact us. |