API
API дає змогу працювати з ботами Watbot з власного коду: знаходити й створювати контакти, надсилати їм повідомлення, змінювати змінні й теги, поповнювати баланси, вести списки. Наприклад, CRM на сайті може передати боту заявку, а платіжна система — нарахувати бонуси після оплати.
API доступний власнику акаунта з тарифом Pro. Запит виконується від імені власника ключа і з його правами.
Ключ API
Ключ видається в профілі, на вкладці «API» — докладно в розділі Ключ API. Ключ дає повний доступ до акаунта: зберігайте його на сервері й не вставляйте в код сторінок сайту чи мобільного застосунку.
Ключ передається в заголовку Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
Якщо заголовок поставити не можна, ключ можна передати параметром api_token — в адресі або в тілі запиту. Заголовок надійніший: адреси з параметрами потрапляють у журнали серверів.
Кнопка «Перевипустити» в профілі замінює ключ: попередній одразу перестає працювати. Ключ скидається і під час зміни чи відновлення пароля — після цього отримайте новий. Перевірити ключ можна методом getMe: він поверне акаунт, якому належить ключ.
Запити
Усі методи — за адресою:
https://watbot.org/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.org/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 з датою вимкнення. Перевіряйте їх у своєму коді, щоб вчасно перейти на заміну.