API-ключи и Client ID

API-ключ позволяет вашим собственным программам и таким инструментам, как Zapier, n8n, Make и плагин WordPress, отправлять сообщения WhatsApp с номеров вашего рабочего пространства. Ваш собственный код передаёт ключ в заголовке Authorization: Bearer; интеграции запрашивают два значения со страницы API-ключи: Client ID вашего рабочего пространства и один из его ключей. На той же странице находится секрет, которым подписываются наши вебхуки.

Кто может это делать: только владельцы — все владельцы рабочего пространства, а не только его создатель. Владельцы видят, создают, копируют и удаляют все ключи рабочего пространства, кто бы их ни создал. Редакторы и аналитики не видят API-ключи ни в боковом меню, ни на странице «Настройки», а ссылка на эту вкладку открывает для них Профиль (см. Роли и права доступа). Ключи работают на любом тарифе, включая пробный период; всё, что вы отправляете с их помощью, расходует сообщения рабочего пространства.

Откройте API-ключи в разделе Интеграции бокового меню или перейдите в Настройки → API-ключи.

У каждого ключа показаны название, дата создания (Создан), последние четыре символа ключа (например, •••• 7f3a), Копировать ключ и Удалить. Самый новый ключ стоит первым.

Создание API-ключа#

1. Нажмите «Создать ключ»

   На вкладке Настройки → API-ключи нажмите Создать ключ в правом верхнем углу карточки.

2. Назовите ключ (необязательно)

   В поле Название (необязательно) введите приложение, которое будет его использовать, например n8n или Сайт (до 50 символов). Если оставить поле пустым, ключ получит название вроде «API Key 3», как сказано в подсказке под полем.

3. Создайте ключ

   Нажмите Создать ключ.

   

4. Скопируйте ключ

   Окно Ваш новый API-ключ показывает полный ключ: «Скопируйте его сейчас – полный ключ больше не будет показан. Позже кнопка „Копировать ключ“ скопирует его, не показывая.» Нажмите Копировать («Ключ скопирован.»), вставьте ключ в своё приложение или интеграцию и нажмите Готово.

   

• До 10 ключей на рабочее пространство. Когда их 10, кнопка Создать ключ серая, а при наведении на неё появляется «Можно иметь не более 10 API-ключей. Удалите один, чтобы создать новый.»
• Ключи не истекают, их нельзя переименовать или отключить: ключ работает, пока его не удалят.
• Один ключ на приложение. Называйте каждый ключ по приложению, которое его использует, — тогда один ключ можно заменить или удалить, не ломая остальные.
• Какое рабочее пространство: ключ принадлежит рабочему пространству, которое было выбрано при его создании, и каждый запрос с этим ключом работает с этим пространством: его номерами, сообщениями и тарифом. Чтобы отправлять из другого рабочего пространства, переключитесь на него и создайте ключ там.

Что указать в приложении#

Куда их вводить:

• Ваш собственный код: в заголовке Authorization: Bearer YOUR_API_KEY в каждом запросе (рекомендуется). Ключ сам указывает на своё рабочее пространство, поэтому client_id можно не передавать; если вы его передаёте, это всё равно должен быть Client ID этого пространства. См. Передача ключа в заголовке, а пример первого сообщения на cURL, Python, Node.js и PHP есть в разделе Отправка сообщения.
• Zapier: Client ID и API-ключ при подключении аккаунта.
• n8n: поля Client ID, API Key и WhatsApp Client ID в учётных данных WbizTool.
• Make, Pabbly Connect и другие инструменты: тело HTTP-запроса.
• WordPress: WbizTool → Settings, раздел API Configuration.

Google Sheets и Shopify настраиваются в панели управления, и ключ для них не нужен.

Передача ключа в заголовке#

Каждый endpoint /api/v1/ принимает ключ в заголовке Authorization, так же как будущий API v2:

Authorization: Bearer YOUR_API_KEY

