Skip to main content

​
Check connection status

GET /v1/numbers/{id}/status returns the live connection state of one WhatsApp number.
Response:
This endpoint reflects the same connection state shown on the Numbers page in the dashboard (as does GET /v1/numbers/{id}/connect).

​
When to use it

  • GET /v1/numbers does not force a mass refresh of connection state — call this endpoint per number when you need an up-to-date check.
  • Poll it after showing a QR code / pairing code to detect when the customer completes the connection (or rely on the number.connected webhook instead).

​
States

Treat state === "OPEN" as the definitive “ready to send” flag.
A 200 does not mean connected. A number created through Meta remote pairing answers 200 with PENDING from the moment the link is generated. Branch on state, never on the HTTP status alone.

​
Meta remote pairing: PENDING, EXPIRED and expiresAt

POST /v1/numbers/remote-pairing with provider: "META" creates the number right away, so it shows up as “awaiting connection” while your end user is still inside the Facebook dialog. Polling its status during that window answers:
expiresAt is the end of the pairing window. After it passes, the same call answers state: "EXPIRED" — the number will never connect on its own, so stop polling and generate a new link. A number in this state is not billed (it is excluded from your plan’s number count and from your capacity) and is removed automatically 24h after it was created, so abandoned signups do not pile up in GET /v1/numbers.
Previously both cases answered 404, indistinguishable from an id that does not exist, which left polling loops with no way to tell “still waiting” from “gone”.

​
How fresh is the answer: stale, checkedAt, lastKnownAt

Every 200 carries stale, plus exactly one of the two timestamps: stale: true always comes with state: "OPEN". The remembered value is only served when the stored state was already OPEN; for a number that was not OPEN, a provider that does not answer produces a 503 instead (see below). Meta (official Cloud API) numbers answer { "id": "…", "state": "OPEN", "stale": false } and carry neither timestamp — they are remote-managed, nothing is probed for them, so there is no reading to date.

​
Errors

The code on a 503 tells you whether retrying is worth it:
Fixed: this endpoint used to answer 503 “WhatsApp provider not configured” for every number that was not already OPEN whenever the platform’s own number was disconnected. That coupling is gone — a 503 now describes this number’s own provider.