Skip to content
WbizTool

API v2 (beta)

Numbers

A number is a WhatsApp number or a Telegram account connected to your workspace. Its id is the from you send messages with. With API v2 you list them, see whether each one is connected, and connect a WhatsApp number from your own app, by QR code or pairing code.

OperationEndpointScope
List numbersGET /api/v2/numbersnumbers
Get a numberGET /api/v2/numbers/{id}numbers
Connect a WhatsApp numberPOST /api/v2/numbersnumbers

A key limited to some numbers sees and reconnects only those, and can't add a number.

List numbers#

GEThttps://wbiztool.com/api/v2/numbers

All the workspace's numbers, oldest first, in one data list (no pages).

curl https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"
{
  "data": [
    {
      "id": 101,
      "phone": "919800000000",
      "label": "Shop",
      "platform": "whatsapp",
      "status": "connected",
      "login_method": "qr",
      "connect": null
    },
    {
      "id": 102,
      "phone": null,
      "label": "",
      "platform": "whatsapp",
      "status": "disconnected",
      "login_method": "qr",
      "connect": null
    }
  ]
}

connect is always null in the list. To follow a connection, get the number.

Get a number#

GEThttps://wbiztool.com/api/v2/numbers/{id}

One number. While it's connecting, connect has the QR code to scan or the pairing code to type.

curl https://wbiztool.com/api/v2/numbers/102 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"
{
  "id": 102,
  "phone": null,
  "label": "",
  "platform": "whatsapp",
  "status": "connecting",
  "login_method": "qr",
  "connect": {
    "qr_code_url": "https://…/qr_codes/…png?X-Amz-Signature=…",
    "pairing_code": null,
    "pairing_code_expires_at": null,
    "linking": false,
    "requested_at": "2026-10-18T11:02:15.402Z"
  }
}

A number that doesn't exist, or that the key may not use, answers 404 number_not_found.

The Number object#

FieldTypeDescription
idintegerThe number's id: the from of a message or reminder.
phonestring or nullIts digits with the country code, no +, such as 919800000000. null for a new number connected by QR until the QR code is scanned.
labelstringIts name in the dashboard; "" when it has none.
platformstringwhatsapp or telegram.
statusstringconnected, connecting (a connection was asked for in the last 10 minutes and is still going) or disconnected.
login_methodstringHow it connects: qr or phone_code (a pairing code).
connectobject or nullWhile status is connecting, and only from Get a number; null otherwise.

connect has:

FieldTypeDescription
qr_code_urlstring or nullA link to the QR code image to scan. Each call gives a new link, valid for 10 minutes; null until the server has the QR code.
pairing_codestring or nullFor phone_code: the code to type on the phone. null until it's ready.
pairing_code_expires_atstring or nullWhen the pairing code stops working.
linkingbooleantrue once the QR code was scanned or the code accepted, while WhatsApp finishes linking.
requested_atstring or nullWhen the connection was asked for.

Messages sent with a disconnected number as from are still accepted: they wait and go out when it's connected again. Webhook events for numbers come later; until then, poll GET /numbers to notice a number that was logged out.

Connect a WhatsApp number#

POSThttps://wbiztool.com/api/v2/numbers

Body: JSON (application/json)

Asks a WbizTool server to open WhatsApp for a number, so you can link it from your own app or website, as you would on WhatsApp numbers. The answer is 202 with the Number, in status connecting. Then poll it until it's connected.

It needs a plan that includes the QR code API; otherwise it answers 403 plan_required. Telegram accounts are connected in the dashboard, not here.

Body

login_methodstringoptional

qr (default): scan a QR code. phone_code: type a pairing code on the phone instead, handy when the phone is the only screen.

phonestringRequired for phone_code

The WhatsApp number to link, in international format with +, such as +919876543210. Not used with qr: the number is read from WhatsApp after the scan.

number_idintegeroptional

Reconnect this existing number instead of adding a new one, for example after it was logged out.

# By QR code
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "qr"}'

# By pairing code, reconnecting number 101
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "phone_code", "phone": "+919876543210", "number_id": 101}'

The connect flow#

  1. Ask for the connection

    POST /numbers with login_method (and phone for a pairing code). Keep the id from the answer. Send an Idempotency-Key so a retry doesn't ask twice.

  2. Poll the number every few seconds

    GET /numbers/{id} every 2 to 5 seconds while status is connecting. The QR code or pairing code appears in connect within moments; until then its fields are null.

  3. Show the QR code or the pairing code

    QR: show the image at connect.qr_code_url; on the phone, open WhatsApp → Linked devices → Link a device and scan it. Each link works for 10 minutes and a new one comes with every poll, so show the newest each time. Pairing code: on the phone, open WhatsApp → Linked devices → Link a device → Link with phone number instead, and type the 8-character connect.pairing_code before connect.pairing_code_expires_at (about 3 minutes).

  4. Wait for connected

    After the scan or the code, connect.linking is true while WhatsApp finishes linking. Then status becomes connected and phone shows the number. Stop polling.

If nothing happens for 10 minutes, the attempt ends and status goes back to disconnected. Ask again with POST /numbers and its number_id.

While a number is being connected, another request for it answers 409 connect_in_progress with its number_id: keep polling that one instead.

Errors when connecting#

HTTPCodeWhen
400validation_failedlogin_method isn't qr or phone_code, or phone_code without phone
403plan_requiredThe plan doesn't include the QR code API
403number_limit_reachedThe plan has no room for another number
403number_not_allowedThe key is limited to some numbers, and number_id isn't one of them (or is missing)
409already_connectedThat number is connected already
409connect_in_progressThat number is being connected right now; number_id says which
422invalid_phonephone isn't a valid number in international format with +
422number_not_foundnumber_id isn't a number of this workspace