Перейти к содержимому
WbizTool

API v2 (бета)

Номера

Номер — это номер WhatsApp или аккаунт Telegram, подключённый к вашему рабочему пространству. Его id — это from, с которым вы отправляете сообщения. С API v2 вы получаете список номеров, видите, подключён ли каждый из них, и подключаете номер WhatsApp из своего приложения по QR-коду или коду привязки.

ОперацияEndpointОбласть доступа
Список номеровGET /api/v2/numbersnumbers
Получение номераGET /api/v2/numbers/{id}numbers
Подключение номера WhatsAppPOST /api/v2/numbersnumbers

Ключ, ограниченный некоторыми номерами, видит и переподключает только их и не может добавить номер.

Список номеров#

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

Все номера рабочего пространства, сначала самые старые, одним списком data (без страниц).

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 всегда равен null. Чтобы следить за подключением, получите номер.

Получение номера#

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

Один номер. Пока он подключается, в connect есть QR-код для сканирования или код привязки для ввода.

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"
  }
}

Номер, которого не существует или который ключу использовать нельзя, возвращает 404 number_not_found.

Объект Number#

ПолеТипОписание
idintegerID номера: from сообщения или напоминания.
phonestring or nullЦифры номера с кодом страны, без +, например 919800000000. null у нового номера, подключаемого по QR-коду, пока QR-код не отсканирован.
labelstringЕго название в панели; "", если названия нет.
platformstringwhatsapp или telegram.
statusstringconnected, connecting (подключение запрошено за последние 10 минут и ещё идёт) или disconnected.
login_methodstringСпособ подключения: qr или phone_code (код привязки).
connectobject or nullПока status равен connecting, и только в Получении номера; иначе null.

connect содержит:

ПолеТипОписание
qr_code_urlstring or nullСсылка на изображение QR-кода для сканирования. Каждый вызов даёт новую ссылку, действительную 10 минут; null, пока у сервера нет QR-кода.
pairing_codestring or nullДля phone_code: код, который нужно ввести на телефоне. null, пока он не готов.
pairing_code_expires_atstring or nullКогда код привязки перестаёт работать.
linkingbooleantrue после сканирования QR-кода или принятия кода, пока WhatsApp завершает привязку.
requested_atstring or nullКогда было запрошено подключение.

Сообщения с номером disconnected в from всё равно принимаются: они ждут и уходят, когда номер снова подключится. События вебхуков для номеров появятся позже; до тех пор опрашивайте GET /numbers, чтобы заметить номер, который вышел из аккаунта.

Подключение номера WhatsApp#

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

Тело запроса: JSON (application/json)

Просит сервер WbizTool открыть WhatsApp для номера, чтобы вы могли привязать его из своего приложения или сайта, как на странице Номера WhatsApp. Ответ — 202 с Number в статусе connecting. Затем опрашивайте его, пока он не станет connected.

Нужен тариф, включающий API QR-кода; иначе ответ — 403 plan_required. Аккаунты Telegram подключаются в панели, а не здесь.

Тело запроса

login_methodstringнеобязательно

qr (по умолчанию): отсканировать QR-код. phone_code: вместо этого ввести код привязки на телефоне — удобно, когда телефон — единственный экран.

phonestringОбязателен для phone_code

Номер WhatsApp для привязки, в международном формате с +, например +919876543210. С qr не используется: номер считывается из WhatsApp после сканирования.

number_idintegerнеобязательно

Переподключить этот существующий номер вместо добавления нового, например после выхода из аккаунта.

# 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}'

Процесс подключения#

  1. Запросите подключение

    POST /numbers с login_method (и phone для кода привязки). Сохраните id из ответа. Передайте Idempotency-Key, чтобы повтор не запросил подключение дважды.

  2. Опрашивайте номер каждые несколько секунд

    GET /numbers/{id} каждые 2–5 секунд, пока status равен connecting. QR-код или код привязки появляется в connect в течение нескольких мгновений; до этого его поля равны null.

  3. Покажите QR-код или код привязки

    QR: покажите изображение по connect.qr_code_url; на телефоне откройте WhatsApp → Связанные устройства → Привязка устройства и отсканируйте его. Каждая ссылка работает 10 минут, а с каждым опросом приходит новая, поэтому каждый раз показывайте самую свежую. Код привязки: на телефоне откройте WhatsApp → Связанные устройства → Привязка устройства → Привязать по номеру телефона и введите 8-символьный connect.pairing_code до connect.pairing_code_expires_at (около 3 минут).

  4. Дождитесь подключения

    После сканирования или ввода кода connect.linking равен true, пока WhatsApp завершает привязку. Затем status становится connected, а phone показывает номер. Прекратите опрос.

Если 10 минут ничего не происходит, попытка завершается и status возвращается в disconnected. Запросите подключение снова через POST /numbers с его number_id.

Пока номер подключается, другой запрос для него возвращает 409 connect_in_progress с его number_id: продолжайте опрашивать этот номер.

Ошибки при подключении#

HTTPКодКогда
400validation_failedlogin_method — не qr и не phone_code, или phone_code без phone
403plan_requiredТариф не включает API QR-кода
403number_limit_reachedВ тарифе нет места для ещё одного номера
403number_not_allowedКлюч ограничен некоторыми номерами, а number_id не из их числа (или не указан)
409already_connectedЭтот номер уже подключён
409connect_in_progressЭтот номер подключается прямо сейчас; number_id показывает какой
422invalid_phonephone — не действительный номер в международном формате с +
422number_not_foundnumber_id — не номер этого рабочего пространства

Связанные материалы#