# Повідомлення

Через API бот може написати контакту з вашої системи: нагадати про запис, надіслати чек, відповісти з CRM. Для цього є метод **sendMessage** — він надсилає текст, зображення або файл одразу й відповідає, чи пішло повідомлення.

Метод **sendMessageToQueue** застарілий і буде вимкнений — у нових інтеграціях беріть sendMessage.

Повідомлення зберігається в діалозі контакту від імені «API» — його видно в розділі [Діалоги та листування](https://support.watbot.org/uk/chatbots/messages/dialogs). Сценарій бота воно не запускає.

## sendMessage

Надсилає контакту текст, зображення або файл.

```endpoint
POST https://watbot.org/api/v1/sendMessage
```

Контакт задається одним із двох способів: за ID контакту — `contact_id`, або за ботом та ID у месенджері — `bot_id`, `messenger` і `contact_external_id` разом.

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | число | так, якщо немає `messenger` | ID контакту |
| `bot_id` | число | так, якщо немає `contact_id` | ID бота |
| `messenger` | рядок | так, якщо немає `contact_id` | Месенджер контакту: `telegram`, `max`, `viber`, `vk` або `web` (чат на сайті) |
| `contact_external_id` | рядок | так, якщо немає `contact_id` | ID контакту в месенджері, до 255 символів, — див. нижче |
| `text` | рядок | так, якщо немає `image` і `file` | Текст повідомлення. Із зображенням чи файлом — підпис до них |
| `image` | рядок | так, якщо немає `text` і `file` | Посилання на зображення |
| `file` | рядок | так, якщо немає `text` і `image` | Посилання на файл |
| `filename` | рядок | ні | Назва файлу для одержувача. Кирилиця замінюється латиницею, символи, крім літер, цифр, `.`, `_` і `-`, — знаком `_` |

Що передавати в `contact_external_id`:

| `messenger` | Значення |
|---|---|
| `telegram` | ID користувача в Telegram (поле `telegram_id` контакту) або його телефон |
| `max` | ID користувача в MAX (поле `max_user_id`) або телефон |
| `viber` | ID користувача у Viber (поле `viber_id`) або телефон |
| `vk` | ID користувача ВКонтакте — `700123456` (попередній запис `vk700123456` теж підходить) — або телефон |
| `web` | Ідентифікатор відвідувача чату на сайті |

Телефон порівнюється з номером контакту (поле `phone` у відповідях методів контактів) символ у символ. Найнадійніше передавати `contact_id` — його повертають методи [контактів](https://support.watbot.org/uk/api/contacts).

Якщо передано і `image`, і `file`, піде зображення.

```bash title="Запит: текст"
curl -X POST "https://watbot.org/api/v1/sendMessage" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Олено, ваше замовлення № 1042 передано в доставку."}'
```

```bash title="Запит: файл за ID у Telegram"
curl -X POST "https://watbot.org/api/v1/sendMessage" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "contact_external_id": "123456789",
    "file": "https://example.com/invoices/1042.pdf",
    "filename": "Рахунок 1042.pdf",
    "text": "Рахунок на оплату"
  }'
```

```json title="Відповідь 200"
{
  "success": true
}
```

```json title="Відповідь 404"
{
  "message": "Контакт не знайдено"
}
```

**Ліміт надсилання.** Не більше 10 повідомлень за 10 секунд в один месенджер. Лічильник ведеться на акаунт окремо для кожного месенджера: 10 секунд відлічуються від першого повідомлення, потім лічильник обнуляється. Відхилені запити до лічильника не йдуть і вікно не подовжують. Відповідь `429` приходить із заголовком `Retry-After` — через скільки секунд можна повторити. Загальний ліміт запитів до API діє окремо — див. [Обмеження](https://support.watbot.org/uk/api#обмеження).

Помилки методу (загальні — у розділі [Помилки](https://support.watbot.org/uk/api#помилки)):

| Код | Коли | Відповідь |
|---|---|---|
| `404` | Контакт або бота не знайдено серед ваших: такого ID немає, він належить іншому акаунту або видалений; контакт за `messenger` і `contact_external_id` не знайдено в боті | `{"message": "Контакт не знайдено"}` або `{"message": "Бота не знайдено"}` |
| `422` | Немає ні `text`, ні `image`, ні `file`; посилання в `image` чи `file` — не адреса; `contact_id` або `bot_id` — не ціле додатне число | `{"message": "…", "errors": {…}}` |
| `429` | Перевищено ліміт надсилання в цей месенджер | `{"error": "Досягнуто ліміту надсилання повідомлень для telegram"}` |
| `501` | Контакт із каналу, у який надсилання більше не підтримується | `{"error": "Наразі надсилання повідомлень у месенджер … не підтримується"}` |

Тексти помилок приходять мовою із заголовка `Accept-Language`.

## sendMessageToQueue

> [!WARNING]
> Метод застарілий і буде вимкнений 1 грудня 2026 року — використовуйте [sendMessage](https://support.watbot.org/uk/api/messages#sendmessage). До вимкнення кожна відповідь методу приходить із заголовками `Deprecation: true` і `Sunset: Tue, 01 Dec 2026 00:00:00 GMT`. З 1 грудня 2026 року (00:00 UTC) метод відповідає кодом `410`: `{"error": "This API method was removed on 2026-12-01.", "code": "method_removed"}`.

Ставить текстове повідомлення контакту в чергу. Черга обробляється раз на хвилину.

```endpoint
POST https://watbot.org/api/v1/sendMessageToQueue
```

Контакт шукається серед контактів усіх ваших ботів, а з `bot_id` — лише серед контактів цього бота. Вкажіть хоча б один із параметрів `contact_id`, `bitrix_contact_id`, `phone`; якщо вказати кілька, контакт має відповідати всім. Якщо під `phone` або `bitrix_contact_id` підходять кілька контактів, а `bot_id` не передано, повідомлення ставиться одному з них: спершу контакту месенджера, у який метод уміє надсилати, і який не заблокував бота, потім із точним збігом телефону в полі `phone` (WhatsApp), потім із найсвіжішим листуванням. Кому пішло повідомлення, видно із заголовків відповіді `X-Contact-Id` і `X-Contact-Ambiguous: true`. З `bot_id` вибір не робиться: якщо і в цьому боті підходять кілька контактів, метод відповідає `422` і повідомлення не ставить — вкажіть `contact_id`.

| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| `contact_id` | число | один із трьох | ID контакту |
| `bitrix_contact_id` | число | один із трьох | ID контакту в Бітрікс24, з яким пов'язаний контакт бота |
| `phone` | рядок | один із трьох | Телефон контакту, до 20 символів. Пробіли, дужки, дефіси й `+` прибираються, початкова `8` замінюється на `7` |
| `bot_id` | число | ні | ID бота, від якого надіслати. Передайте, коли номер або ID у Бітрікс24 є в контактів кількох ваших ботів |
| `text` | рядок | так | Текст повідомлення, до 1024 символів |
| `message_id` | рядок | ні | Ваш ідентифікатор повідомлення, до 255 символів. Захищає від дублів: повторний запит із тим самим `message_id` тому самому контакту не ставить повідомлення вдруге, поки попереднє чекає надсилання або вже надіслане, — відповідь та сама `201`. Після помилки надсилання повтор ставить повідомлення знову |

```bash title="Запит"
curl -X POST "https://watbot.org/api/v1/sendMessageToQueue" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Нагадуємо: ви записані на завтра, 11:00."}'
```

```json title="Відповідь 422"
{
  "error": "Контакт не знайдено"
}
```

```json title="Відповідь 422: потрібен contact_id"
{
  "message": "Під ці дані в боті підходять кілька контактів — вкажіть contact_id.",
  "errors": {
    "contact_id": ["Під ці дані в боті підходять кілька контактів — вкажіть contact_id."]
  }
}
```

Успішна відповідь — код `201` з порожнім тілом і ID вибраного контакту в заголовку `X-Contact-Id`. Очищений номер із `phone` має збігтися з номером контакту символ у символ. Контакту з каналу, у який надсилання більше не підтримується, метод відповідає `422`: `{"error": "Месенджер не підтримується"}`. Контактам, які відписалися від бота або заблокували його, повідомлення з черги не надсилається — воно знімається з черги під час наступного розбору.