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-api.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-api.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-api.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-api.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-api.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-api.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, изменений не произойдет. Если пусто, все вложения будут удалены

Ссылка на сообщение

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-api.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-api.max.ru/chats/{chatId}"       -H "Authorization: {access_token}"

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

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

ID запрашиваемого группового чата или канала

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

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

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

Публичная ссылка на канал

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

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

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

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

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-api.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-api.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-api.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 - метод возвращает массив сообщений из указанного чата. Сообщения возвращаются в обратном порядке: последние сообщения будут первыми в массиве

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

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

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

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

curl -X GET "https://platform-api.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'>]

ID чата, чтобы получить сообщения из определённого чата. Обязательный параметр, если не указан message\_ids

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-api.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-api.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-api.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-api.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 для последующей загрузки файла

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

#### Ограничения при загрузке файлов

  • Максимальный размер файла: 4 ГБ

  • Можно загружать только один файл за раз

#### Пример получения URL для загрузки

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

#### Файлы по полученному URL можно загрузить двумя способами

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

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

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

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

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

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

где %UPLOAD\_URL% - это URL из результата метода в примере cURL запроса

**Особенности загрузки видео и аудио:**

  • Когда получаем ссылку на загрузку видео или аудио (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=video"       -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-api.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-api.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-api.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, участники получат уведомление с системным сообщением о закреплении

maxo.bot.methods.PostAdmins

псевдоним для SetAdmins

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-api.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-api.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-api.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'>]

Если сообщение отправляется в чат, укажите его ID

Если false, сервер не будет генерировать превью для ссылок в тексте сообщения

user_id: Omitted, <Marker 'query'>]

Если вы хотите отправить сообщение пользователю, укажите его ID

attachments: LocationAttachment] | None, <Marker 'body'>]

Вложения сообщения. Если поле равно null, изменений не произойдет. Если пусто, все вложения будут удалены

Ссылка на сообщение

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.SetAdmins[исходный код]

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

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

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

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

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

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

curl -X POST "https://platform-api.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.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)

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

  1. При наступлении события выполняется вызов Webhook-endpoint

  2. Выполняется TLS-валидация целевого endpoint для безопасной передачи данных

  3. На endpoint отправляется HTTPS-запрос

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

  5. При успешной валидации возвращается HTTP 200 OK

  6. Выполняется обработка события

  7. Инициируются вызовы MAX API

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

### URL и порт

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

https://your-domain.com/webhook

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

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

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

  • Webhook-endpoint удостоверен TLS-сертификатом, выданным доверенным центром сертификации. Самоподписанные сертификаты не поддерживаются

  • Доменное имя в URL Webhook-endpoint совпадает с CN или SAN сертификата

  • Сервер предоставляет полную цепочку сертификатов

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

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

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

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

curl -X POST "https://platform-api.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-api.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

> ! > - Для повышения безопасности **с 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 DELETE "https://platform-api.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