Methods#

class maxo.bot.methods.AddMembers[исходный код]#

Добавление участников в групповой чат

Добавляет участников в групповой чат

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата с соответствующим правом add\_remove\_members. Чтобы получить информацию о правах бота, используйте [GET /chats/-chatId-/members/admins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins). Подробнее о правах - в описании объекта [Chat](https://dev.max.ru/docs-api/objects/Chat)

>Добавить подписчиков в канал с помощью этого метода нельзя

**Пример запроса**:

curl -X POST "https://platform-api2.max.ru/chats/{chatId}/members"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "user_ids": ["{user_id_1}", "{user_id_2}"]
}'

Источник: https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата

user_ids: Annotated[list[int], <Marker 'body'>]#

class maxo.bot.methods.AnswerOnCallback[исходный код]#

Ответ на callback

Этот метод используется для отправки ответа после того, как пользователь нажал на кнопку. Ответом может быть обновленное сообщение и/или одноразовое уведомление для пользователя

#### Пример запроса:

curl -X POST "https://platform-api2.max.ru/answers?callback_id=callback_id"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
    "message": {
      "text": "Это сообщение с кнопкой-ссылкой",
      "attachments": [
        {
          "type": "inline_keyboard",
          "payload": {
            "buttons": [
              [
                {
                  "type": "link",
                  "text": "Откройте сайт",
                  "url": "https://example.com"
                }
              ]
            ]
          }
        }
      ]
    }
  }'

Источник: https://dev.max.ru/docs-api/methods/POST/answers

callback_id: Annotated[str, <Marker 'query'>]#

Идентификатор кнопки, на которую нажал пользователь

Идентификатор можно получить в обновлениях о событиях через [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions) или [Long Polling](https://dev.max.ru/docs-api/methods/GET/updates)

Получение обновлений с помощью [Long Polling](https://dev.max.ru/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий - этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions)

Когда пользователь нажмёт на кнопку, МАКС отправит событие, содержащее объект [Update](https://dev.max.ru/docs-api/objects/Update) с типом message\_callback и идентификатором кнопки в поле updates[i].callback.callback\_id

message: Omitted, <Marker 'body'>]#: Заполните это, если хотите изменить текущее сообщение

notification: Omitted, <Marker 'body'>]#: Заполните это, если хотите просто отправить одноразовое уведомление пользователю

class maxo.bot.methods.DeleteAdmin[исходный код]#

Отменить права администратора в групповом чате или канале

Лишает пользователя или бота прав администратора в групповом чате или канале. При этом из чата и канала они не исключаются

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала с соответствующим правом add\_admins. Чтобы получить информацию о правах бота, используйте [GET /chats/-chatId-/members/admins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins). Подробнее о правах - в описании объекта [Chat](https://dev.max.ru/docs-api/objects/Chat)

Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/chats/{chatId}/members/admins/{userId}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

user_id: Annotated[int, <Marker 'path'>]#: Идентификатор пользователя или бота, которого надо лишить прав администратора

class maxo.bot.methods.DeleteChat[исходный код]#

Удаление группового чата

Удаляет групповой чат для всех участников

#### Пример запроса:

curl -X DELETE "https://platform-api.max.ru/chats/{chatId}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-

chat_id: Annotated[int, <Marker 'path'>]#: ID чата

class maxo.bot.methods.DeleteMessage[исходный код]#

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

Удаляет сообщение в диалоге или чате, если бот имеет разрешение на удаление сообщений

#### Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/messages?message_id={message_id}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/messages

message_id: Annotated[str, <Marker 'query'>]#: ID удаляемого сообщения

class maxo.bot.methods.EditBotInfo[исходный код]#

Изменение информации о текущем боте.

Позволяет изменить информацию о текущем боте. Заполняйте только те поля, которые требуется обновить. Все остальные останутся без изменений.

Источник: https://dev.max.ru/docs-api/methods/PATCH/me

first_name: Omitted, <Marker 'body'>]#

last_name: Omitted, <Marker 'body'>]#

description: Omitted, <Marker 'body'>]#

commands: Omitted, <Marker 'body'>]#

photo: Omitted, <Marker 'body'>]#

class maxo.bot.methods.EditChat[исходный код]#

Изменение информации о групповом чате или канале

Позволяет редактировать информацию о групповом чате или канале, включая название, иконку и закреплённое сообщение

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала

Пример запроса:

curl -X PATCH "https://platform-api2.max.ru/chats/{chatId}"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "icon": { "url": "https://example.com/image.jpg" },
  "title": "Название чата",
  "notify": true
}'

Источник: https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-

chat_id: Annotated[int, <Marker 'path'>]#: ID чата

icon: Omitted, <Marker 'body'>]#

notify: Omitted, <Marker 'body'>]#: Если true, участники получат системное уведомление об изменении

