Сообщения#

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

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

Сообщение сохраняется в диалоге контакта от имени «API» — его видно в разделе Диалоги. Сценарий бота оно не запускает.

sendMessage#

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

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

Что передавать в contact_external_id:

Телефон сравнивается с номером контакта (поле phone в ответах методов контактов) символ в символ. Надёжнее всего передавать contact_id — его возвращают методы контактов.

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

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 передан в доставку."}'

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": "Счёт на оплату"
  }'

{
  "success": true
}

{
  "message": "Контакт не найден"
}

Лимит отправки. Не больше 10 сообщений за 10 секунд в один мессенджер. Счётчик ведётся на аккаунт отдельно по каждому мессенджеру: 10 секунд отсчитываются от первого сообщения, затем счётчик обнуляется. Отклонённые запросы в счётчик не идут и окно не продлевают. Ответ 429 приходит с заголовком Retry-After — через сколько секунд можно повторить. Общий лимит запросов к API действует отдельно — см. Ограничения.

Ошибки метода (общие — в разделе Ошибки):

Тексты ошибок приходят на языке из заголовка Accept-Language.

sendMessageToQueue#

Внимание

Метод устарел и будет отключён 1 декабря 2026 года — используйте 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"}.

Ставит текстовое сообщение контакту в очередь. Очередь разбирается раз в минуту.

Контакт ищется среди контактов всех ваших ботов, а с 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.

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."}'

{
  "error": "Контакт не найден"
}

{
  "message": "Под эти данные в боте подходят несколько контактов — укажите contact_id.",
  "errors": {
    "contact_id": ["Под эти данные в боте подходят несколько контактов — укажите contact_id."]
  }
}

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