Переход с v1 на v2

API v2 умеет то же, что и v1, но с более безопасными ключами, единым стилем URL, настоящими кодами состояния HTTP и подписанными вебхуками JSON. На этой странице для каждого endpoint и поля v1 указан его аналог в v2. Что нового в самом v2, описано в обзоре.

Что меняется везде#

• Ключи: client_id + api_key из v1 превращаются в один заголовок Authorization: Bearer wbz_live_…. Создайте ключ v2 на странице Настройки → API-ключи, в карточке API-ключи v2, только с теми областями доступа, которые нужны приложению. Ключи v1 не работают в v2, а ключи v2 не работают в v1.
• Только JSON: никаких полей формы. Файлы загружаются через POST /media (multipart) и отправляются по media_id.
• Методы и URL: GET для чтения, POST для создания, PATCH для изменения, DELETE для отмены или удаления, под https://wbiztool.com/api/v2.
• Коды состояния HTTP вместо "status": 0 или 1 (см. Ответы и ошибки).
• Номера телефонов в международном формате с +, без country_code.
• Время в ISO 8601 со смещением вместо отдельных полей даты, времени и часового пояса.
• Вебхуки — это endpoint, которые вы один раз добавляете для рабочего пространства, с подписанными событиями JSON, а не URL webhook в каждом сообщении.

Соответствие endpoint#

Пути v2 указаны относительно https://wbiztool.com/api/v2.

Отправка: поле за полем#

Одна и та же отправка в v1 и v2:

# v1
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_V1_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "msg_type": 1, "country_code": "91", "phone": "9876543210",
       "img_url": "https://example.com/offers/diwali-sale.jpg", "msg": "Our Diwali sale starts today",
       "expire_after_seconds": 3600}'

# v2
curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diwali-9876543210" \
  -d '{"from": 101, "to": {"phone": "+919876543210"},
       "media": {"url": "https://example.com/offers/diwali-sale.jpg"}, "text": "Our Diwali sale starts today",
       "expires_at": "2026-10-20T11:30:00+05:30"}'

Некоторые особенности v1 убраны намеренно:

• Код страны не угадывается. v1 добавлял country_code перед номером (с 91 — всегда перед 10-значным номером). v2 принимает номер ровно так, как он написан с +.
• Файл не скачивается при вызове. v1 скачивал img_url и file_url во время запроса. v2 проверяет, что ссылка публичная, и скачивает файл при отправке сообщения; нерабочая ссылка проявляется как сообщение failed.
• Отказ не оставляет строку с ошибкой. Когда v1 отклоняет отправку сверх суточных 1000, он всё равно сохраняет сообщение как неудачное. v2 ничего не сохраняет, когда отклоняет отправку.
• Неизвестные поля отклоняются, а не игнорируются.

Статусы#

Числа и слова v1 превращаются в одно поле status:

События вебхуков — message.sent, message.failed, message.cancelled и message.expired, они соответствуют SENT, FAILED, CANCELLED и EXPIRED из v1.

Ответы и ошибки#

v1 отвечает на многие ошибки HTTP 200 или 400 с "status": 0, а на успех — "status": 1. v2 использует код состояния HTTP:

• Успех — это 200, 201 (создано) или 202 (в очереди), а тело — сам объект, например Message. Обёртки status: 1 нет.
• Ошибки — это 4xx или 5xx в одном формате: {"error": {"code", "message", "field", "docs", "request_id"}}. Опирайтесь на code, а не на английский message. Все коды есть на странице ошибок.

# v1
result = response.json()
if result.get("status") == 1:
    msg_id = result["msg_id"]

# v2
if response.status_code == 202:
    message_id = response.json()["id"]
else:
    error = response.json()["error"]
    if error["code"] == "number_daily_cap_reached":
        ...  # try again tomorrow

Некоторые сообщения v1 и их коды в v2:

Вебхуки#

В v1 каждое сообщение может содержать URL webhook, который получает данные формы msg_id=…&status=SENT. В v2:

1. Один раз добавьте endpoint через POST /webhooks и сохраните его secret.
2. Он получает события JSON по всем сообщениям рабочего пространства, с полным Message в data.message. Сопоставляйте их со своими записями по data.message.id.
3. Проверяйте подпись: схема та же, что в v1 (WbizTool-Timestamp, WbizTool-Signature: v1=…), но с собственным секретом endpoint вместо секрета рабочего пространства.
4. Отбрасывайте повторы по WbizTool-Event-Id. Повторные попытки идут около 23 часов, а не 4 попытки за несколько минут, как в v1, и ответы 4xx тоже повторяются.

У событий подключения из v1 (webhook_url в whatsapp/connect/) пока нет события в v2: вместо этого опрашивайте GET /numbers/{id}.

Чек-лист#

1. Создайте ключ v2 для каждого приложения

   На странице Настройки → API-ключи, только с нужными ему областями доступа. Сначала попробуйте тестовый ключ: он всё проверяет и ничего не отправляет.

2. Измените запросы

   Новые URL и методы, тела JSON, to / from / text / media, номера телефонов с +, время со смещением. Добавляйте Idempotency-Key к каждой отправке.

3. Измените обработку ошибок

   Проверяйте статус HTTP, затем error.code. На 429 ждите столько, сколько указано в Retry-After.

4. Перенесите вебхуки

   Добавьте endpoint, проверяйте подписи его секретом и отбрасывайте повторы по ID события.

5. Переключитесь и отзовите ключ v1

   Когда приложение заработает на v2, удалите его ключ v1 на странице Настройки → API-ключи.

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

• Обзор API v2
• Сообщения
• Вебхуки
• Ошибки
• API-ключи и Client ID (v1)