pin: Omitted, <Marker 'body'>]#

//dev.max.ru/docs-api/methods/DELETE/chats/%7BchatId%7D/pin)

Type:: ID сообщения для закрепления в чате. Чтобы удалить закреплённое сообщение, используйте метод [unpin](https

title: Omitted, <Marker 'body'>]#

class maxo.bot.methods.EditMessage[исходный код]#

Редактировать сообщение

Метод позволяет редактировать сообщения, отправленные ботом

#### Ограничения при редактировании сообщений:

В диалогах с ботом:
- сообщения с кнопками [inline\_keyboard](https://dev.max.ru/docs-api#Как%20добавить%20кнопки) редактируются независимо от срока давности
- остальные сообщения редактируются, если они отправлены менее 7 суток назад
В групповых чатах и каналах любые сообщения редактируются независимо от срока давности

#### Пример запроса:

curl -X PUT "https://platform-api2.max.ru/messages?message_id=message_id"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "text": "Изменённый текст"
}'

Источник: https://dev.max.ru/docs-api/methods/PUT/messages

message_id: Annotated[str, <Marker 'query'>]#: ID редактируемого сообщения

attachments: LocationAttachment] | None, <Marker 'body'>]#: Вложения сообщения. Если поле равно null, изменений не произойдет. Если пусто, все вложения будут удалены

link: NewMessageLink | None, <Marker 'body'>]#: Ссылка на сообщение

text: Annotated[str | None, <Marker 'body'>]#: Новый текст сообщения

format: Omitted, <Marker 'body'>]#

//dev.max.ru/docs-api#Форматирование%20текста%20в%20сообщениях)

Type:: Если установлен, текст сообщения будет форматирован данным способом. Для подробной информации загляните в раздел [Форматирование](https

notify: Omitted, <Marker 'body'>]#: Если false, участники чата не будут уведомлены (по умолчанию true)

class maxo.bot.methods.GetAdmins[исходный код]#

Получение списка администраторов группового чата или канала

