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

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

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

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

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

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

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

   Передайте номер телефона и ваш webhook_url. В ответе вы получите whatsapp_client_id. Сохраните его.

2. Получите QR-код

   Ваш webhook получает status=qr_generated с изображением QR-кода в qr_image. Покажите это изображение владельцу телефона. Пока Wbiztool ждёт сканирования, QR-код отправляется повторно каждые несколько секунд, поэтому всегда показывайте последний. На сканирование у человека есть около двух минут. После этого или если WhatsApp попросит перезагрузить код, вы получите not_connected; вызовите API снова, чтобы получить новый код.

3. Отсканируйте его в WhatsApp

   На телефоне откройте WhatsApp → Связанные устройства → Привязка устройства и отсканируйте код.

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

   Ваш webhook получает status=connected, когда номер привязан, или 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",
    "whatsapp_number": "919876543210",
    "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",
        "whatsapp_number": "919876543210",
        "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",
    whatsapp_number: "919876543210",
    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',
    'whatsapp_number' => '919876543210',
    '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 своими значениями. Где их найти, описано в разделе Аутентификация.

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

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

Python-клиент вызывает /api/v1/whatsapp-client/create/ за вас.

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,
  "status": 1
}

"status": 1 означает, что запрос создан, а не что номер подключён. Если снова вызвать API для номера, который был добавлен ранее, но не подключён, вы получите тот же whatsapp_client_id, и начнётся новая попытка подключения.

Ошибки#

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

Если тот же владелец аккаунта уже добавил этот номер в другом рабочем пространстве, запрос может завершиться ошибкой HTTP 500. Подключите номер на странице настроек WhatsApp в нужном рабочем пространстве или свяжитесь с поддержкой.

События webhook#

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

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

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

Номер подключён (для одного подключения может прийти несколько раз):

status=connected&whatsapp_client_id=678

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

status=not_connected&whatsapp_client_id=678

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

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

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

Советы#

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