Numbers

A number is a WhatsApp account linked to your business. Messages are always sent from, and received by, one of your numbers.

The number object#

{
  "id": "01a0f44d-c969-75b1-955d-3841d817f711",
  "label": "Front desk",
  "phoneNumber": "+12125550147",
  "status": "CONNECTED",
  "mode": "API",
  "connectedAt": "2026-10-01T10:01:12.000Z",
  "lastDisconnectedAt": null,
  "createdAt": "2026-10-01T10:00:00.000Z"
}

mode is always API here: API keys only see API numbers. phoneNumber is filled in once the number connects.

List numbers#

Returns an array of number objects, oldest first. A key limited to some numbers only lists those numbers; to it, every other number of your business answers 404.

Create a number#

Creates a number, starts pairing and returns it with a connectUrl — the hosted page that shows its QR code. See Connect a number. When the key is limited to some numbers, the new number is added to its list, so the key can use it straight away.

curl https://api.waconnect.ai/v1/numbers \
  -H "Authorization: Bearer wc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"label":"Front desk"}'

Returns 201 with the number and connectUrl. Answers 402 when you're out of credits.

Get a number#

The number object plus its connection history: the 20 most recent events, newest first, and totalEvents, the number of events since the number was created. Use it to show a timeline of when a number connected, dropped and came back.

{
  "id": "01a0f44d-c969-75b1-955d-3841d817f711",
  "label": "Front desk",
  "phoneNumber": "+12125550147",
  "status": "CONNECTED",
  "mode": "API",
  "connectedAt": "2026-10-01T10:01:12.000Z",
  "lastDisconnectedAt": "2026-10-03T08:15:40.000Z",
  "createdAt": "2026-10-01T10:00:00.000Z",
  "events": [
    { "id": "01a0f6c2-1f0e-7a33-8b5e-6c1d2e3f4a5b", "type": "RECONNECTED", "message": null, "createdAt": "2026-10-03T08:16:02.000Z" },
    { "id": "01a0f6c1-9d2a-7c10-a4f1-2b3c4d5e6f70", "type": "RECONNECTING", "message": "Code 428", "createdAt": "2026-10-03T08:15:40.000Z" },
    { "id": "01a0f44e-0b7d-7e21-9c3a-1d2e3f4a5b6c", "type": "CONNECTED", "message": "+12125550147", "createdAt": "2026-10-01T10:01:12.000Z" },
    { "id": "01a0f44d-d102-7f8e-b6a9-0c1d2e3f4a5b", "type": "QR_REQUESTED", "message": null, "createdAt": "2026-10-01T10:00:00.000Z" }
  ],
  "totalEvents": 4
}

Event fields#

New event types may be added; show an unknown type as it is. Older events beyond the latest 20 aren't returned; totalEvents tells you how many there are in all.

Get the QR code#

The current QR code as text, for drawing it in your own UI.

{ "status": "CONNECTING", "qr": "2@AbC…", "generatedAt": "2026-10-01T10:00:05.000Z", "expired": false }

New connect link#

Starts a fresh QR code and returns a new connectUrl; the previous link stops working. Use it when a code expired or a link was used.

{ "connectUrl": "https://waconnect.ai/connect/Lx8…_U" }

Answers 409 with the code NUMBER_ALREADY_CONNECTED if the number is already connected.

Remove a number#

Logs the number out of WhatsApp and removes it. Answers 202: removal finishes a moment later, and the number.removed webhook is sent with reason: "deleted". Chat history is kept and reattaches if the same phone is connected again.