Возвращает список всех администраторов группового чата и канала (пользователей и ботов) и их данные, например: идентификатор, имя, никнейм, время последней активности, URL аватара, флаги администратора, владельца и бота, а также права на управление каналом или групповым чатом для пользователей-администраторов

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала. Подробнее о правах - в описании объекта [Chat](https://dev.max.ru/docs-api/objects/Chat)

Пример запроса:

curl -X GET "https://platform-api2.max.ru/chats/{chatId}/members/admins"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

class maxo.bot.methods.GetChat[исходный код]#

Получение информации о групповом чате или канале

Возвращает информацию о групповом чате или канале по его ID

Пример запроса:

curl -X GET "https://platform-api2.max.ru/chats/{chatId}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatId-

chat_id: Annotated[int, <Marker 'path'>]#

//dev.max.ru/docs-api#Получение%20chat_id)

Type:: ID запрашиваемого группового чата или канала. Как получить ID - в [разделе «Получение chat_id»](https

class maxo.bot.methods.GetChatByLink[исходный код]#

Получение информации о канале по его ссылке

Возвращает информацию о канале по его публичной ссылке. Метод доступен только для каналов - получить информацию о чате по публичной ссылке не получится

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatLink-

chat_link: Annotated[str, <Marker 'path'>]#: Публичная ссылка на канал

class maxo.bot.methods.GetChats[исходный код]#

Получение списка всех групповых чатов и каналов для бота

> ! Начиная **с июня 2026** метод GET /chats больше не поддерживается, и API не предоставляет готовой возможности для получения списка групповых чатов и каналов, в которые добавлен бот

Если вам требуется получить для бота такой список, используйте [POST /subscriptions](https://dev.max.ru/docs-api/methods/POST/subscriptions). При этом задача сбора, хранения и поддержки идентификаторов ложится на разработчика: он выбирает способ реализации исходя из своей инфраструктуры и сценария использования

**Возможный алгоритм действий:**

**Cоздайте подписку** через [POST /subscriptions](https://dev.max.ru/docs-api/methods/POST/subscriptions) и укажите нужные типы событий в параметре update\_types[], например, bot\_added или bot\_started. Список поддерживаемых типов событий - в объекте [Update](https://dev.max.ru/docs-api/objects/Update)
**Получите chat\_id в событии** - о том, как это сделать, см. в [разделе «Получение chat_id»](https://dev.max.ru/docs-api#Получение%20chat_id)
**Сохраните chat\_id**:
- разверните на своей стороне хранилище данных
- при получении каждого события с chat\_id - сохраните его, если он ещё не сохранён
- обработайте возможные дубли (одно и то же событие может прийти повторно)
- удалите chat\_id при возникновении соответствующих событий, например, bot\_removed
**Используйте сохранённый chat\_id для вызовов API**. После того как chat\_id окажется в вашем хранилище, вы сможете использовать его во всех методах, где он требуется:
- [POST /messages](https://dev.max.ru/docs-api/methods/POST/messages) - отправить сообщение в чат
- [GET /chats/{chat\_id}/members](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members) - получить участников группового чата или канала
- [POST /chats/{chat\_id}/actions](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions) - отправить действия бота в групповой чат
- и любые другие методы, принимающие chat\_id как параметр

> Использование [Long Polling](https://dev.max.ru/docs-api#Long%C2%A0Polling) для получения списка чатов и каналов для бота не предусмотрено

Возвращает список групповых чатов и каналов, в которые добавлен бот, информацию о каждом чате и маркер для перехода к следующей странице списка

Пример запроса:

curl -X GET "https://platform-api.max.ru/chats"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats

count: Omitted, <Marker 'query'>]#: Количество запрашиваемых чатов

marker: Omitted, <Marker 'query'>]#: Указатель на следующую страницу данных. Для первой страницы передайте null

class maxo.bot.methods.GetMembers[исходный код]#

Получение участников группового чата или канала

Возвращает список участников группового чата и их данные, например: идентификатор, имя, никнейм, время последней активности, URL аватара, флаги администратора, владельца и бота, а также права на управление каналом или групповым чатом для пользователей-администраторов. Подробнее о правах - в описании объекта [Chat](https://dev.max.ru/docs-api/objects/Chat)

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала

Пример запроса:

curl -X GET "https://platform-api2.max.ru/chats/{chatId}/members"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

count: Omitted, <Marker 'query'>]#: Количество участников, которых нужно вернуть в ответе

marker: Omitted, <Marker 'query'>]#: Указатель на следующую страницу данных

user_ids: Omitted, <Marker 'query'>]#: Список ID пользователей, чьё членство нужно получить. Когда этот параметр передан, параметры count и marker игнорируются

class maxo.bot.methods.GetMembership[исходный код]#

Получение информации о членстве бота в групповом чате или канале

Возвращает информацию о членстве бота в групповом чате или канале, общую информацию о нём, а также список [доступных прав доступа](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins#Доступные%20права%20администраторов). Бот идентифицируется с помощью токена доступа

Пример запроса:

curl -X GET "https://platform-api2.max.ru/chats/{chatId}/members/me"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

class maxo.bot.methods.GetMessageById[исходный код]#

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

Возвращает сообщение по его ID

#### Пример запроса:

curl -X GET "https://platform-api2.max.ru/messages/{messageId}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/messages/-messageId-

message_id: Annotated[str, <Marker 'path'>]#: ID сообщения (mid), чтобы получить одно сообщение в чате

class maxo.bot.methods.GetMessages[исходный код]#

Получение сообщений

Метод возвращает информацию о сообщении или массив сообщений из чата. Для выполнения запроса нужно указать один из параметров - chat\_id или message\_ids:

chat\_id - метод возвращает массив сообщений из указанного чата. Сообщения возвращаются в обратном порядке: последние сообщения будут первыми в массиве. Как получить ID - в [разделе «Получение chat_id»](https://dev.max.ru/docs-api#Получение%20chat_id)

message\_ids - метод возвращает информацию о запрошенных сообщениях. Можно указать один идентификатор или несколько

#### Пример запроса с использованием chat\_id:

curl -X GET "https://platform-api2.max.ru/messages?chat_id={chat_id}"       -H "Authorization: {access_token}"

#### Пример запроса с использованием message\_ids:

curl -X GET "https://platform-api2.max.ru/messages?message_ids={message_id1},{message_id2}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/messages

chat_id: Omitted, <Marker 'query'>]#

//dev.max.ru/docs-api#Получение%20chat_id)

Type:: ID чата, чтобы получить сообщения из определённого чата. Обязательный параметр, если не указан message\_ids. Как получить ID - в [разделе «Получение chat_id»](https

count: Omitted, <Marker 'query'>]#: Максимальное количество сообщений в ответе

from_: Omitted, <Marker 'query'>]#: Время, до которого будут запрошены все сообщения с начала чата (в формате Unix timestamp)

message_ids: Omitted, <Marker 'query'>]#: Список ID сообщений, которые нужно получить (через запятую). Обязательный параметр, если не указан chat\_id

to: Omitted, <Marker 'query'>]#: Время, начиная с которого будут запрошены все сообщения до конца чата (в формате Unix timestamp)

class maxo.bot.methods.GetMyInfo[исходный код]#

Получение информации о боте

Метод возвращает информацию о боте, который идентифицируется с помощью токена доступа access\_token. В ответе приходит [объект User с вариантом наследования BotInfo](https://dev.max.ru/docs-api/objects/User), который содержит идентификатор бота, его название, никнейм, время последней активности, описание и аватар (при наличии)

#### Пример запроса:

curl -X GET "https://platform-api2.max.ru/me"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/me

class maxo.bot.methods.GetPinnedMessage[исходный код]#

Получение закреплённого сообщения в групповом чате или канале

Возвращает закреплённое сообщение в групповом чате или канале

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала

Пример запроса:

curl -X GET "https://platform-api2.max.ru/chats/{chatId}/pin"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin

chat_id: Annotated[int, <Marker 'path'>]#: ID чата

class maxo.bot.methods.GetSubscriptions[исходный код]#

Получение всех подписок через Webhook

Если ваш бот получает данные через Webhook, этот метод возвращает список всех подписок

> ! > - Для повышения безопасности **с 25 мая** прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Рекомендуем заранее перейти на HTTPS и сертификаты от доверенных центров, в том числе сертификаты Минцифры. Чтобы обновить подписку на события, используйте [POST /subscriptions](https://dev.max.ru/docs-api/methods/POST/subscriptions) > - Получение обновлений с помощью [Long Polling](https://dev.max.ru/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий - этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions)

#### Пример запроса:

curl -X GET "https://platform-api2.max.ru/subscriptions"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/subscriptions

class maxo.bot.methods.GetUpdates[исходный код]#

Получение обновлений о событиях через Long Polling

> ! Получение обновлений с помощью [Long Polling](https://dev.max.ru/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий - этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions)

Метод GET /updates можно использовать для получения обновлений при разработке и тестировании, если ваш бот не подписан на Webhook. **Для production-окружения используйте только Webhook**

Каждое обновление со списком событий имеет свой порядковый номер. Свойство marker в ответе указывает на следующее ожидаемое обновление. После того, как вы передали marker с указателем на конкретное обновление, все предыдущие считаются прочитанными

Если параметр marker **не передан** или передано значение null, вы получите только последнее обновление

#### Пример запроса:

curl -X GET "https://platform-api2.max.ru/updates"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/updates

limit: Omitted, <Marker 'query'>] = <Omitted>#: Максимальное количество обновлений о событиях, которое может вернуться в ответе на запрос

marker: Omitted, <Marker 'query'>] = <Omitted>#: Чтобы получить последнее обновление событий, передайте null или оставьте поле пустым. Чтобы получить все обновления по событиям с момента предыдущего запроса, передайте значение marker, которое получили в ответ на предыдущий запрос

timeout: Omitted, <Marker 'query'>] = <Omitted>#: Тайм-аут в секундах для долгого опроса

types: Omitted, <Marker 'query'>] = <Omitted>#

