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

Через 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.org/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.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": "Рахунок на оплату"
  }'

{
  "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.org/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": "Месенджер не підтримується"}. Контактам, які відписалися від бота або заблокували його, повідомлення з черги не надсилається — воно знімається з черги під час наступного розбору.