• client_id необязателен, если ключ передан в заголовке: рабочее пространство определяется ключом. Если вы всё же передаёте client_id, это должен быть Client ID этого рабочего пространства, как и раньше.
• Передавайте ключ в одном месте. С заголовком не указывайте api_key в теле запроса или передавайте тот же ключ. Если ключи различаются, используется ключ из заголовка, когда он действителен; если в заголовке что-то другое (например, токен другого инструмента), используется api_key из тела.
• Ключи в теле запроса по-прежнему работают (client_id и api_key в виде JSON или полей формы), поэтому для приложений и интеграций, которые их передают, ничего не меняется. Заголовок лучше, потому что тело запроса чаще, чем заголовки, попадает в логи, прокси и историю конструкторов форм.
• С заголовком работают и поля формы, и multipart-загрузки, и тело в формате JSON.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Проверка ключа#

Вызовите проверку учётных данных (POST /api/v1/me/) со своим ключом и, если хотите, whatsapp_client. "status": 1 с "message": "Okay" означает, что они работают вместе. Запрос ничего не отправляет и не расходует сообщения, но и не проверяет, остались ли у вас сообщения и подключён ли номер.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Рабочий ключ возвращает {"status": 1, "message": "Okay", "name": "…"}.

Повторное копирование ключа#

Нажмите Копировать ключ рядом с ключом. Полный ключ попадает в буфер обмена, не появляясь на странице; вы увидите, например, «„Zapier“ скопирован.», а кнопка ненадолго покажет Скопировано ✓. Если вы потеряли ключ, создавать новый не нужно.

Чтобы узнать, какой ключ использует приложение, сравните последние четыре символа его ключа со списком.

Удаление ключа#

1. Нажмите «Удалить»

   Нажмите Удалить рядом с ключом.

2. Подтвердите

   Окно «Удалить „…“?» предупреждает: «Всё, что использует этот ключ, сразу перестанет работать: Zaps в Zapier, сценарии n8n и Make, плагин WordPress и ваши собственные вызовы API. Сначала выдайте им другой ключ. Это действие нельзя отменить.» Нажмите Удалить ключ. Появится «„…“ удалён.»

После этого запросы с этим ключом получают Auth Error: invalid api key. То, что ключ успел сделать, остаётся: поставленные им в очередь сообщения всё равно уйдут (при необходимости отмените их в Отчётах), а созданные им напоминания продолжат работать. Триггер Zapier Incoming WhatsApp Message, настроенный с этим ключом, тоже продолжит получать сообщения, потому что его вебхук уже установлен на номере: чтобы остановить его, выключите Zap в Zapier.

Замена ключа#

Заменяйте ключ, если он мог утечь, если уходит человек, который мог его скопировать, или просто время от времени. Кнопки ротации нет: сначала создайте новый ключ, чтобы в промежутке ничего не остановилось.

1. Создайте новый ключ

   Создайте ключ и скопируйте его. Если ключей уже 10, сначала удалите тот, которым больше не пользуетесь.

2. Обновите приложения

   Вставьте новый ключ во все приложения и интеграции, которые использовали старый, и проверьте каждое, например через проверку учётных данных.

3. Удалите старый ключ

   Удалите его. Он сразу перестанет работать.

4. Проверьте, не было ли злоупотреблений (после утечки)

   Просмотрите Отчёты в поисках сообщений, которые вы не отправляли, и отмените те, что ещё ожидают. На странице Напоминания удалите напоминания, которых вы не создавали, потому что они продолжают работать. Удалите номера, которые вы не добавляли, на странице Номера WhatsApp. С дополнением Unibox проверьте страницу Номера для входящих: нет ли там незнакомого значка Zapier или вебхука.

Безопасность ключей#

У ключа нет собственных прав: любой, у кого он есть, может делать в вашем рабочем пространстве всё, что умеет API, независимо от своей роли. В том числе отправлять сообщения с любого из его номеров (за счёт его сообщений), читать историю сообщений, отменять ожидающие сообщения, управлять напоминаниями и медиафайлами, проверять номера и подключать новые.