//dev.max.ru/docs-api/objects/Update)

Type:: Список типов событий, которые вы хотите получать, например
Type:: message\_created, message\_callback. Полный список возможных событий смотрите в описании [объекта Update](https

make_response(response, response_loader)[исходный код]#

Convert an HTTPResponse into the declared ResponseType.

Результат:

The deserialized response object.

Тип результата:

ResponseType

Параметры:

response (HTTPResponse)
response_loader (ResponseLoader)

class maxo.bot.methods.GetUploadUrl[исходный код]#

Загрузка медиафайлов

Метод возвращает URL для загрузки медиафайла и токен для передачи загруженного файла во вложении к сообщению в чате или канале. После загрузки файла токен передаётся в запросе [POST /messages](https://dev.max.ru/docs-api/methods/POST/messages) или [PUT /messages](https://dev.max.ru/docs-api/methods/PUT/messages) в параметре attachments.payload.token

Для изображений вместо токена и текущего метода вы также можете использовать внешний URL для загрузки по прямой ссылке - подробнее смотрите параметры объекта attachments.payload.url в [POST /messages](https://dev.max.ru/docs-api/methods/POST/messages). Для отправки остальных медиафайлов, потребуется получить токен: загрузить их через /uploads

#### Пример запроса для загрузки медиафайла

curl -X POST "https://platform-api.max.ru/uploads?type={type}"       -H "Authorization: {access_token}"

### Типы медиафайлов и ограничения: Медиафайлы, которые можно загрузить через POST /uploads, должны быть одного из типов type:

image - изображения

**Доступные форматы**: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC **Максимальный размер** одного изображения: до 50 МБ или не более 7680 x 7680 px - должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 x 7600 px нельзя

video - видеофайлы

**Доступные форматы**: MP4, MOV, MKV, WEBM **Максимальный размер** одного видео: до 250 МБ

audio - аудиофайлы

**Доступные форматы**: MP3, WAV, M4A и другие **Максимальный размер** одного аудио: до 256 МБ или длительностью не более 60 мин - должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя

file - другие файлы

**Максимальный размер** одного файла: до 4 ГБ **Доступные форматы**: TXT, DOC, PDF и другие распространённые форматы

> Параметр type=photo больше не поддерживается. Если вы использовали type=photo в ранее созданных интеграциях - замените его на type=image

По URL-ссылке, которая вернётся в ответ на запрос, можно загрузить только один файл. Если вы хотите загрузить ещё файл, отправьте повторно запрос POST /uploads и используйте новую URL-ссылку

### Способы загрузки медиафайлов

В ответ на текущий запрос POST /uploads в поле url вернётся URL для загрузки медиафайла - загрузить можно одним из двух способов:

**Resumable upload** - надёжный способ, если заголовок Content-Type не равен multipart/form-data. Этот способ позволяет загружать файл частями и возобновлять загрузку с последней успешно загруженной части в случае ошибок

**Пример загрузки файла по URL**:

curl -X POST "%UPLOAD_URL%"       -H "Authorization: {access_token}"       -F "data=@example.mp4"

где %UPLOAD\_URL% - это значение поля url, которое вернулось [в ответе](https://dev.max.ru/docs-api/methods/POST/uploads#Результат) на запрос POST /uploads

**Multipart upload** - более простой, но менее надёжный способ. В этом случае используется заголовок Content-Type: multipart/form-data. Файл отправляется целиком одним запросом. Если загрузка прервётся, невозможно её возобновить - придётся начать заново

**Пример использования cURL для загрузки файла**:

curl -i -X POST       -H "Content-Type: multipart/form-data"       -F "data=@movie.pdf" "%UPLOAD_URL%"

### Особенности загрузки разных типов медиафайлов

**Видео и аудио:**

Когда получаем ссылку на загрузку видео или аудио (POST /uploads с type = video или type = audio), вместе с url в ответе приходит token, который нужно использовать в сообщении (когда формируете body с attachments) в [POST /messages](https://dev.max.ru/docs-api/methods/POST/messages)
После загрузки видео или аудио (по url из шага выше) сервер возвращает retval
C этого момента можно использовать token, чтобы прикреплять вложение в сообщение бота

**Изображения и файлы:**

Для``type`` = file: token возвращается в ответе на загрузку файла
Для``type`` = image:
- token возвращается в ответе на загрузку файла
- token содержится в URL, возвращаемом в методе для загрузки файла

Прикрепление медиафайлов#

Процесс прикрепления медиафайлов к сообщениям состоит из трёх шагов:

#### 1. Получение URL для загрузки медиафайлов

Отправьте запрос:

curl -X POST "https://platform-api.max.ru/uploads?type={type}"       -H "Authorization: {access_token}"

где {type} - тип загружаемого файла:

file - произвольный файл
image - изображение
video / audio - видео или аудио

Ответ:

{
    "url": "https://<upload-host>/upload.do?..."
}

> Обратите внимание: домен в url зависит от типа файла. Это ожидаемое поведение: file → https://fu.oneme.ru image → https://iu.oneme.ru video / audio → https://vu.okcdn.ru

#### 2. Загрузка медиафайла

Используйте полученный url без изменений:

curl -X POST       -H "Content-Type: multipart/form-data"       -F "data=@movie.mp4"       "{url}"

Ответ:

{
    "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
}

#### 3. Создание вложения

После успешной загрузки получите JSON-объект в ответе. Используйте этот объект для создания вложения. Структура вложения:

type: тип медиа, например "video"
payload: JSON-объект, который вы получили.

Отправьте сообщение с вложением:

{
    "text": "Message with video",
    "attachments": [
        {
            "type": "video",
            "payload": {
                "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
            }
        }
    ]
}

Обработка медиафайлов#

После успешной загрузки сервер обрабатывает файл. Файлы от нескольких мегабайт обрабатываются дольше

> Для стабильной работы сервисов MAX убедитесь, что максимальное количество запросов в секунду на platform-api.max.ru - 30 rps

Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка:

{
  "code": "attachment.not.ready",
  "message": "Key: errors.process.attachment.file.not.processed"
}

**Как избежать ошибки:**

После загрузки файла сделайте паузу перед отправкой сообщения
Если отправка не удалась, повторите попытку через некоторое время. Увеличивайте интервал с каждой попыткой
Загружайте часто используемые файлы заранее и переиспользуйте токен

Источник: https://dev.max.ru/docs-api/methods/POST/uploads

type: UploadType, <Marker 'query'>]#

"image", "video", "audio", "file"

Type:: Тип загружаемого файла. Возможные значения

class maxo.bot.methods.GetVideoAttachmentDetails[исходный код]#

Получить информацию о видео

Возвращает подробную информацию о прикреплённом видео, URL-адреса воспроизведения и дополнительные метаданные

#### Пример запроса:

curl -X GET "https://platform-api2.max.ru/videos/{video_token}"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-

video_token: Annotated[str, <Marker 'path'>]#: Токен видео-вложения

class maxo.bot.methods.LeaveChat[исходный код]#

Удаление бота из группового чата или канала

Удаляет бота из участников группового чата или канала

Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/chats/{chatId}/members/me"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

class maxo.bot.methods.PinMessage[исходный код]#

Закрепление сообщения в групповом чате или канале

Закрепляет сообщение в групповом чате или канале

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала

Пример запроса:

curl -X PUT "https://platform-api2.max.ru/chats/{chatId}/pin"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "message_id": "{message_id}",
  "notify": true
}'

Источник: https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала, где нужно закрепить сообщение

message_id: Annotated[str, <Marker 'body'>]#: ID сообщения, которое нужно закрепить. Соответствует полю Message.body.mid

notify: Omitted, <Marker 'body'>]#: Если true, участники получат уведомление с системным сообщением о закреплении

class maxo.bot.methods.PostAdmins[исходный код]#

Назначить администратора группового чата или канала

Выдаёт пользователям и ботам, которые являются участникам чата или подписчикам канала, права администратора

Права, которые можно назначить, зависят от того, где (канал или чат) и кому (пользователь или бот) выданы

Список прав передаётся в теле запроса в массиве admins.permissions. Если вы хотите изменить назначенные права, вызовите повторно текущий метод: в теле запроса передайте обновлённый список прав. При повторном вызове логика работы метода соответствует PUT: права администратора будут обновлены полностью в соответствии с переданными в запросе

Пример запроса:

curl -X POST "https://platform-api2.max.ru/chats/{chatId}/members/admins"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "admins": [
    {
      "user_id": "{user_id}",
      "permissions": [
        "read_all_messages",
        "add_remove_members",
        "add_admins",
        "change_chat_info",
        "pin_message",
        "write"
      ],
      "alias": "администраторам"
    }
  ]
}'

Доступные права администратора#

read\_all\_messages - читать все сообщения в канале или групповом чате. Право можно назначить пользователям и ботам. Без этого права не получится управлять сообщениями: закреплять (pin\_message), редактировать и удалять посты в каналах (edit и delete) и групповых чатах (write). Также это право важно при назначении ботов: без него тот не будет получать обновления через [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions). Управление read\_all\_messages в интерфейсе мессенджера доступно только для ботов в групповых чатах

edit - редактировать посты в каналах (для групповых чатов недоступно). Право можно назначить пользователям и ботам, только если уже есть право read\_all\_messages или вместе с ним - иначе вернётся ошибка. Ранее вместо edit в API использовалось edit\_message - в ответе могут возвращаться оба значения, однако при назначении новых прав администраторов используйте edit. Управление edit также дублируется в интерфейсе мессенджера

delete - удалять посты (для групповых чатов недоступно). Право можно назначить пользователям и ботам, только если уже есть право read\_all\_messages или вместе с ним - иначе вернётся ошибка. Ранее вместо delete в API использовалось delete\_message - в ответе могут возвращаться оба значения, однако при назначении новых прав администраторов используйте delete. Управление delete также дублируется в интерфейсе мессенджера

write - редактировать и удалять сообщения в групповых чатах, а также писать посты в каналах. Право можно назначить пользователям и ботам, только если уже есть право read\_all\_messages или вместе с ним - иначе вернётся ошибка. Ранее вместо write в API использовалось post\_edit\_delete\_message - в ответе могут возвращаться оба значения, однако при назначении новых прав администраторам используйте write. Управление write также дублируется в интерфейсе мессенджера

pin\_message - закреплять сообщение. Право можно назначить пользователям и ботам, только если уже есть право read\_all\_messages или вместе с ним - иначе вернётся ошибка

change\_chat\_info - изменять информацию о канале или групповом чате. Право доступно для пользователей и ботов

add\_remove\_members - добавлять и удалять участников группового чата или подписчиков канала. Право доступно для пользователей и в чатах, и в каналах, для ботов - **только в чатах**. Управление add\_remove\_members также дублируется в интерфейсе мессенджера

add\_admins - добавлять и удалять администраторов группового чата или канала. Право доступно для пользователей и ботов. Управление add\_admins дублируется в интерфейсе мессенджера

edit\_link - изменять ссылку на групповой чат (для каналов недоступно). Право есть для пользователей и ботов. Управление edit\_link также дублируется в интерфейсе мессенджера

can\_call - звонить в групповом чате (для каналов недоступно). Право есть у пользователей и ботов - проставляется автоматически при назначении администратором. Управление can\_call в интерфейсе мессенджера не дублируется

view\_stats - право на просмотр статистики каналов (для групповых чатов недоступно). Назначается по умолчанию владельцам каналов. Для других пользователей-администраторов канала и ботов недоступно. Управление view\_stats в интерфейсе мессенджера не дублируется

Источник: https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

admins: ChatAdmin], <Marker 'body'>]#: Список пользователей и ботов, которые получат права администратора группового чата или канала

