Подключение номера WhatsApp (API)

Начните подключение номера WhatsApp к вашему рабочему пространству прямо из своего приложения. WbizTool открывает новую сессию WhatsApp и отправляет на ваш URL webhook QR-код или, при login_method=phone, 8-символьный код. Покажите его владельцу телефона, он сканирует QR-код или вводит код в WhatsApp — и номер готов к отправке сообщений. При подключении по QR-коду номер не нужно знать заранее: WbizTool получит его из WhatsApp после сканирования и отправит на ваш webhook.

Привязываете свой номер вручную? Следуйте руководству Подключение номера WhatsApp.

POST /api/v1/whatsapp-client/create/ — полностью идентичный псевдоним: он выполняет тот же код и возвращает те же ответы. Оба пути продолжают работать.

Как проходит подключение#

Вызов API только начинает подключение. QR-код или код для телефона приходит позже — на ваш URL webhook.

1. Вызовите API подключения

   Передайте ваш webhook_url, а при login_method=phone — ещё и whatsapp_number. Чтобы переподключить номер, добавленный ранее, передайте также его whatsapp_client_id. В ответе вы получите whatsapp_client_id. Сохраните его.

2. Получите QR-код или код для телефона

   При login_method=qr (по умолчанию) ваш webhook получает status=qr_generated с изображением QR-кода в qr_image. Пока WbizTool ждёт сканирования, QR-код отправляется повторно каждые несколько секунд, поэтому всегда показывайте последний. На сканирование у человека есть около двух минут.

   При login_method=phone ваш webhook получает status=pairing_code с 8-символьным кодом в pairing_code, например K5EWPGY5. Он отправляется один раз и действует около трёх минут.

   Покажите изображение или код владельцу телефона. Если их не использовали вовремя или WhatsApp попросит перезагрузить код, вы получите not_connected; вызовите API снова, чтобы получить новый.

3. Привяжите телефон

   На телефоне откройте WhatsApp → Связанные устройства → Привязка устройства. Отсканируйте QR-код или нажмите Привязать по номеру телефона и введите 8-символьный код.

4. Получите результат

   Ваш webhook получает status=connected с привязанным номером в whatsapp_number, когда номер привязан, или status=not_connected, если код не отсканировали вовремя или подключение не удалось. Событие connected может прийти на несколько секунд раньше, чем Статус подключения вернёт Connected. Сначала ответьте на webhook, а затем опрашивайте «Статус подключения» каждые несколько секунд в течение минуты. Не проверяйте его один раз прямо из обработчика webhook.

Быстрый пример#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

Замените 12345 и YOUR_API_KEY своими значениями. Где их найти, описано в разделе Аутентификация. Чтобы вместо QR-кода получить код для телефона, добавьте "login_method": "phone" и "whatsapp_number": "919876543210".

Параметры запроса#

Использование официальных клиентов#

Python-клиент вызывает /api/v1/whatsapp-client/create/ за вас. Он запрашивает whatsapp_number; при подключении по QR-коду это значение игнорируется.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

Python-клиент выбрасывает requests.exceptions.HTTPError, когда API возвращает HTTP 400 или 403, поэтому оберните вызов в try/except.

Ответ#

Когда запрос на подключение создан, API возвращает HTTP 200:

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "login_method": "qr",
  "status": 1
}

"status": 1 означает, что запрос создан, а не что номер подключён. Повторные вызовы API не создают лишних номеров:

• При подключении по QR-коду без whatsapp_client_id вы получаете тот же whatsapp_client_id, пока не будет отсканирован один из его QR-кодов.
• При login_method=phone для номера, который был добавлен ранее, но не подключён, возвращается его существующий whatsapp_client_id.
• С whatsapp_client_id этот номер переподключается.

Пока не отсканирован первый QR-код, у номера ещё нет номера телефона: Список подключённых номеров и Статус подключения возвращают для него пустой номер.

Ошибки#

Запрос, который не является POST, возвращает пустой объект {} с HTTP 200.

События webhook#

На каждом шаге WbizTool отправляет POST на ваш webhook_url. Тело запроса передаётся в виде полей формы (application/x-www-form-urlencoded), а не JSON.

QR-код готов (отправляется повторно каждые несколько секунд, пока ожидается сканирование, часто с тем же изображением):

status=qr_generated&whatsapp_client_id=678&qr_image=...

Код для телефона готов (при login_method=phone, отправляется один раз):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Номер подключён, с номером, под которым выполнен вход, в том виде, как его сообщает WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Подключение не удалось, например, потому что QR-код не отсканировали или код для телефона не ввели вовремя:

status=not_connected&whatsapp_client_id=678

Ваш URL должен быть публично доступен и отвечать в течение нескольких секунд. WbizTool ждёт вашего ответа до 10 секунд; если ваш сервер отвечает медленно или недоступен, это событие теряется, но попытка подключения продолжается. Принимается любой код статуса HTTP. Неудачные доставки не повторяются, а если номер позже отключится, ничего отправлено не будет. Чтобы следить за номером после подключения, опрашивайте Статус подключения.

Опрос вместо webhook#

Если ваш сервер не может принимать webhook, webhook всё равно нужен для получения QR-кода, но для получения результата полагаться на него не обязательно. После сканирования QR-кода вызывайте Статус подключения с whatsapp_client_id каждые несколько секунд, пока он не вернёт Connected. Список аккаунтов показывает то же самое для всех ваших номеров.

Советы#

• Обрабатывайте повторные события: сделайте обработчик безопасным для повторного выполнения на случай, если событие будет доставлено дважды.
• Показывайте самый новый QR-код: заменяйте изображение при каждом новом событии qr_generated, добавляя к https URL параметр для обхода кеша. Старые коды перестают работать.
• Сканируйте примерно в течение двух минут: после этого вы получите not_connected. Вызовите API снова, чтобы получить новый код.
• Проверяйте номер после сканирования QR-кода: whatsapp_number в событии connected — это номер, который был привязан на самом деле, и он может отличаться от ожидаемого.
• Введите код для телефона примерно в течение трёх минут: каждая попытка даёт один код. Если он истёк, вы получите not_connected; вызовите API снова.
• Нет QR-кода или кода для телефона через 10 минут? Запрос истёк. Вызовите API снова.
• Подключение из панели управления проще, если вы привязываете собственный номер. Откройте настройки WhatsApp и отсканируйте код там.