API
API позволяет работать с ботами Watbot из своего кода: находить и создавать контакты, отправлять им сообщения, менять переменные и теги, пополнять балансы, вести списки. Например, CRM на сайте может записать в бота заявку, а платёжная система — начислить бонусы после оплаты.
API доступно владельцу аккаунта с тарифом Pro. Запрос выполняется от имени владельца ключа и с его правами.
Ключ API
Ключ выдаётся в профиле, на вкладке «API» — подробно в разделе Ключ API. Ключ даёт полный доступ к аккаунту: храните его на сервере и не вставляйте в код страниц сайта или мобильного приложения.
Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
Если заголовок поставить нельзя, ключ можно передать параметром api_token — в адресе или в теле запроса. Заголовок надёжнее: адреса с параметрами попадают в журналы серверов.
Кнопка «Перевыпустить» в профиле заменяет ключ: прежний сразу перестаёт работать. Ключ сбрасывается и при смене или восстановлении пароля — после этого получите новый. Проверить ключ можно методом getMe: он вернёт аккаунт, которому ключ принадлежит.
Запросы
Все методы — по адресу:
https://watbot.ru/api/v1/имяМетода
- Большинство методов принимает и
GET, иPOST; какие именно — указано у метода. Методы, которые что-то меняют, лучше вызывать черезPOST. - Параметры
POSTпередаются в JSON (Content-Type: application/json) или как поля формы. УGET— в адресе. - Ответы — в JSON, в кодировке UTF-8.
Важно
Передавайте в каждом запросе заголовок
Accept: application/json. Без него ошибки проверки параметров приходят не ответом422в JSON, а переадресацией — разобрать такую ошибку в коде не получится.
Пример: контакты бота.
curl -X POST "https://watbot.ru/api/v1/getContacts" \
-H "Authorization: Bearer ВАШ_КЛЮЧ" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"bot_id": 12345}'
Номер бота (bot_id) — число в адресе бота в кабинете: /bots/12345/….
Ограничения
- Частота — 120 запросов в минуту на аккаунт, все методы вместе.
- Сверх лимита API отвечает кодом
429. ЗаголовокRetry-Afterговорит, через сколько секунд можно повторить;X-RateLimit-Remaining— сколько запросов осталось в текущей минуте.
Ошибки
Успешный ответ — код 200 или 201. Ошибки:
| Код | Когда | Ответ |
|---|---|---|
401 |
Нет ключа, ключ неверный или перевыпущен | {"error": "unauthorized"} |
402 |
У владельца ключа нет тарифа Pro | {"error": "…", "code": "pro_required"} |
403 |
Нет доступа к боту или объекту; аккаунт заблокирован | {"error": "…"} |
404 |
Бот, контакт или запись не найдены | {"error": "…"} или {"message": "…"} |
410 |
Метод отключён (устаревший метод после даты отключения) | {"error": "…", "code": "method_removed"} |
422 |
Параметры не прошли проверку | {"message": "…", "errors": {"поле": ["…"]}} |
429 |
Превышена частота запросов | {"message": "Too Many Attempts."} |
Ошибка 422 перечисляет в errors каждое поле с причинами:
{
"message": "The contact id field is required.",
"errors": {
"contact_id": ["The contact id field is required."]
}
}
Текст ошибок может меняться — в коде опирайтесь на код ответа и на поля code и errors.
Устаревший метод до отключения работает как прежде, но в каждом ответе присылает заголовки Deprecation: true и Sunset с датой отключения. Проверяйте их в своём коде, чтобы вовремя перейти на замену.