marker: Omitted, <Marker 'body'>]#: Указатель на следующую страницу данных

class maxo.bot.methods.RemoveMember[исходный код]#

Удаление участников из группового чата или канала

Удаляет участника из группового чата или канала

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала с соответствующим правом add\_remove\_members. Чтобы получить информацию о правах бота, используйте [GET /chats/-chatId-/members/admins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins). Подробнее о правах - в описании объекта [Chat](https://dev.max.ru/docs-api/objects/Chat)

Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/chats/{chatId}/members?user_id={user_id}&block=true"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала

user_id: Annotated[int, <Marker 'query'>]#: ID пользователя, которого нужно удалить из группового чата или канала

block: Omitted, <Marker 'query'>]#: Если передать true, пользователь будет заблокирован в чате. Применяется только для чатов с публичной или приватной ссылкой. Игнорируется в остальных случаях

class maxo.bot.methods.SendAction[исходный код]#

Отправка действия бота в групповой чат

Позволяет отправлять в групповой чат такие действия бота, как например: «набор текста» или «отправка фото»

#### Пример запроса:

curl -X POST "https://platform-api2.max.ru/chats/{chatId}/actions"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "action": "typing_on"
}'

Источник: https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions

chat_id: Annotated[int, <Marker 'path'>]#: ID чата

