Trovacast

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.

The flow (text)
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 settles

Create 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.

Issue a connect link
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"
}'
201 Created (json)
{
  "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
CREATEDIssued, not opened yet. The link must be opened within 24 hours.
OPENEDThe merchant has the page open. From the first open, the whole signup — Meta’s popup and the PIN — must finish within 10 minutes (activeUntil).
CONNECTEDThe 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).
REGISTEREDDone: the number is on the Cloud API (registration is NOT_REQUIRED — it already was — or REGISTERED, with its PIN, here).
FAILEDEnded 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).
EXPIREDRan out of time before settling.
200 OK — waiting for the PIN (json)
{
  "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

Events

EventWhen it is sentKey scopes
whatsapp.account.updatedThe WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, changewhatsapp:read

Errors

CodeStatusMeaning and what to do
API_KEY_SCOPE_MISSING403The 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_DISABLED403Messaging 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_FOUND404No 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_ALLOWED400A 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_UNAVAILABLE503Hosted 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.