Одиночные сообщения

В отличие от рассылки, одиночное сообщение адресовано одному контакту. Это полезно для поддержки и ответов на запросы.

Из кабинета

1. Контакты → откройте карточку контакта.
2. Нажмите Написать.
3. Введите текст. Поддержки медиа в этом UI пока нет — для медиа используйте send-media через REST.
4. Отправить.

Сообщение попадёт пользователю от имени бота и появится в Диалогах с direction='out'.

Через REST API

curl -X POST "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/send" \
     -H "X-API-Key: mbs_..." \
     -H "Content-Type: application/json" \
     -d '{"userId":"123456789","text":"Здравствуйте! Чем помочь?"}'

Параметры:

Поле	Тип	Описание
userId	string	external_user_id контакта (число, обёрнутое в строку, либо UUID для Max)
text	string	текст сообщения, до 4000 символов

Ответ:

{
  "ok": true,
  "id": "5d31...",
  "direction": "out",
  "text": "Здравствуйте! Чем помочь?",
  "created_at": "2026-04-30T15:23:01Z"
}

Под капотом:

• для Telegram — POST /bot<TOKEN>/sendMessage с chat_id=userId;
• для Max — POST /messages?chat_id=<userId> с заголовком Authorization.

Отправка медиа (приватный API кабинета)

В кабинете доступна отправка медиа через приватный эндпоинт:

POST /api/bots/:id/send-media
Content-Type: multipart/form-data
Authorization: Bearer <jwt>

userId=123456
text=Прайс-лист
file=@price.pdf
kind=file

В REST API v1 этой возможности пока нет — отправка с медиа доступна только через рассылку (/broadcast) или приватный API.

Когда userId неизвестен

Если у вас на руках только username, а external_user_id — нет, нельзя написать первым: Telegram запрещает ботам инициировать диалог. Дождитесь, пока пользователь напишет /start, после чего external_user_id появится в контактах.

Обработка ошибок

Код	Значение
400 Bad Request	пустой text или невалидный userId
404 Not Found	бот не найден или не принадлежит вам
400 Personal send requires bot token	у бота не указан токен — отправка невозможна
502 Bad Gateway	Telegram/Max ответил ошибкой; в provider поле — детали