Marx Bot API

The HTTP API a bot's program uses to read and send messages in the Marx messenger.

Address

Every method is under https://api.bot.marx.moscow/api/bot/v1/. HTTPS only. Request and response bodies are JSON in UTF-8 with Content-Type: application/json; a file upload is multipart/form-data. The list of methods: Methods.

Create a bot and get its token

Bots are created by the system bot @marxbot («Создатель ботов», the bot maker) in the Marx app. It answers in Russian.

1. In the app's settings tap «Создать бота» (Create bot), or find @marxbot and open a chat with it.
2. Send /newbot.
3. Send the bot's name: 1 to 64 characters. It is shown in chats and in the profile.
4. Send the username: 5 to 32 characters, Latin letters, digits and _, ending in bot. For example, dacha_weather_bot.
5. The answer holds a token like marx_pat_…. Tap it to copy.

Anyone with the token writes as the bot: keep it like a password. /token issues a new one; the old one stops working at once.

One person may own up to 20 bots, create up to 5 bots a day and change a token up to 10 times an hour.

Add a bot to a group or a channel

Direct chat

A bot cannot start a direct chat. The chat appears when a person finds the bot by its username and writes to it; the app shows a «Начать» (Start) button that sends /start.

Group

A bot is added like any member: in the group's profile, «Добавить участников» (Add members) and find it by @username. Anyone allowed to add members may do it; the bot's owner is not needed. Group members may post, and so may the bot. What the bot gets from a group: What a bot sees.

Channel

Only admins post in a channel, so the bot must be an admin: in the channel's profile, «Добавить админа» (Add admin) and find it by @username, or «Сделать админом» (Make admin) if the bot is already in the channel. The channel's owner and admins with the right «Назначать админов» (Appoint admins) can do it. A bot gets no messages from a channel; it only publishes there.

Authorization

Every request carries the bot's token in a header:

Authorization: Bearer marx_pat_...

No header, a token of the wrong form, a revoked or unknown token: 401.

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

{"detail": "invalid api token"}

Errors

A 2xx status is success. Other statuses carry JSON with a detail field.

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

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

429 and retry_after

A request over a limit gets 429, with the limit's name from the table below in code and the number of seconds until a retry may succeed in retry_after and in the Retry-After header. A 503 with code db_busy has the same form.

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

Wait retry_after seconds and send the request again. For POST /messages pass a client_id: a repeat with the same client_id does not create a second message.

Rate limits

Limits count per token, except creating a bot and changing a token, which count per person, the bots' owner. A window is a fixed stretch of time starting at the minute, hour or day by the server's clock, not at the first request: the count resets at its end.

Long polling with timeout=30 makes two requests a minute, far below the bot.updates limit.