• Храните ключи на своём сервере — в переменной окружения или в хранилище учётных данных вашей интеграции. Никогда не размещайте ключ в JavaScript сайта, в мобильном приложении, в общей таблице или в публикуемом коде.
• Не пересылайте ключи по почте или в чате. Вставляйте их сразу в приложение, которому они нужны.
• Используйте один ключ на приложение и удаляйте ключи, которыми больше не пользуетесь.
• Заменяйте ключи время от времени и сразу же, если ключ мог утечь.

Сам по себе Client ID не секрет, но относитесь к каждому ключу как к паролю.

API-ключи v2#

У API v2 свои ключи, которые создаются в карточке API-ключи v2 на той же вкладке. Они безопаснее описанных выше ключей:

• Показываются один раз. Полный ключ (wbz_live_…) показывается только при создании; WbizTool хранит лишь его отпечаток. Если вы его потеряете, отзовите его и создайте новый.
• Только то, что нужно. Отметьте, что ключ может делать (отправлять сообщения, читать сообщения, напоминания, номера, медиафайлы, проверки номеров), ограничьте его некоторыми вашими номерами и при желании задайте срок действия.
• Тестовые ключи. Тестовый ключ (wbz_test_…) проверяет каждый запрос так же, как рабочий, но ничего не отправляет — для создания и опробования интеграции.
• Последнее использование. У каждого ключа показано, когда и откуда он использовался в последний раз. Отозвать сразу останавливает его, а вместе с ним и созданные им адреса вебхуков.

Описанные выше ключи работают только с API v1, а API-ключи v2 — только с v2. См. Переход с v1 на v2.

Подписи вебхуков#

WbizTool подписывает каждый вебхук, который отправляет вам, чтобы ваш endpoint мог убедиться, что запрос действительно пришёл от нас и не был изменён по пути: вебхук статуса сообщения (отправлено, ошибка, отменено, истекло), события подключения номера и вебхуки входящих. Тело запроса не меняется; добавляются два заголовка:

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

Получение секрета подписи#

На странице Настройки → API-ключи карточка Секрет подписи вебхуков под вашими ключами показывает последние четыре символа секрета, например •••• b70d. У каждого рабочего пространства один секрет для всех его вебхуков; он создаётся вместе с первым вебхуком, который мы вам отправляем.

1. Нажмите «Показать новый секрет»

   Нажмите Показать новый секрет (или Создать секрет, если у рабочего пространства его ещё нет). Окно «Заменить секрет подписи?» предупреждает, что текущий секрет сразу перестанет работать. Нажмите Создать новый секрет.

2. Скопируйте его

   В окне Ваш секрет подписи вебхуков полный секрет показывается один раз. Нажмите Копировать и сохраните его там, где его сможет прочитать ваш обработчик вебхуков, например в переменной окружения. Больше вы его не увидите: если потеряете, создайте новый.

Карточку видят только владельцы. Новый секрет сразу заменяет старый, поэтому сразу же обновите обработчики: вебхуки, отправленные в промежутке, не пройдут вашу проверку.

Проверка вебхука#

Вычислите подпись по исходному телу запроса (до того, как его разберёт ваш фреймворк), сравните её с заголовком за постоянное время и отклоняйте метки времени старше 5 минут, чтобы старый запрос нельзя было отправить повторно:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Отвечайте 2xx, если проверка прошла, и 401, если нет. Вебхуки входящих для номера со своим секретом вебхука по-прежнему содержат и X-Wbiztool-Signature; WbizTool-Signature работает по одной схеме на всех вебхуках.

Устранение неполадок#

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

• Начало работы с API
• Обзор API v2
• API проверки учётных данных
• API отправки сообщений
• Приложения и интеграции
• Настройки рабочего пространства, участники команды и роли
• Подключение номера WhatsApp