# Сообщения

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

Метод **sendMessageToQueue** устарел и будет отключён — в новых интеграциях берите sendMessage.

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

## sendMessage

Отправляет контакту текст, картинку или файл.

```endpoint
POST https://watbot.ru/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.ru/api/contacts).

Если переданы и `image`, и `file`, уйдёт картинка.

```bash title="Запрос: текст"
curl -X POST "https://watbot.ru/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.ru/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.ru/api#ограничения).

Ошибки метода (общие — в разделе [Ошибки](https://support.watbot.ru/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.ru/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.ru/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.ru/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": "Мессенджер не поддерживается"}`. Отписавшимся от бота и заблокировавшим его сообщение из очереди не отправляется — оно снимается с очереди при очередном разборе.