action: SenderAction, <Marker 'body'>]#

class maxo.bot.methods.SendMessage[исходный код]#

Отправить сообщение

Отправляет сообщение в чат

#### Пример запроса с одной кнопкой-ссылкой

Больше примеров запросов с кнопками - [в разделе «Клавиатура»](https://dev.max.ru/docs-api#Как%20добавить%20кнопки)

curl -X POST "https://platform-api2.max.ru/messages?user_id={user_id}"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "text": "Это сообщение с кнопкой-ссылкой",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "link",
              "text": "Откройте сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
 }'

Источник: https://dev.max.ru/docs-api/methods/POST/messages

chat_id: Omitted, <Marker 'query'>]#

//dev.max.ru/docs-api#Получение%20chat_id)

Type:: Если сообщение отправляется в чат, укажите его ID. Как получить ID - в [разделе «Получение chat_id»](https

disable_link_preview: Omitted, <Marker 'query'>]#: Если true, сервер не будет генерировать превью для ссылок в тексте сообщения

user_id: Omitted, <Marker 'query'>]#: Если вы хотите отправить сообщение пользователю, укажите его ID

attachments: LocationAttachment] | None, <Marker 'body'>]#: Вложения сообщения. Если поле равно null, изменений не произойдет. Если пусто, все вложения будут удалены

