Marx Bot API

HTTP API, через которое программа бота читает и отправляет сообщения в мессенджере Marx.

Адрес

Все методы — под адресом https://api.bot.marx.moscow/api/bot/v1/. Только HTTPS. Тела запросов и ответов — JSON в UTF-8 с заголовком Content-Type: application/json; загрузка файла — multipart/form-data. Список методов — на странице Методы.

Создать бота и получить токен

Ботов создаёт системный бот @marxbot («Создатель ботов») в приложении Marx.

1. В настройках приложения нажмите «Создать бота» или найдите @marxbot и откройте чат с ним.
2. Отправьте /newbot.
3. Пришлите имя бота: от 1 до 64 символов. Его видят в чатах и в профиле.
4. Пришлите имя пользователя: от 5 до 32 символов, латиница, цифры и _, в конце — bot. Например, dacha_weather_bot.
5. В ответе — токен вида marx_pat_…. Нажмите на него, чтобы скопировать.

С токеном любой пишет от имени бота: храните его как пароль. Новый токен выдаёт /token; прежний перестаёт работать сразу.

У одного человека — до 20 ботов; создать можно до 5 ботов в сутки; токен можно менять до 10 раз в час.

Добавить бота в группу и в канал

Личный чат

Начать личный чат бот не может. Чат появляется, когда человек находит бота по имени пользователя и пишет ему; приложение показывает кнопку «Начать», которая отправляет /start.

Группа

Бота добавляют как обычного участника: в профиле группы — «Добавить участников», найти по @имени. Добавить может любой, у кого есть право добавлять участников; владелец бота для этого не нужен. Участник группы может писать в неё, и бот тоже. Что бот получает из группы — в разделе Что видит бот.

Канал

В канале пишут только админы, поэтому бот должен быть админом: в профиле канала — «Добавить админа», найти по @имени, или «Сделать админом», если бот уже в канале. Это могут владелец канала и админы с правом «Назначать админов». Из канала бот не получает сообщений — он только публикует.

Авторизация

Каждый запрос несёт токен бота в заголовке:

Authorization: Bearer marx_pat_...

Нет заголовка, токен не того вида, отозван или неизвестен — 401:

curl https://api.bot.marx.moscow/api/bot/v1/me \
  -H "Authorization: Bearer marx_pat_not_a_real_token"

{"detail": "invalid api token"}

Ошибки

Ответ с кодом 2xx — успех. Остальные коды несут JSON с полем detail.

curl https://api.bot.marx.moscow/api/bot/v1/messages \
  -H "Authorization: Bearer $MARX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "нет chat_id"}'

{"detail": [{"type": "missing", "loc": ["body", "chat_id"], "msg": "Field required", "input": {"body": "нет chat_id"}}]}

429 и retry_after

При превышении предела ответ — 429, в code — имя предела из таблицы ниже, в retry_after и в заголовке Retry-After — через сколько секунд можно повторить. Тот же вид у 503 с code db_busy.

{"detail": "rate limit exceeded", "code": "bot.message.send", "retry_after": 17}

Подождите retry_after секунд и повторите запрос. Для POST /messages передавайте client_id: повтор с тем же client_id не создаст второе сообщение.

Пределы частоты

Пределы считаются на токен, кроме создания бота и смены токена — они на человека, владельца ботов. Окно — отрезок времени фиксированной длины от начала минуты, часа или суток по часам сервера, а не от первого запроса: счёт обнуляется на его границе.

Длинный опрос с timeout=30 — два запроса в минуту, далеко от предела bot.updates.