API v2 (бета)
Номера
Номер — это номер WhatsApp или аккаунт Telegram, подключённый к вашему рабочему пространству. Его id — это from, с которым вы отправляете сообщения. С API v2 вы получаете список номеров, видите, подключён ли каждый из них, и подключаете номер WhatsApp из своего приложения по QR-коду или коду привязки.
| Операция | Endpoint | Область доступа |
|---|---|---|
| Список номеров | GET /api/v2/numbers | numbers |
| Получение номера | GET /api/v2/numbers/{id} | numbers |
| Подключение номера WhatsApp | POST /api/v2/numbers | numbers |
Ключ, ограниченный некоторыми номерами, видит и переподключает только их и не может добавить номер.
Список номеров#
https://wbiztool.com/api/v2/numbersВсе номера рабочего пространства, сначала самые старые, одним списком data (без страниц).
curl https://wbiztool.com/api/v2/numbers \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"import os
import requests
response = requests.get(
"https://wbiztool.com/api/v2/numbers",
headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
timeout=30,
)
for number in response.json()["data"]:
print(number["id"], number["phone"], number["label"], number["status"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/numbers", {
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const { data } = await response.json();
for (const number of data) console.log(number.id, number.phone, number.label, number.status);<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
]);
$numbers = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
foreach ($numbers as $number) {
echo $number['id'] . ' ' . $number['phone'] . ' ' . $number['status'] . "\n";
}{
"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. Чтобы следить за подключением, получите номер.
Получение номера#
https://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#
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID номера: from сообщения или напоминания. |
phone | string or null | Цифры номера с кодом страны, без +, например 919800000000. null у нового номера, подключаемого по QR-коду, пока QR-код не отсканирован. |
label | string | Его название в панели; "", если названия нет. |
platform | string | whatsapp или telegram. |
status | string | connected, connecting (подключение запрошено за последние 10 минут и ещё идёт) или disconnected. |
login_method | string | Способ подключения: qr или phone_code (код привязки). |
connect | object or null | Пока status равен connecting, и только в Получении номера; иначе null. |
connect содержит:
| Поле | Тип | Описание |
|---|---|---|
qr_code_url | string or null | Ссылка на изображение QR-кода для сканирования. Каждый вызов даёт новую ссылку, действительную 10 минут; null, пока у сервера нет QR-кода. |
pairing_code | string or null | Для phone_code: код, который нужно ввести на телефоне. null, пока он не готов. |
pairing_code_expires_at | string or null | Когда код привязки перестаёт работать. |
linking | boolean | true после сканирования QR-кода или принятия кода, пока WhatsApp завершает привязку. |
requested_at | string or null | Когда было запрошено подключение. |
Сообщения с номером disconnected в from всё равно принимаются: они ждут и уходят, когда номер снова подключится. События вебхуков для номеров появятся позже; до тех пор опрашивайте GET /numbers, чтобы заметить номер, который вышел из аккаунта.
Подключение номера WhatsApp#
https://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}'import os
import time
import requests
API = "https://wbiztool.com/api/v2"
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}
number = requests.post(f"{API}/numbers", headers=headers,
json={"login_method": "phone_code", "phone": "+919876543210"}, timeout=30).json()
shown = None
while number["status"] == "connecting":
time.sleep(3)
number = requests.get(f"{API}/numbers/{number['id']}", headers=headers, timeout=30).json()
code = (number["connect"] or {}).get("pairing_code")
if code and code != shown:
print("On the phone: WhatsApp → Linked devices → Link with phone number, then type", code)
shown = code
print("Number", number["id"], "is", number["status"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const API = "https://wbiztool.com/api/v2";
const headers = { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" };
let number = await (await fetch(`${API}/numbers`, {
method: "POST", headers, body: JSON.stringify({ login_method: "qr" }),
})).json();
let shown = null;
while (number.status === "connecting") {
await new Promise((r) => setTimeout(r, 3000));
number = await (await fetch(`${API}/numbers/${number.id}`, { headers })).json();
const qr = number.connect?.qr_code_url;
if (qr && qr !== shown) {
console.log("Show this QR code to scan:", qr); // e.g. in an <img> on your page
shown = qr;
}
}
console.log(`Number ${number.id} is ${number.status}`);<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['login_method' => 'qr']),
CURLOPT_RETURNTRANSFER => true,
]);
$number = json_decode(curl_exec($ch), true);
curl_close($ch);
// Save $number['id'], then poll GET /api/v2/numbers/{id} every few seconds (see The connect flow).
echo $number['id'] . ' ' . $number['status'];Процесс подключения#
Запросите подключение
POST /numbersсlogin_method(иphoneдля кода привязки). Сохранитеidиз ответа. ПередайтеIdempotency-Key, чтобы повтор не запросил подключение дважды.Опрашивайте номер каждые несколько секунд
GET /numbers/{id}каждые 2–5 секунд, покаstatusравенconnecting. QR-код или код привязки появляется вconnectв течение нескольких мгновений; до этого его поля равныnull.Покажите QR-код или код привязки
QR: покажите изображение по
connect.qr_code_url; на телефоне откройте WhatsApp → Связанные устройства → Привязка устройства и отсканируйте его. Каждая ссылка работает 10 минут, а с каждым опросом приходит новая, поэтому каждый раз показывайте самую свежую. Код привязки: на телефоне откройте WhatsApp → Связанные устройства → Привязка устройства → Привязать по номеру телефона и введите 8-символьныйconnect.pairing_codeдоconnect.pairing_code_expires_at(около 3 минут).Дождитесь подключения
После сканирования или ввода кода
connect.linkingравенtrue, пока WhatsApp завершает привязку. Затемstatusстановитсяconnected, аphoneпоказывает номер. Прекратите опрос.
Если 10 минут ничего не происходит, попытка завершается и status возвращается в disconnected. Запросите подключение снова через POST /numbers с его number_id.
Пока номер подключается, другой запрос для него возвращает 409 connect_in_progress с его number_id: продолжайте опрашивать этот номер.
Ошибки при подключении#
| HTTP | Код | Когда |
|---|---|---|
400 | validation_failed | login_method — не qr и не phone_code, или phone_code без phone |
403 | plan_required | Тариф не включает API QR-кода |
403 | number_limit_reached | В тарифе нет места для ещё одного номера |
403 | number_not_allowed | Ключ ограничен некоторыми номерами, а number_id не из их числа (или не указан) |
409 | already_connected | Этот номер уже подключён |
409 | connect_in_progress | Этот номер подключается прямо сейчас; number_id показывает какой |
422 | invalid_phone | phone — не действительный номер в международном формате с + |
422 | number_not_found | number_id — не номер этого рабочего пространства |
Связанные материалы#
- Подключение номера WhatsApp в панели
- Подключение аккаунта Telegram
- Сообщения: отправка с номера через
from - Ошибки
