REST API → Отправка сообщений

POST /api/v1/bots/{id}/send

Отправляет текстовое сообщение конкретному пользователю от имени вашего бота.

Scope: write

Тело запроса

{
  "userId": "123456789",
  "text": "Здравствуйте! Чем помочь?"
}

Поле	Тип	Обязательно	Описание
userId	string	да	external_user_id контакта (id Telegram/Max)
text	string	да	до 4000 символов

Запрос

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

Ответ

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

• id — публичный UUID сообщения в MaxBotStat (не путать с message_id Telegram).
• provider — необработанный ответ от Telegram/Max API. У Telegram там result.message_id — это id сообщения внутри Telegram.

Что происходит под капотом

Для Telegram:

POST https://api.telegram.org/bot<TOKEN>/sendMessage
Content-Type: application/json

{ "chat_id": "<userId>", "text": "<text>" }

Для Max:

POST https://platform-api.max.ru/messages?chat_id=<userId>
Authorization: <ACCESS_TOKEN>
Content-Type: application/json

{ "text": "<text>" }

После успешной отправки запись добавляется в messages с direction='out' и срабатывает webhook-событие message.outbound (если у вас есть подписки).

Ошибки

HTTP	Сообщение	Что значит
400	userId and text required	пропущено одно из обязательных полей
400	Personal send requires bot token	у бота не указан токен — отправка невозможна
403	Недостаточно прав: требуется scope "write"	ключ выпущен только с read
404	Bot not found	бот не принадлежит вам
502	Provider send failed	Telegram/Max ответил ошибкой; в provider — детали

Пример 502:

{
  "message": "Provider send failed",
  "provider": {
    "ok": false,
    "error_code": 403,
    "description": "Forbidden: bot was blocked by the user"
  }
}

Примеры

Node.js

const r = await fetch(`https://capybara.maxbotstat.ru/api/v1/bots/${botId}/send`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.MBS_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: '123456', text: 'Привет!' }),
})
const data = await r.json()
if (!r.ok) throw new Error(data.message)

Python

import requests, os

r = requests.post(
    f'https://capybara.maxbotstat.ru/api/v1/bots/{bot_id}/send',
    headers={'X-API-Key': os.environ['MBS_KEY']},
    json={'userId': '123456', 'text': 'Привет!'},
    timeout=15,
)
r.raise_for_status()
print(r.json())

PHP

$ch = curl_init("https://capybara.maxbotstat.ru/api/v1/bots/{$botId}/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: {$_ENV['MBS_KEY']}", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["userId" => "123456", "text" => "Привет!"]),
    CURLOPT_RETURNTRANSFER => true,
]);
$resp = curl_exec($ch);

Ограничения

• Только текст. Для медиа используйте кабинет или /broadcast с файлом.
• Telegram запрещает ботам инициировать диалог с незнакомым пользователем — userId должен быть из контактов бота.
• Лимиты Telegram: 30 сообщений в секунду, 1 в секунду в одном диалоге. MaxBotStat не разгоняет — ретраи делайте сами по 429.

Идемпотентность

Если при 502 вы повторяете запрос — Telegram, возможно, уже доставил сообщение, и пользователь увидит дубль. Защититесь:

• сохраняйте message_id после первого успеха;
• при ретрае проверяйте через GET /api/v1/bots/{id}/messages?userId=... — есть ли уже исходящее сообщение с нужным текстом за последние 30 секунд.