link: NewMessageLink | None, <Marker 'body'>]#: Ссылка на сообщение

text: Annotated[str | None, <Marker 'body'>]#: Новый текст сообщения

format: Omitted, <Marker 'body'>]#

//dev.max.ru/docs-api#Форматирование%20текста%20в%20сообщениях)

Type:: Если установлен, текст сообщения будет форматирован данным способом. Для подробной информации загляните в раздел [Форматирование](https

notify: Omitted, <Marker 'body'>]#: Если false, участники чата не будут уведомлены (по умолчанию true)

maxo.bot.methods.SetAdmins#: псевдоним для PostAdmins

class maxo.bot.methods.Subscribe[исходный код]#

Подписка на обновления о новых событиях через Webhook

Метод настраивает доставку событий бота через Webhook - основной механизм получения событий в продуктовых интеграциях. При активной подписке Long Polling не работает

> ! > - Для повышения безопасности **с 25 мая** прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Рекомендуем заранее перейти на HTTPS и сертификаты от доверенных центров, в том числе сертификаты Минцифры. Чтобы обновить подписку на события, используйте текущий метод > - Получение обновлений с помощью [Long Polling](https://dev.max.ru/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий - этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](https://dev.max.ru/docs-api/methods/POST/subscriptions)

Модель доставки событий#

После вызова метода POST /subscriptions события отправляются на указанный Webhook-endpoint в виде HTTPS POST-запросов с объектом [Update](https://dev.max.ru/docs-api/objects/Update)

Как обрабатывается событие:

При наступлении события выполняется вызов Webhook-endpoint
Выполняется TLS-валидация целевого endpoint для безопасной передачи данных
На endpoint отправляется HTTPS-запрос
Если при создании подписки указан secret, проверяется заголовок X-Max-Bot-Api-Secret
При успешной валидации возвращается HTTP 200 OK
Выполняется обработка события
Инициируются вызовы MAX API

Требования к Webhook-endpoint#

### URL и порт

Webhook-endpoint должен быть доступен по HTTPS на порту 443. Ваш сервер должен прослушивать этот порт. Порт в URL не указывается:

https://your-domain.com/webhook

> Поддерживается только порт 443. Если endpoint недоступен, события не доставляются

### Безопасность соединения (TLS)

Перед отправкой событий устанавливается HTTPS-соединение, и Webhook-endpoint проверяется на соответствие следующим требованиям безопасности соединения:

Webhook-endpoint удостоверен TLS-сертификатом, выданным доверенным центром сертификации, или TLS-сертификатом Минцифры. Самоподписанные сертификаты не поддерживаются
Доменное имя в URL Webhook-endpoint совпадает с CN или SAN сертификата
Сервер предоставляет полную цепочку сертификатов

> Если проверка не пройдена, события не доставляются

### Обработка запросов

Webhook-endpoint должен возвращать **HTTP 200** в течение 30 секунд. Любой другой код ответа или превышение тайм-аута считается ошибкой доставки

#### Пример запроса:

curl -X POST "https://platform-api2.max.ru/subscriptions"       -H "Authorization: {access_token}"       -H "Content-Type: application/json"       -d '{
  "url": "https://your-domain.com/webhook",
  "update_types": ["message_created", "bot_started"],
  "secret": "your_secret"
}'

### Политика повторных попыток

Если доставка не удалась, выполняется до 10 повторных попыток с экспоненциально растущим интервалом:

1-я попытка: через 60 секунд
2-я попытка: через 150 секунд (60 × 2,5)
3-я попытка: через 375 секунд (150 × 2,5)
и так далее

> Если в течение 8 часов от Webhook-endpoint не получен успешный ответ, бот автоматически от него отписывается

Безопасность Webhook-запросов#

Параметр secret позволяет убедиться, что Webhook-запросы приходят от MAX, а не от третьей стороны. Это необязательный параметр, но мы настоятельно рекомендуем указывать его. Проверяйте значение заголовка X-Max-Bot-Api-Secret на Webhook-сервере и отклоняйте запросы при несоответствии

Если secret указан при создании подписки, он передаётся в заголовке X-Max-Bot-Api-Secret каждого Webhook-запроса

—

Формат и типы событий#

Webhook-запрос содержит объект [Update](https://dev.max.ru/docs-api/objects/Update)

Полный список типов событий и структура объекта описаны в разделе [Update](https://dev.max.ru/docs-api/objects/Update)

Источник: https://dev.max.ru/docs-api/methods/POST/subscriptions

url: Annotated[str, <Marker 'body'>]#: URL HTTPS-endpoint вашего бота. Должен начинаться с https://

secret: Omitted, <Marker 'body'>]#: Cекрет, который должен быть отправлен в заголовке X-Max-Bot-Api-Secret в каждом запросе Webhook. Разрешены только символы A-Z, a-z, 0-9, и дефис. Заголовок рекомендован, чтобы запрос поступал из установленного веб-узла

update_types: Omitted, <Marker 'body'>]#

//dev.max.ru/docs-api/objects/Update)

Type:: Список типов событий, которые хочет получать ваш бот. Полный список смотрите в описании объекта [Update](https

class maxo.bot.methods.UnpinMessage[исходный код]#

Открепление сообщения в групповом чате или канале

Открепляет сообщение в групповом чате или канале

Бот, чей токен access\_token используется для авторизации, должен быть администратором этого чата или канала

Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/chats/{chatId}/pin"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin

chat_id: Annotated[int, <Marker 'path'>]#: ID группового чата или канала, в котором нужно открепить сообщение или пост

class maxo.bot.methods.Unsubscribe[исходный код]#

Отписка от обновлений о новых событиях через Webhook

Отписывает бота от получения обновлений о новых событиях через Webhook. После вызова этого метода бот перестаёт получать уведомления о новых событиях на Webhook-endpoint, и становится доступна доставка уведомлений через Long Polling

#### Пример запроса:

curl -X DELETE "https://platform-api2.max.ru/subscriptions?url=https://your-domain.com/webhook"       -H "Authorization: {access_token}"

Источник: https://dev.max.ru/docs-api/methods/DELETE/subscriptions

url: Annotated[str, <Marker 'query'>]#: URL, который нужно удалить из подписок на WebHook

class maxo.bot.methods.UploadMedia[исходный код]#

Загрузка медиа.

upload_url: Annotated[str, <Marker 'path'>]#

file: UploadFile, <Marker 'file'>]#

validate_response(response)[исходный код]#

Validate response BODY before deserialization.

Override to handle APIs that return errors in body with 200 status. Called for ALL responses (including 200 OK).

Исключение:: Exception – if response body indicates an error
Параметры:: response (HTTPResponse)
Тип результата:: None