HTTP API

Базовый путь /v1 на gateway (http://localhost:8080/v1 в примерах).

• Каждый запрос — с Authorization: Bearer <BOT_TOKEN>. Без него — только GET /healthz и POST /hooks/<секрет>.
• Тела — JSON (Content-Type: application/json), если не сказано иное.
• id — строки, время — Unix в миллисекундах.
• id личного чата — id собеседника.
• Запросы, которым нечего вернуть, отвечают {}.

Ошибки

Ошибка — HTTP-код и тело:

{"error": "message text is too long", "code": "bad_request"}

code	Код	Когда
unauthorized	401	Нет токена или он неверный.
bad_request	400	Неверные параметры или отказ ядра: слишком длинный текст, чужое сообщение, закрытый опрос…
not_found	404	Нет такого чата, сообщения, хука или пути.
webhook	409	GET /v1/updates при заданном webhook или UPDATES=off.

Бот

Получить бота

GET /v1/me

→ {id, name, invite_url, about, commands}. invite_url — ссылка, открывающая чат с ботом в приложениях.

Сменить имя или описание

PATCH /v1/me
{"name": "Погода", "about": "Прогноз для любого города"}

Не указанные поля остаются как есть. about — до 512 символов.

Задать команды

PUT /v1/me/commands
{"commands": [{"name": "weather", "description": "Прогноз", "args": "<город>"}]}

До 100 команд; [] — убрать. См. Команды и кнопки.

Задать аватар

PUT /v1/me/avatar
Content-Type: image/jpeg

<байты картинки>

JPEG, PNG или WebP до 20 МБ; обрезается до квадрата и уменьшается сам.

Чаты

Список чатов

GET /v1/chats

→ массив Chat.

Получить чат

GET /v1/chats/{chat}

→ Chat.

Принять запрос

POST /v1/chats/{chat}/accept

Принимает запрос на переписку или приглашение в группу (нужно при ACCEPT_REQUESTS=contacts) → Chat.

Создать группу

POST /v1/groups
{"name": "Дежурные", "members": ["u7f…", "u2c…"]}

→ Chat.

Сообщения

Список сообщений

GET /v1/chats/{chat}/messages?before=&limit=

Сообщения из базы бота, старые первыми. before — время в мс; limit — 1–100, по умолчанию 50. → массив Message.

Получить сообщение

GET /v1/chats/{chat}/messages/{msg}

Отправить текст

POST /v1/chats/{chat}/messages
{"text": "Привет, @Анна", "reply_to": "m1…",
 "mentions": [{"user": "u7f…", "offset": 8, "length": 5}],
 "buttons": [[{"text": "OK", "data": "ok"}]]}

Обязателен только text. offset и length упоминаний — в единицах UTF-16, как длина строки в JavaScript. Кнопки: до 3 рядов по 2. → Message.

Отправить файл

POST /v1/chats/{chat}/files
Content-Type: multipart/form-data

Поле
file	Файл (до 300 МБ).
caption	Подпись.
reply_to	id сообщения.
kind	photo, video, voice или file; по умолчанию — по типу файла. Фото: JPEG, PNG, WebP.
duration_ms, width, height	Для видео и голосовых.

Превью фото gateway делает сам. → Message.

curl -H "Authorization: Bearer $BOT_TOKEN" -F file=@chart.png -F caption='CPU за час' \
  localhost:8080/v1/chats/u7f…/files

Скачать вложение

GET /v1/chats/{chat}/messages/{msg}/file

Байты файла с его Content-Type. Скачивается и расшифровывается при первом запросе.

Изменить сообщение

PATCH /v1/chats/{chat}/messages/{msg}
{"text": "Выкачено ✅", "buttons": []}

Правит свой текст или подпись. Без text текст остаётся; без buttons кнопки остаются, [] убирает их. Сообщения с кнопками правятся в любое время. → Message.

Удалить сообщение

DELETE /v1/chats/{chat}/messages/{msg}?for=all

for=all (по умолчанию) — у всех, только свои; for=me — только в базе бота.

Реакция

PUT /v1/chats/{chat}/messages/{msg}/reaction
{"emoji": "👍"}

DELETE /v1/chats/{chat}/messages/{msg}/reaction убирает реакцию бота.

Отметить прочитанным

POST /v1/chats/{chat}/read
{"up_to": "m9…"}

Отмечает прочитанным до up_to, или всё, если он пуст.

Опросы

Отправить опрос

POST /v1/chats/{chat}/polls
{"question": "Обед?", "options": ["Пицца", "Хинкали"], "multiple": false,
 "close_ts": 1791373600000, "reply_to": ""}

→ Message с poll.

Проголосовать

POST /v1/chats/{chat}/messages/{msg}/vote
{"options": [1]}

Номера вариантов с 0; [] — забрать голос.

Закрыть опрос

POST /v1/chats/{chat}/messages/{msg}/close

Только свои опросы.

Кнопки

Ответить на нажатие

POST /v1/presses/{press_id}/answer
{"text": "Готово"}

Всплывающая строка только у нажавшего; до 200 символов, не позже минуты после нажатия.

Входящие

GET /v1/updates?offset=&timeout=&limit=

→ массив Update. См. Входящие.

Хуки

Доступны при заданном HOOKS_URL. См. Входящие хуки.

Запрос
GET /v1/hooks?chat=	Хуки чата (без chat — все).
POST /v1/hooks {chat_id, format}	Завести → {id, chat_id, format, ts, url}; url показывается только здесь.
DELETE /v1/hooks/{id}	Удалить.
POST /hooks/<секрет>	Отправить в хук; без токена.