# API

API дає змогу працювати з ботами Watbot з власного коду: знаходити й створювати контакти, надсилати їм повідомлення, змінювати змінні й теги, поповнювати баланси, вести списки. Наприклад, CRM на сайті може передати боту заявку, а платіжна система — нарахувати бонуси після оплати.

API доступний власнику акаунта з тарифом Pro. Запит виконується від імені власника ключа і з його правами.

## Ключ API

Ключ видається в профілі, на вкладці «API» — докладно в розділі [Ключ API](https://support.watbot.org/uk/account/profile#ключ-api). Ключ дає повний доступ до акаунта: зберігайте його на сервері й не вставляйте в код сторінок сайту чи мобільного застосунку.

Ключ передається в заголовку `Authorization`:

```
Authorization: Bearer ВАШ_КЛЮЧ
```

Якщо заголовок поставити не можна, ключ можна передати параметром `api_token` — в адресі або в тілі запиту. Заголовок надійніший: адреси з параметрами потрапляють у журнали серверів.

Кнопка «Перевипустити» в профілі замінює ключ: попередній одразу перестає працювати. Ключ скидається і під час зміни чи відновлення пароля — після цього отримайте новий. Перевірити ключ можна методом [getMe](https://support.watbot.org/uk/api/account#getme): він поверне акаунт, якому належить ключ.

## Запити

Усі методи — за адресою:

```
https://watbot.org/api/v1/назваМетоду
```

- Більшість методів приймає і `GET`, і `POST`; які саме — вказано біля методу. Методи, що щось змінюють, краще викликати через `POST`.
- Параметри `POST` передаються в JSON (`Content-Type: application/json`) або як поля форми. У `GET` — в адресі.
- Відповіді — в JSON, у кодуванні UTF-8.

> [!IMPORTANT]
> Передавайте в кожному запиті заголовок `Accept: application/json`. Без нього помилки перевірки параметрів приходять не відповіддю `422` у JSON, а переадресацією — розібрати таку помилку в коді не вийде.

Приклад: контакти бота.

```bash title="Запит"
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` кожне поле з причинами:

```json
{
  "message": "The contact id field is required.",
  "errors": {
    "contact_id": ["The contact id field is required."]
  }
}
```

Тексти помилок можуть змінюватися — у коді спирайтеся на код відповіді та на поля `code` і `errors`.

До вимкнення застарілий метод працює як раніше, але в кожній відповіді надсилає заголовки `Deprecation: true` і `Sunset` з датою вимкнення. Перевіряйте їх у своєму коді, щоб вчасно перейти на заміну.