Skip to content

api-notes.md

Latest commit

 

History

History
65 lines (43 loc) · 5.24 KB

api-notes.md

File metadata and controls

65 lines (43 loc) · 5.24 KB
Raw

Заметки по API Max

Этот файл нужен для коротких практических оговорок, которые важны разработчику, но перегружают главный README.

Long polling и webhook

Max Bot API может доставлять updates через long polling или webhook. Если у бота остались активные webhook-подписки, long polling может не получать ожидаемые updates. Поэтому bot.start() по умолчанию удаляет webhook-подписки перед запуском polling.

Long polling подходит для разработки и ручной проверки, но не должен быть основным production-режимом. Если marker не передан, API возвращает только последнее обновление, а не всю очередь событий за время недоступности бота.

С 11.05.2026 для long polling заявлены ограничения:

  • максимум 2 RPS;
  • timeout запроса 30 секунд;
  • максимум 100 событий в batch;
  • TTL событий 24 часа.

Для стабильной доставки событий используйте webhook-подписку: POST /subscriptions.

attachment.not.ready

После upload файл может быть ещё не готов к отправке как attachment. max-io повторяет отправку сообщения с backoff и поддерживает отмену через AbortSignal.

removeChatMember

Для групповых чатов chatId обычно отрицательный. Параметр block: true ведёт себя как ban: пользователь не может вернуться по ссылке. Отдельный стабильный unban endpoint пока не подтверждён.

Список чатов и добавление участников

GET /chats отсутствует в актуальной схеме и, по сообщениям upstream, возвращает 404. Сохраняйте chat_id из полученных updates и используйте getChat(chatId) для получения информации о чате.

addChatMembers по схеме добавляет участников только в групповой чат. Боту нужны права администратора add_remove_members; за один запрос допускается до 100 уникальных ID. Проверяйте failed_user_ids и failed_user_details в ответе: часть пользователей может не добавиться. Подписчиков канала этот метод не добавляет.

При этом уведомление в схеме сообщает, что с 9 сентября 2026 года работа метода ограничена, но не раскрывает характер ограничений. В более раннем уведомлении было указано плановое удаление с 30 сентября; в текущей схеме это утверждение отсутствует, сам endpoint по-прежнему описан. Проверяйте доступность в своём сценарии и обрабатывайте ошибки API.

deleteChat

Метод зависит от прав бота. Если у бота нет права delete, API возвращает success: false и сообщение о нехватке прав.

Схемы и живое поведение

OpenAPI-схема, Go SDK и фактическое поведение API иногда расходятся. Для новых публичных типов и методов лучше фиксировать источник: схема, runtime-проверка или payload из живого API.

Текущий ориентир для типизации — актуальный архив OpenAPI-схем xTCry/max-dev-openapi-schema, схема от 2026-08-18, версия Bot API 0.0.33.

Удаление компонентов из схемы не всегда означает отключение функции сервером; поведение следует подтверждать отдельно.

Схема schema_2026_07_22 указывает server URL https://platform-api2.max.ru. В max-io дефолт пока остаётся https://platform-api.max.ru, но endpoint можно переопределить через new Bot(token, { apiBaseUrl }) или createClient(token, { baseUrl }). У альтернативного endpoint может быть сертификат, который не доверен в конкретной ОС или Node.js runtime; в таком случае запрос завершится TLS-ошибкой до обращения к API.

Метод обновления команд через PATCH /me/commands описан в schema_2026_07_22.