Перейти к содержанию

Package: maxapi.methods

maxapi.methods

add_admin_chat

AddAdminChat(bot, chat_id, admins, marker=None)

Bases: BaseConnection

Класс для добавления списка администраторов в чат через API.

https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins

Attributes:

Name Type Description
bot Bot

Экземпляр бота, через который выполняется запрос.
chat_id int

Идентификатор чата.
admins List[ChatAdmin]

Список администраторов для добавления.
marker int

Маркер для пагинации или дополнительных настроек. По умолчанию None.
Source code in maxapi/methods/add_admin_chat.py 
26
27
28
29
30
31
32
33
34
35
36
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    admins: List[ChatAdmin],
    marker: Optional[int] = None,
):
    self.bot = bot
    self.chat_id = chat_id
    self.admins = admins
    self.marker = marker
fetch() async

Выполняет HTTP POST запрос для добавления администраторов в чат.

Формирует JSON с данными администраторов и отправляет запрос на соответствующий API-эндпоинт.

Returns:

Name Type Description
AddedListAdminChat AddedListAdminChat

Результат операции с информацией об успешности.
Source code in maxapi/methods/add_admin_chat.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
async def fetch(self) -> AddedListAdminChat:
    """
    Выполняет HTTP POST запрос для добавления администраторов в чат.

    Формирует JSON с данными администраторов и отправляет запрос на соответствующий API-эндпоинт.

    Returns:
        AddedListAdminChat: Результат операции с информацией об успешности.
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    json["admins"] = [admin.model_dump() for admin in self.admins]
    json["marker"] = self.marker

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.CHATS.value
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS
        + ApiPath.ADMINS,
        model=AddedListAdminChat,
        params=bot.params,
        json=json,
    )

    return cast(AddedListAdminChat, response)

add_members_chat

AddMembersChat(bot, chat_id, user_ids)

Bases: BaseConnection

Класс для добавления участников в чат через API.

https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members

Attributes:

Name Type Description
bot Bot

Экземпляр бота, через который выполняется запрос.
chat_id int

Идентификатор целевого чата.
user_ids List[int]

Список ID пользователей для добавления в чат.
Source code in maxapi/methods/add_members_chat.py 
24
25
26
27
28
29
30
31
32
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    user_ids: List[int],
):
    self.bot = bot
    self.chat_id = chat_id
    self.user_ids = user_ids
fetch() async

Отправляет POST-запрос на добавление пользователей в чат.

Формирует JSON с ID пользователей и вызывает базовый метод запроса.

Returns:

Name Type Description
AddedMembersChat AddedMembersChat

Результат операции с информацией об успешности добавления.
Source code in maxapi/methods/add_members_chat.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
async def fetch(self) -> AddedMembersChat:
    """
    Отправляет POST-запрос на добавление пользователей в чат.

    Формирует JSON с ID пользователей и вызывает базовый метод запроса.

    Returns:
        AddedMembersChat: Результат операции с информацией об успешности добавления.
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    json["user_ids"] = self.user_ids

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.CHATS.value
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS,
        model=AddedMembersChat,
        params=bot.params,
        json=json,
    )

    return cast(AddedMembersChat, response)

change_info

ChangeInfo(bot, first_name=None, last_name=None, description=None, commands=None, photo=None)

Bases: BaseConnection

Класс для изменения данных текущего бота.

.. deprecated:: 0.9.8 Этот метод отсутствует в официальной swagger-спецификации API MAX. Использование не рекомендуется.

https://dev.max.ru/docs-api/methods/PATCH/me

Parameters:

Name Type Description Default
first_name str

Имя бота (1–64 символа).

 None
last_name str

Второе имя бота (1–64 символа).

 None
description str

Описание бота (1–16000 символов).

 None
commands list[BotCommand]

Список команд (до 32 элементов).

 None
photo PhotoAttachmentRequestPayload

Фото бота.

 None
Note

Метод :meth:fetch возвращает объект :class:User с обновленными данными бота.

Source code in maxapi/methods/change_info.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def __init__(
    self,
    bot: "Bot",
    first_name: Optional[str] = None,
    last_name: Optional[str] = None,
    description: Optional[str] = None,
    commands: Optional[List[BotCommand]] = None,
    photo: Optional[PhotoAttachmentRequestPayload] = None,
):
    warnings.warn(
        "ChangeInfo устарел и отсутствует в официальной swagger-спецификации API MAX. "
        "Использование не рекомендуется.",
        DeprecationWarning,
        stacklevel=2,
    )

    if not any([first_name, last_name, description, commands, photo]):
        raise ValueError(
            "Нужно указать хотя бы один параметр для изменения"
        )

    if first_name is not None and not (1 <= len(first_name) <= 64):
        raise ValueError("first_name должен быть от 1 до 64 символов")

    if last_name is not None and not (1 <= len(last_name) <= 64):
        raise ValueError("last_name должен быть от 1 до 64 символов")

    if description is not None and not (1 <= len(description) <= 16000):
        raise ValueError("description должен быть от 1 до 16000 символов")

    if commands is not None and len(commands) > 32:
        raise ValueError("commands не может содержать больше 32 элементов")

    self.bot = bot
    self.first_name = first_name
    self.last_name = last_name
    self.description = description
    self.commands = commands
    self.photo = photo
fetch() async

Отправляет запрос на изменение информации о боте.

Returns:

Name Type Description
User User

Объект с обновленными данными бота
Source code in maxapi/methods/change_info.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
async def fetch(self) -> User:
    """
    Отправляет запрос на изменение информации о боте.

    Returns:
        User: Объект с обновленными данными бота
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    if self.first_name:
        json["first_name"] = self.first_name
    if self.last_name:
        json["last_name"] = self.last_name
    if self.description:
        json["description"] = self.description
    if self.commands:
        json["commands"] = [
            command.model_dump() for command in self.commands
        ]
    if self.photo:
        json["photo"] = self.photo.model_dump()

    response = await super().request(
        method=HTTPMethod.PATCH,
        path=ApiPath.ME,
        model=User,
        params=bot.params,
        json=json,
    )

    return cast(User, response)

delete_bot_from_chat

DeleteMeFromMessage(bot, chat_id)

Bases: BaseConnection

Класс для удаления бота из участников указанного чата.

https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата, из которого нужно удалить бота.
Source code in maxapi/methods/delete_bot_from_chat.py 
23
24
25
26
27
28
29
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Отправляет DELETE-запрос для удаления бота из чата.

Returns:

Name Type Description
DeletedBotFromChat DeletedBotFromChat

Результат операции удаления.
Source code in maxapi/methods/delete_bot_from_chat.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
async def fetch(self) -> DeletedBotFromChat:
    """
    Отправляет DELETE-запрос для удаления бота из чата.

    Returns:
        DeletedBotFromChat: Результат операции удаления.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.CHATS
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS
        + ApiPath.ME,
        model=DeletedBotFromChat,
        params=bot.params,
    )

    return cast(DeletedBotFromChat, response)

delete_chat

DeleteChat(bot, chat_id)

Bases: BaseConnection

Класс для удаления чата через API.

https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата, который необходимо удалить.
Source code in maxapi/methods/delete_chat.py 
23
24
25
def __init__(self, bot: "Bot", chat_id: int):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Отправляет DELETE-запрос для удаления указанного чата.

Returns:

Name Type Description
DeletedChat DeletedChat

Результат операции удаления чата.
Source code in maxapi/methods/delete_chat.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
async def fetch(self) -> DeletedChat:
    """
    Отправляет DELETE-запрос для удаления указанного чата.

    Returns:
        DeletedChat: Результат операции удаления чата.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.CHATS.value + "/" + str(self.chat_id),
        model=DeletedChat,
        params=bot.params,
    )

    return cast(DeletedChat, response)

delete_message

DeleteMessage(bot, message_id)

Bases: BaseConnection

Класс для удаления сообщения через API.

https://dev.max.ru/docs-api/methods/DELETE/messages

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
message_id str

Идентификатор сообщения, которое нужно удалить.
Source code in maxapi/methods/delete_message.py 
23
24
25
26
27
28
29
30
31
32
def __init__(
    self,
    bot: "Bot",
    message_id: str,
):
    if len(message_id) < 1:
        raise ValueError("message_id не должен быть меньше 1 символа")

    self.bot = bot
    self.message_id = message_id
fetch() async

Выполняет DELETE-запрос для удаления сообщения.

Использует параметр message_id для идентификации сообщения.

Returns:

Name Type Description
DeletedMessage DeletedMessage

Результат операции удаления сообщения.
Source code in maxapi/methods/delete_message.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
async def fetch(self) -> DeletedMessage:
    """
    Выполняет DELETE-запрос для удаления сообщения.

    Использует параметр message_id для идентификации сообщения.

    Returns:
        DeletedMessage: Результат операции удаления сообщения.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    params["message_id"] = self.message_id

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.MESSAGES,
        model=DeletedMessage,
        params=params,
    )

    return cast(DeletedMessage, response)

delete_pin_message

DeletePinMessage(bot, chat_id)

Bases: BaseConnection

Класс для удаления закреплённого сообщения в чате через API.

https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата, из которого нужно удалить закреплённое сообщение.
Source code in maxapi/methods/delete_pin_message.py 
23
24
25
26
27
28
29
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Выполняет DELETE-запрос для удаления закреплённого сообщения.

Returns:

Name Type Description
DeletedPinMessage DeletedPinMessage

Результат операции удаления закреплённого сообщения.
Source code in maxapi/methods/delete_pin_message.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def fetch(self) -> DeletedPinMessage:
    """
    Выполняет DELETE-запрос для удаления закреплённого сообщения.

    Returns:
        DeletedPinMessage: Результат операции удаления закреплённого сообщения.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.CHATS + "/" + str(self.chat_id) + ApiPath.PIN,
        model=DeletedPinMessage,
        params=bot.params,
    )

    return cast(DeletedPinMessage, response)

edit_chat

EditChat(bot, chat_id, icon=None, title=None, pin=None, notify=None)

Bases: BaseConnection

Класс для редактирования информации о чате через API.

https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата для редактирования.
icon PhotoAttachmentRequestPayload

Новый значок (иконка) чата.
title str

Новое название чата.
pin str

Идентификатор закреплённого сообщения.
notify bool

Включение или отключение уведомлений (по умолчанию True).
Source code in maxapi/methods/edit_chat.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    icon: Optional[PhotoAttachmentRequestPayload] = None,
    title: Optional[str] = None,
    pin: Optional[str] = None,
    notify: Optional[bool] = None,
):
    if title is not None and not (1 <= len(title) <= 200):
        raise ValueError(
            "title не должен быть меньше 1 или больше 200 символов"
        )

    self.bot = bot
    self.chat_id = chat_id
    self.icon = icon
    self.title = title
    self.pin = pin
    self.notify = notify
fetch() async

Выполняет PATCH-запрос для обновления параметров чата.

Валидация
  • Проверяется, что в icon атрибуты модели взаимоисключающие (в модели должно быть ровно 2 поля с None).
  • Если условие не выполнено, логируется ошибка и запрос не отправляется.

Returns:

Name Type Description
Chat Chat

Обновлённый объект чата.
Source code in maxapi/methods/edit_chat.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
async def fetch(self) -> Chat:
    """
    Выполняет PATCH-запрос для обновления параметров чата.

    Валидация:
        - Проверяется, что в `icon` атрибуты модели взаимоисключающие (в модели должно быть ровно 2 поля с None).
        - Если условие не выполнено, логируется ошибка и запрос не отправляется.

    Returns:
        Chat: Обновлённый объект чата.
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    if self.icon:
        dump = self.icon.model_dump()
        counter = Counter(dump.values())

        if None not in counter or not counter[None] == 2:
            raise MaxIconParamsException(
                "Все атрибуты модели Icon являются взаимоисключающими | "
                "https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-"
            )

        json["icon"] = dump

    if self.title:
        json["title"] = self.title
    if self.pin:
        json["pin"] = self.pin
    if self.notify:
        json["notify"] = self.notify

    response = await super().request(
        method=HTTPMethod.PATCH,
        path=ApiPath.CHATS.value + "/" + str(self.chat_id),
        model=Chat,
        params=bot.params,
        json=json,
    )

    return cast(Chat, response)

edit_message

EditMessage(bot, message_id, text=None, attachments=None, link=None, notify=None, parse_mode=None, sleep_after_input_media=True)

Bases: BaseConnection

Класс для редактирования существующего сообщения через API.

https://dev.max.ru/docs-api/methods/PUT/messages

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
message_id str

Идентификатор сообщения для редактирования.
text Optional[str]

Новый текст сообщения.
attachments Optional[List[Attachment | InputMedia | InputMediaBuffer]]

Список вложений для сообщения.
link Optional[NewMessageLink]

Связь с другим сообщением (например, ответ или пересылка).
notify Optional[bool]

Отправлять ли уведомление о сообщении. По умолчанию True.
parse_mode Optional[ParseMode]

Формат разметки текста (например, Markdown, HTML).
Source code in maxapi/methods/edit_message.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def __init__(
    self,
    bot: Bot,
    message_id: str,
    text: Optional[str] = None,
    attachments: Optional[
        List[Attachment | InputMedia | InputMediaBuffer | AttachmentUpload]
        | List[Attachments]
    ] = None,
    link: Optional[NewMessageLink] = None,
    notify: Optional[bool] = None,
    parse_mode: Optional[ParseMode] = None,
    sleep_after_input_media: Optional[bool] = True,
):
    if text is not None and not (len(text) < 4000):
        raise ValueError("text должен быть меньше 4000 символов")

    self.bot = bot
    self.message_id = message_id
    self.text = text
    self.attachments = attachments
    self.link = link
    self.notify = notify
    self.parse_mode = parse_mode
    self.sleep_after_input_media = sleep_after_input_media
fetch() async

Выполняет PUT-запрос для обновления сообщения.

Формирует тело запроса на основе переданных параметров и отправляет запрос к API.

Returns:

Name Type Description
EditedMessage Optional[EditedMessage]

Обновлённое сообщение.
Source code in maxapi/methods/edit_message.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
async def fetch(self) -> Optional[EditedMessage]:
    """
    Выполняет PUT-запрос для обновления сообщения.

    Формирует тело запроса на основе переданных параметров и отправляет запрос к API.

    Returns:
        EditedMessage: Обновлённое сообщение.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    json: Dict[str, Any] = {"attachments": []}

    params["message_id"] = self.message_id

    if self.text is not None:
        json["text"] = self.text

    HAS_INPUT_MEDIA = False

    if self.attachments:
        for att in self.attachments:
            if isinstance(att, InputMedia) or isinstance(
                att, InputMediaBuffer
            ):
                HAS_INPUT_MEDIA = True

                input_media = await process_input_media(
                    base_connection=self, bot=bot, att=att
                )
                json["attachments"].append(input_media.model_dump())
            elif isinstance(att, Attachment) and isinstance(
                att.payload, AttachmentUpload
            ):
                json["attachments"].append(att.payload.model_dump())
            else:
                json["attachments"].append(att.model_dump())

    if self.link is not None:
        json["link"] = self.link.model_dump()
    if self.notify is not None:
        json["notify"] = self.notify
    if self.parse_mode is not None:
        json["format"] = self.parse_mode.value

    if HAS_INPUT_MEDIA and self.sleep_after_input_media:
        await asyncio.sleep(bot.after_input_media_delay)

    response = None

    for attempt in range(self.ATTEMPTS_COUNT):
        try:
            response = await super().request(
                method=HTTPMethod.PUT,
                path=ApiPath.MESSAGES,
                model=EditedMessage,
                params=params,
                json=json,
            )
        except MaxApiError as e:
            if (
                isinstance(e.raw, dict)
                and e.raw.get("code") == "attachment.not.ready"
            ):
                logger_bot.info(
                    f"Ошибка при отправке загруженного медиа, попытка {attempt + 1}, жду {self.RETRY_DELAY} секунды"
                )
                await asyncio.sleep(self.RETRY_DELAY)
                continue

        break

    if response is None:
        raise RuntimeError("Не удалось отредактировать сообщение")

    return cast(Optional[EditedMessage], response)

get_chat_by_id

GetChatById(bot, id)

Bases: BaseConnection

Класс для получения информации о чате по его идентификатору.

https://dev.max.ru/docs-api/methods/GET/chats/-chatId-

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
id int

Идентификатор чата.
Source code in maxapi/methods/get_chat_by_id.py 
23
24
25
def __init__(self, bot: "Bot", id: int):
    self.bot = bot
    self.id = id
fetch() async

Выполняет GET-запрос для получения данных чата.

Returns:

Name Type Description
Chat Chat

Объект чата с полной информацией.
Source code in maxapi/methods/get_chat_by_id.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
async def fetch(self) -> Chat:
    """
    Выполняет GET-запрос для получения данных чата.

    Returns:
        Chat: Объект чата с полной информацией.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS.value + "/" + str(self.id),
        model=Chat,
        params=bot.params,
    )

    return cast(Chat, response)

Bases: BaseConnection

Класс для получения информации о чате по ссылке.

https://dev.max.ru/docs-api/methods/GET/chats/-chatLink-

Attributes:

Name Type Description
link list[str]

Список валидных частей ссылки.
PATTERN_LINK str

Регулярное выражение для парсинга ссылки.
Source code in maxapi/methods/get_chat_by_link.py 
26
27
28
29
30
31
def __init__(self, bot: "Bot", link: str):
    self.bot = bot
    self.link = findall(self.PATTERN_LINK, link)

    if not self.link:
        raise ValueError(f"link не соответствует {self.PATTERN_LINK!r}")
fetch() async

Выполняет GET-запрос для получения данных чата по ссылке.

Returns:

Name Type Description
Chat Chat

Объект с информацией о чате.
Source code in maxapi/methods/get_chat_by_link.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
async def fetch(self) -> Chat:
    """
    Выполняет GET-запрос для получения данных чата по ссылке.

    Returns:
        Chat: Объект с информацией о чате.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS.value + "/" + self.link[-1],
        model=Chat,
        params=bot.params,
    )

    return cast(Chat, response)

get_chats

GetChats(bot, count=None, marker=None)

Bases: BaseConnection

Класс для получения списка чатов.

https://dev.max.ru/docs-api/methods/GET/chats

Attributes:

Name Type Description
bot Bot

Инициализированный клиент бота.
count Optional[int]

Максимальное количество чатов, возвращаемых за один запрос.
marker Optional[int]

Маркер для продолжения пагинации.
Source code in maxapi/methods/get_chats.py 
24
25
26
27
28
29
30
31
32
33
34
35
def __init__(
    self,
    bot: "Bot",
    count: Optional[int] = None,
    marker: Optional[int] = None,
):
    if count is not None and not (1 <= count <= 100):
        raise ValueError("count не должен быть меньше 1 или больше 100")

    self.bot = bot
    self.count = count
    self.marker = marker
fetch() async

Выполняет GET-запрос для получения списка чатов.

Returns:

Name Type Description
Chats Chats

Объект с данными по списку чатов.
Source code in maxapi/methods/get_chats.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
async def fetch(self) -> Chats:
    """
    Выполняет GET-запрос для получения списка чатов.

    Returns:
        Chats: Объект с данными по списку чатов.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    if self.count:
        params["count"] = self.count

    if self.marker:
        params["marker"] = self.marker

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS,
        model=Chats,
        params=params,
    )

    return cast(Chats, response)

get_list_admin_chat

GetListAdminChat(bot, chat_id)

Bases: BaseConnection

Класс для получения списка администраторов чата через API.

https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
chat_id int

Идентификатор чата.
Source code in maxapi/methods/get_list_admin_chat.py 
23
24
25
def __init__(self, bot: "Bot", chat_id: int):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Выполняет GET-запрос для получения списка администраторов указанного чата.

Returns:

Name Type Description
GettedListAdminChat GettedListAdminChat

Объект с информацией о администраторах чата.
Source code in maxapi/methods/get_list_admin_chat.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def fetch(self) -> GettedListAdminChat:
    """
    Выполняет GET-запрос для получения списка администраторов указанного чата.

    Returns:
        GettedListAdminChat: Объект с информацией о администраторах чата.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS.value
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS
        + ApiPath.ADMINS,
        model=GettedListAdminChat,
        params=bot.params,
    )

    return cast(GettedListAdminChat, response)

get_me

GetMe(bot)

Bases: BaseConnection

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

https://dev.max.ru/docs-api/methods/GET/me

Parameters:

Name Type Description Default
bot Bot

Экземпляр бота для выполнения запроса.

 required
Source code in maxapi/methods/get_me.py 
23
24
def __init__(self, bot: "Bot"):
    self.bot = bot
fetch() async

Выполняет GET-запрос для получения данных о боте.

Returns:

Name Type Description
User User

Объект пользователя с полной информацией.
Source code in maxapi/methods/get_me.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
async def fetch(self) -> User:
    """
    Выполняет GET-запрос для получения данных о боте.

    Returns:
        User: Объект пользователя с полной информацией.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.ME,
        model=User,
        params=bot.params,
    )

    return cast(User, response)

get_me_from_chat

GetMeFromChat(bot, chat_id)

Bases: BaseConnection

Класс для получения информации о текущем боте в конкретном чате.

https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
chat_id int

Идентификатор чата.
Source code in maxapi/methods/get_me_from_chat.py 
23
24
25
def __init__(self, bot: "Bot", chat_id: int):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Выполняет GET-запрос для получения информации о боте в указанном чате.

Returns:

Name Type Description
ChatMember ChatMember

Информация о боте как участнике чата.
Source code in maxapi/methods/get_me_from_chat.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def fetch(self) -> ChatMember:
    """
    Выполняет GET-запрос для получения информации о боте в указанном чате.

    Returns:
        ChatMember: Информация о боте как участнике чата.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS
        + ApiPath.ME,
        model=ChatMember,
        params=bot.params,
    )

    return cast(ChatMember, response)

get_members_chat

GetMembersChat(bot, chat_id, user_ids=None, marker=None, count=None)

Bases: BaseConnection

Класс для получения списка участников чата через API.

https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата.
user_ids Optional[List[str]]

Список ID пользователей для фильтрации. По умолчанию None.
marker Optional[int]

Маркер для пагинации (начальная позиция). По умолчанию None.
count Optional[int]

Максимальное количество участников для получения. По умолчанию None.
Source code in maxapi/methods/get_members_chat.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    user_ids: Optional[List[int]] = None,
    marker: Optional[int] = None,
    count: Optional[int] = None,
):
    if count is not None and not (1 <= count <= 100):
        raise ValueError("count не должен быть меньше 1 или больше 100")

    self.bot = bot
    self.chat_id = chat_id
    self.user_ids = user_ids
    self.marker = marker
    self.count = count
fetch() async

Выполняет GET-запрос для получения участников чата с опциональной фильтрацией.

Формирует параметры запроса с учётом фильтров и передаёт их базовому методу.

Returns:

Name Type Description
GettedMembersChat GettedMembersChat

Объект с данными по участникам чата.
Source code in maxapi/methods/get_members_chat.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
async def fetch(self) -> GettedMembersChat:
    """
    Выполняет GET-запрос для получения участников чата с опциональной фильтрацией.

    Формирует параметры запроса с учётом фильтров и передаёт их базовому методу.

    Returns:
        GettedMembersChat: Объект с данными по участникам чата.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    if self.user_ids:
        params["user_ids"] = ",".join(
            [str(user_id) for user_id in self.user_ids]
        )

    if self.marker:
        params["marker"] = self.marker
    if self.count:
        params["count"] = self.count

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS.value
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS,
        model=GettedMembersChat,
        params=params,
    )

    return cast(GettedMembersChat, response)

get_message

GetMessage(bot, message_id)

Bases: BaseConnection

Класс для получения сообщения.

https://dev.max.ru/docs-api/methods/GET/messages/-messageId-

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
message_id Optional[str]

ID сообщения (mid), чтобы получить одно сообщение в чате.
Source code in maxapi/methods/get_message.py 
23
24
25
26
27
28
29
def __init__(
    self,
    bot: "Bot",
    message_id: str,
):
    self.bot = bot
    self.message_id = message_id
fetch() async

Выполняет GET-запрос для получения сообщения.

Returns:

Name Type Description
Message Message

Объект с полученным сообщением.
Source code in maxapi/methods/get_message.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def fetch(self) -> Message:
    """
    Выполняет GET-запрос для получения сообщения.

    Returns:
        Message: Объект с полученным сообщением.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.MESSAGES + "/" + self.message_id,
        model=Message,
        params=bot.params,
    )

    return cast(Message, response)

get_messages

GetMessages(bot, chat_id=None, message_ids=None, from_time=None, to_time=None, count=50)

Bases: BaseConnection

Класс для получения сообщений из чата через API.

https://dev.max.ru/docs-api/methods/GET/messages

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
chat_id int

Идентификатор чата.
message_ids List[str] | None

Фильтр по идентификаторам сообщений.
from_time datetime | int | None

Начальная временная метка.
to_time datetime | int | None

Конечная временная метка.
count int

Максимальное число сообщений.
Source code in maxapi/methods/get_messages.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def __init__(
    self,
    bot: "Bot",
    chat_id: Optional[int] = None,
    message_ids: Optional[List[str]] = None,
    from_time: Optional[Union[datetime, int]] = None,
    to_time: Optional[Union[datetime, int]] = None,
    count: int = 50,
):
    if count is not None and not (1 <= count <= 100):
        raise ValueError("count не должен быть меньше 1 или больше 100")

    self.bot = bot
    self.chat_id = chat_id
    self.message_ids = message_ids
    self.from_time = from_time
    self.to_time = to_time
    self.count = count
fetch() async

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

Преобразует datetime в UNIX timestamp при необходимости.

Returns:

Name Type Description
Messages Messages

Объект с полученными сообщениями.
Source code in maxapi/methods/get_messages.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
async def fetch(self) -> Messages:
    """
    Выполняет GET-запрос для получения сообщений с учётом параметров фильтрации.

    Преобразует datetime в UNIX timestamp при необходимости.

    Returns:
        Messages: Объект с полученными сообщениями.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    if self.chat_id:
        params["chat_id"] = self.chat_id

    if self.message_ids:
        params["message_ids"] = ",".join(self.message_ids)

    if self.from_time:
        if isinstance(self.from_time, datetime):
            params["from"] = to_ms(self.from_time)
        else:
            params["from"] = self.from_time

    if self.to_time:
        if isinstance(self.to_time, datetime):
            params["to"] = to_ms(self.to_time)
        else:
            params["to"] = self.to_time

    params["count"] = self.count

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.MESSAGES,
        model=Messages,
        params=params,
    )

    return cast(Messages, response)

get_pinned_message

GetPinnedMessage(bot, chat_id)

Bases: BaseConnection

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

https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата.
Source code in maxapi/methods/get_pinned_message.py 
23
24
25
26
27
28
29
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
):
    self.bot = bot
    self.chat_id = chat_id
fetch() async

Выполняет GET-запрос для получения закреплённого сообщения.

Returns:

Name Type Description
GettedPin GettedPin

Объект с информацией о закреплённом сообщении.
Source code in maxapi/methods/get_pinned_message.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def fetch(self) -> GettedPin:
    """
    Выполняет GET-запрос для получения закреплённого сообщения.

    Returns:
        GettedPin: Объект с информацией о закреплённом сообщении.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.CHATS + "/" + str(self.chat_id) + ApiPath.PIN,
        model=GettedPin,
        params=bot.params,
    )

    return cast(GettedPin, response)

get_subscriptions

GetSubscriptions(bot)

Bases: BaseConnection

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

https://dev.max.ru/docs-api/methods/GET/subscriptions

Attributes:

Name Type Description
bot Bot

Экземпляр бота
Source code in maxapi/methods/get_subscriptions.py 
22
23
24
25
26
def __init__(
    self,
    bot: "Bot",
):
    self.bot = bot
fetch() async

Отправляет запрос на получение списка всех подписок.

Returns:

Name Type Description
GettedSubscriptions GettedSubscriptions

Объект со списком подписок
Source code in maxapi/methods/get_subscriptions.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
async def fetch(self) -> GettedSubscriptions:
    """
    Отправляет запрос на получение списка всех подписок.

    Returns:
        GettedSubscriptions: Объект со списком подписок
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.SUBSCRIPTIONS,
        model=GettedSubscriptions,
        params=bot.params,
    )

    return cast(GettedSubscriptions, response)

get_updates

GetUpdates(bot, limit, timeout, marker=None, types=None)

Bases: BaseConnection

Класс для получения обновлений (updates) от API.

https://dev.max.ru/docs-api/methods/GET/updates

Запрашивает новые события для бота через long polling с возможностью фильтрации по типам и маркеру последнего обновления.

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
limit int

Лимит на количество получаемых обновлений.
timeout int

Таймаут ожидания.
marker Optional[int]

ID последнего обработанного события.
types Optional[Sequence[UpdateType]]

Список типов событий для фильтрации.
Source code in maxapi/methods/get_updates.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def __init__(
    self,
    bot: Bot,
    limit: Optional[int],
    timeout: Optional[int],
    marker: Optional[int] = None,
    types: Optional[Sequence[UpdateType]] = None,
):
    if limit is not None and not (1 <= limit <= 1000):
        raise ValueError("limit не должен быть меньше 1 и больше 1000")

    if timeout is not None and not (0 <= timeout <= 90):
        raise ValueError("timeout не должен быть меньше 0 и больше 90")

    self.bot = bot
    self.limit = limit
    self.timeout = timeout
    self.marker = marker
    self.types = types
fetch() async

Выполняет GET-запрос к API для получения новых событий.

Returns:

Name Type Description
Dict Dict[str, Any]

Сырой JSON-ответ от API с новыми событиями.
Source code in maxapi/methods/get_updates.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
async def fetch(self) -> Dict[str, Any]:
    """
    Выполняет GET-запрос к API для получения новых событий.

    Returns:
        Dict: Сырой JSON-ответ от API с новыми событиями.
    """
    bot = self._ensure_bot()

    params = bot.params.copy()

    if self.limit:
        params["limit"] = self.limit
    if self.marker is not None:
        params["marker"] = self.marker
    if self.timeout is not None:
        params["timeout"] = self.timeout
    if self.types:
        params["types"] = ",".join(self.types)

    event_json = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.UPDATES,
        model=None,
        params=params,
        is_return_raw=True,
    )

    return cast(Dict[str, Any], event_json)

get_upload_url

GetUploadURL(bot, type)

Bases: BaseConnection

Класс для получения URL загрузки файла определённого типа.

https://dev.max.ru/docs-api/methods/POST/uploads

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
type UploadType

Тип загружаемого файла (например, image, video и т.д.).
Source code in maxapi/methods/get_upload_url.py 
24
25
26
def __init__(self, bot: "Bot", type: UploadType):
    self.bot = bot
    self.type = type
fetch() async

Выполняет POST-запрос для получения URL загрузки файла.

Возвращает объект с данными URL.

Returns:

Name Type Description
GettedUploadUrl GettedUploadUrl

Результат с URL для загрузки.
Source code in maxapi/methods/get_upload_url.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
async def fetch(self) -> GettedUploadUrl:
    """
    Выполняет POST-запрос для получения URL загрузки файла.

    Возвращает объект с данными URL.

    Returns:
        GettedUploadUrl: Результат с URL для загрузки.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    params["type"] = self.type.value

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.UPLOADS,
        model=GettedUploadUrl,
        params=params,
    )

    return cast(GettedUploadUrl, response)

get_video

GetVideo(bot, video_token)

Bases: BaseConnection

Класс для получения информации о видео по его токену.

https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
video_token str

Токен видео для запроса.
Source code in maxapi/methods/get_video.py 
23
24
25
def __init__(self, bot: "Bot", video_token: str):
    self.bot = bot
    self.video_token = video_token
fetch() async

Выполняет GET-запрос для получения данных видео по токену.

Returns:

Name Type Description
Video Video

Объект с информацией о видео.
Source code in maxapi/methods/get_video.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
async def fetch(self) -> Video:
    """
    Выполняет GET-запрос для получения данных видео по токену.

    Returns:
        Video: Объект с информацией о видео.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.GET,
        path=ApiPath.VIDEOS.value + "/" + self.video_token,
        model=Video,
        params=bot.params,
    )

    return cast(Video, response)

pin_message

PinMessage(bot, chat_id, message_id, notify=None)

Bases: BaseConnection

Класс для закрепления сообщения в чате.

https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата, в котором закрепляется сообщение.
message_id str

Идентификатор сообщения для закрепления.
notify bool

Отправлять ли уведомление о закреплении (по умолчанию True).
Source code in maxapi/methods/pin_message.py 
25
26
27
28
29
30
31
32
33
34
35
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    message_id: str,
    notify: Optional[bool] = None,
):
    self.bot = bot
    self.chat_id = chat_id
    self.message_id = message_id
    self.notify = notify
fetch() async

Выполняет PUT-запрос для закрепления сообщения в чате.

Формирует тело запроса с ID сообщения и флагом уведомления.

Returns:

Name Type Description
PinnedMessage PinnedMessage

Объект с информацией о закреплённом сообщении.
Source code in maxapi/methods/pin_message.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
async def fetch(self) -> PinnedMessage:
    """
    Выполняет PUT-запрос для закрепления сообщения в чате.

    Формирует тело запроса с ID сообщения и флагом уведомления.

    Returns:
        PinnedMessage: Объект с информацией о закреплённом сообщении.
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    json["message_id"] = self.message_id
    json["notify"] = self.notify

    response = await super().request(
        method=HTTPMethod.PUT,
        path=ApiPath.CHATS + "/" + str(self.chat_id) + ApiPath.PIN,
        model=PinnedMessage,
        params=bot.params,
        json=json,
    )

    return cast(PinnedMessage, response)

remove_admin

RemoveAdmin(bot, chat_id, user_id)

Bases: BaseConnection

Класс для отмены прав администратора в чате.

https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
chat_id int

Идентификатор чата.
user_id int

Идентификатор пользователя.
Source code in maxapi/methods/remove_admin.py 
24
25
26
27
def __init__(self, bot: "Bot", chat_id: int, user_id: int):
    self.bot = bot
    self.chat_id = chat_id
    self.user_id = user_id
fetch() async

Выполняет DELETE-запрос для отмены прав администратора в чате.

Returns:

Name Type Description
RemovedAdmin RemovedAdmin

Объект с результатом отмены прав администратора.
Source code in maxapi/methods/remove_admin.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
async def fetch(self) -> RemovedAdmin:
    """
    Выполняет DELETE-запрос для отмены прав администратора в чате.

    Returns:
        RemovedAdmin: Объект с результатом отмены прав администратора.
    """

    bot = self._ensure_bot()

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.CHATS
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS
        + ApiPath.ADMINS
        + "/"
        + str(self.user_id),
        model=RemovedAdmin,
        params=bot.params,
    )

    return cast(RemovedAdmin, response)

remove_member_chat

RemoveMemberChat(bot, chat_id, user_id, block=False)

Bases: BaseConnection

Класс для удаления участника из чата с опцией блокировки.

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id int

Идентификатор чата.
user_id int

Идентификатор пользователя, которого необходимо удалить.
block bool

Блокировать пользователя после удаления. По умолчанию False.
Source code in maxapi/methods/remove_member_chat.py 
23
24
25
26
27
28
29
30
31
32
33
def __init__(
    self,
    bot: "Bot",
    chat_id: int,
    user_id: int,
    block: bool = False,
):
    self.bot = bot
    self.chat_id = chat_id
    self.user_id = user_id
    self.block = block
fetch() async

Выполняет DELETE-запрос для удаления пользователя из чата.

Параметр block определяет, будет ли пользователь заблокирован после удаления.

Returns:

Name Type Description
RemovedMemberChat RemovedMemberChat

Результат удаления участника.
Source code in maxapi/methods/remove_member_chat.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
async def fetch(self) -> RemovedMemberChat:
    """
    Выполняет DELETE-запрос для удаления пользователя из чата.

    Параметр `block` определяет, будет ли пользователь заблокирован после удаления.

    Returns:
        RemovedMemberChat: Результат удаления участника.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    params["chat_id"] = self.chat_id
    params["user_id"] = self.user_id
    params["block"] = str(self.block).lower()

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.CHATS.value
        + "/"
        + str(self.chat_id)
        + ApiPath.MEMBERS,
        model=RemovedMemberChat,
        params=params,
    )

    return cast(RemovedMemberChat, response)

send_action

SendAction(bot, chat_id=None, action=SenderAction.TYPING_ON)

Bases: BaseConnection

Класс для отправки действия пользователя (например, индикатора печати) в чат.

https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id Optional[int]

Идентификатор чата. Если None, действие не отправляется.
action Optional[SenderAction]

Тип действия. По умолчанию SenderAction.TYPING_ON.
Source code in maxapi/methods/send_action.py 
25
26
27
28
29
30
31
32
33
def __init__(
    self,
    bot: "Bot",
    chat_id: Optional[int] = None,
    action: SenderAction = SenderAction.TYPING_ON,
):
    self.bot = bot
    self.chat_id = chat_id
    self.action = action
fetch() async

Выполняет POST-запрос для отправки действия в указанный чат.

Returns:

Name Type Description
SendedAction SendedAction

Результат выполнения запроса.
Source code in maxapi/methods/send_action.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
async def fetch(self) -> SendedAction:
    """
    Выполняет POST-запрос для отправки действия в указанный чат.

    Returns:
        SendedAction: Результат выполнения запроса.
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    json["action"] = self.action.value

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.CHATS + "/" + str(self.chat_id) + ApiPath.ACTIONS,
        model=SendedAction,
        params=bot.params,
        json=json,
    )

    return cast(SendedAction, response)

send_callback

SendCallback(bot, callback_id, message=None, notification=None)

Bases: BaseConnection

Класс для отправки callback-ответа с опциональным сообщением и уведомлением.

https://dev.max.ru/docs-api/methods/POST/answers

Attributes:

Name Type Description
bot Bot

Экземпляр бота.
callback_id str

Идентификатор callback.
message Optional[MessageForCallback]

Сообщение для отправки.
notification Optional[str]

Текст уведомления.
Source code in maxapi/methods/send_callback.py 
28
29
30
31
32
33
34
35
36
37
38
def __init__(
    self,
    bot: "Bot",
    callback_id: str,
    message: Optional[MessageForCallback] = None,
    notification: Optional[str] = None,
):
    self.bot = bot
    self.callback_id = callback_id
    self.message = message
    self.notification = notification
fetch() async

Выполняет POST-запрос для отправки callback-ответа.

Возвращает результат отправки.

Returns:

Name Type Description
SendedCallback SendedCallback

Объект с результатом отправки callback.
Source code in maxapi/methods/send_callback.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
async def fetch(self) -> SendedCallback:
    """
    Выполняет POST-запрос для отправки callback-ответа.

    Возвращает результат отправки.

    Returns:
        SendedCallback: Объект с результатом отправки callback.
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    params["callback_id"] = self.callback_id

    json: Dict[str, Any] = {}

    if self.message:
        json["message"] = self.message.model_dump()
    if self.notification:
        json["notification"] = self.notification

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.ANSWERS,
        model=SendedCallback,
        params=params,
        json=json,
    )

    return cast(SendedCallback, response)

send_message

SendMessage(bot, chat_id=None, user_id=None, text=None, attachments=None, link=None, notify=None, parse_mode=None, disable_link_preview=None, sleep_after_input_media=True)

Bases: BaseConnection

Класс для отправки сообщения в чат или пользователю с поддержкой вложений и форматирования.

https://dev.max.ru/docs-api/methods/POST/messages

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
chat_id Optional[int]

Идентификатор чата, куда отправлять сообщение.
user_id Optional[int]

Идентификатор пользователя, если нужно отправить личное сообщение.
text Optional[str]

Текст сообщения.
attachments Optional[List[Attachment | InputMedia | InputMediaBuffer]]

Список вложений к сообщению.
link Optional[NewMessageLink]

Связь с другим сообщением (например, ответ или пересылка).
notify Optional[bool]

Отправлять ли уведомление о сообщении. По умолчанию True.
parse_mode Optional[ParseMode]

Режим разбора текста (например, Markdown, HTML).
disable_link_preview Optional[bool]

Флаг генерации превью.
Source code in maxapi/methods/send_message.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def __init__(
    self,
    bot: "Bot",
    chat_id: Optional[int] = None,
    user_id: Optional[int] = None,
    text: Optional[str] = None,
    attachments: Optional[
        List[Attachment | InputMedia | InputMediaBuffer | AttachmentUpload]
        | List[Attachments]
    ] = None,
    link: Optional[NewMessageLink] = None,
    notify: Optional[bool] = None,
    parse_mode: Optional[ParseMode] = None,
    disable_link_preview: Optional[bool] = None,
    sleep_after_input_media: Optional[bool] = True,
):
    if text is not None and not (len(text) < 4000):
        raise ValueError("text должен быть меньше 4000 символов")

    self.bot = bot
    self.chat_id = chat_id
    self.user_id = user_id
    self.text = text
    self.attachments = attachments
    self.link = link
    self.notify = notify
    self.parse_mode = parse_mode
    self.disable_link_preview = disable_link_preview
    self.sleep_after_input_media = sleep_after_input_media
fetch() async

Отправляет сообщение с вложениями (если есть), с обработкой задержки готовности вложений.

Возвращает результат отправки или ошибку.

Возвращаемое значение

SendedMessage или Error

Source code in maxapi/methods/send_message.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
async def fetch(self) -> Optional[SendedMessage]:
    """
    Отправляет сообщение с вложениями (если есть), с обработкой задержки готовности вложений.

    Возвращает результат отправки или ошибку.

    Возвращаемое значение:
        SendedMessage или Error
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    json: Dict[str, Any] = {"attachments": []}

    if self.chat_id:
        params["chat_id"] = self.chat_id
    elif self.user_id:
        params["user_id"] = self.user_id

    json["text"] = self.text

    HAS_INPUT_MEDIA = False

    if self.attachments:
        for att in self.attachments:
            if isinstance(att, (InputMedia, InputMediaBuffer)):
                HAS_INPUT_MEDIA = True

                input_media = await process_input_media(
                    base_connection=self, bot=bot, att=att
                )
                json["attachments"].append(input_media.model_dump())
            elif isinstance(att, Attachment) and isinstance(
                att.payload, AttachmentUpload
            ):
                json["attachments"].append(att.payload.model_dump())
            else:
                json["attachments"].append(att.model_dump())

    if self.link is not None:
        json["link"] = self.link.model_dump()

    if self.notify:
        json["notify"] = self.notify

    if self.disable_link_preview:
        json["disable_link_preview"] = self.disable_link_preview

    if self.parse_mode is not None:
        json["format"] = self.parse_mode.value

    if HAS_INPUT_MEDIA and self.sleep_after_input_media:
        await asyncio.sleep(bot.after_input_media_delay)

    response = None
    for attempt in range(self.ATTEMPTS_COUNT):
        try:
            response = await super().request(
                method=HTTPMethod.POST,
                path=ApiPath.MESSAGES,
                model=SendedMessage,
                params=params,
                json=json,
            )
        except MaxApiError as e:
            if (
                isinstance(e.raw, dict)
                and e.raw.get("code") == "attachment.not.ready"
            ):
                logger_bot.info(
                    f"Ошибка при отправке загруженного медиа, попытка {attempt + 1}, жду {self.RETRY_DELAY} секунды"
                )
                await asyncio.sleep(self.RETRY_DELAY)
                continue
            else:
                raise e

        break

    if response is None:
        raise RuntimeError("Не удалось отправить сообщение")

    return cast(Optional[SendedMessage], response)

subscribe_webhook

SubscribeWebhook(bot, url, update_types=None, secret=None)

Bases: BaseConnection

Подписывает бота на получение обновлений через WebHook. После вызова этого метода бот будет получать уведомления о новых событиях в чатах на указанный URL. Ваш сервер должен прослушивать один из следующих портов: 80, 8080, 443, 8443, 16384-32383.

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
url str

URL HTTP(S)-эндпойнта вашего бота. Должен начинаться с http(s)://
update_types Optional[List[str]]

Список типов обновлений, которые ваш бот хочет получать. Для полного списка типов см. объект
secret Optional[str]

От 5 до 256 символов. Cекрет, который должен быть отправлен в заголовке X-Max-Bot-Api-Secret в каждом запросе Webhook. Разрешены только символы A-Z, a-z, 0-9, и дефис. Заголовок рекомендован, чтобы запрос поступал из установленного веб-узла
Source code in maxapi/methods/subscribe_webhook.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(
    self,
    bot: "Bot",
    url: str,
    update_types: Optional[List[UpdateType]] = None,
    secret: Optional[str] = None,
):
    if secret is not None and not (5 <= len(secret) <= 256):
        raise ValueError(
            "secret не должен быть меньше 5 или больше 256 символов"
        )

    self.bot = bot
    self.url = url
    self.update_types = update_types
    self.secret = secret
fetch() async

Отправляет запрос на подписку бота на получение обновлений через WebHook

Returns:

Name Type Description
Subscribed Subscribed

Объект с информацией об операции
Source code in maxapi/methods/subscribe_webhook.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
async def fetch(self) -> Subscribed:
    """
    Отправляет запрос на подписку бота на получение обновлений через WebHook

    Returns:
        Subscribed: Объект с информацией об операции
    """

    bot = self._ensure_bot()

    json: Dict[str, Any] = {}

    json["url"] = self.url

    if self.update_types:
        json["update_types"] = self.update_types

    if self.secret:
        json["secret"] = self.secret

    response = await super().request(
        method=HTTPMethod.POST,
        path=ApiPath.SUBSCRIPTIONS,
        model=Subscribed,
        params=bot.params,
        json=json,
    )

    return cast(Subscribed, response)

types

added_admin_chat

AddedListAdminChat

Bases: BaseModel

Ответ API при добавлении списка администраторов в чат.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

added_members_chat

AddedMembersChat

Bases: BaseModel

Ответ API при добавлении списка пользователей в чат.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

deleted_bot_from_chat

DeletedBotFromChat

Bases: BaseModel

Ответ API при удалении бота из чата.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

deleted_chat

DeletedChat

Bases: BaseModel

Ответ API при удалении чата (?).

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

deleted_message

DeletedMessage

Bases: BaseModel

Ответ API при удалении сообщения.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

deleted_pin_message

DeletedPinMessage

Bases: BaseModel

Ответ API при удалении закрепленного в чате сообщения.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

edited_message

EditedMessage

Bases: BaseModel

Ответ API при изменении сообщения.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

getted_list_admin_chat

GettedListAdminChat

Bases: BaseModel

Ответ API с полученным списком администраторов чата.

Attributes:

Name Type Description
members List[ChatMember]

Список участников с правами администратора.
marker Optional[int]

Маркер для постраничной навигации (если есть).

getted_members_chat

GettedMembersChat

Bases: BaseModel

Ответ API с полученным списком участников чата.

Attributes:

Name Type Description
members List[ChatMember]

Список участников с правами администратора.
marker Optional[int]

Маркер для постраничной навигации (если есть).

getted_pineed_message

GettedPin

Bases: BaseModel

Ответ API с информацией о закреплённом сообщении.

Attributes:

Name Type Description
message Optional[Message]

Закреплённое сообщение, если оно есть.

getted_subscriptions

GettedSubscriptions

Bases: BaseModel

Ответ API с отправленным сообщением.

Attributes:

Name Type Description
message Message

Объект отправленного сообщения.

pinned_message

PinnedMessage

Bases: BaseModel

Ответ API при добавлении списка администраторов в чат.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

removed_admin

RemovedAdmin

Bases: BaseModel

Ответ API при отмене прав администратора у пользователя в чате

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

removed_member_chat

RemovedMemberChat

Bases: BaseModel

Ответ API при удалении участника из чата.

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или описание ошибки.

sended_action

SendedAction

Bases: BaseModel

Ответ API после выполнения действия.

Attributes:

Name Type Description
success bool

Статус успешности выполнения операции.
message Optional[str]

Дополнительное сообщение или описание ошибки.

sended_callback

SendedCallback

Bases: BaseModel

Ответ API после выполнения callback-действия.

Attributes:

Name Type Description
success bool

Статус успешности выполнения callback.
message Optional[str]

Дополнительное сообщение или описание ошибки.
bot Optional[Bot]

Внутреннее поле для хранения ссылки на экземпляр бота (не сериализуется).

sended_message

SendedMessage

Bases: BaseModel

Ответ API с отправленным сообщением.

Attributes:

Name Type Description
message Message

Объект отправленного сообщения.

subscribed

Subscribed

Bases: BaseModel

Результат подписки на обновления на Webhook

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

unsubscribed

Unsubscribed

Bases: BaseModel

Результат отписки от обновлений на Webhook

Attributes:

Name Type Description
success bool

Статус успешности операции.
message Optional[str]

Дополнительное сообщение или ошибка.

unsubscribe_webhook

UnsubscribeWebhook(bot, url)

Bases: BaseConnection

Отписывает бота от получения обновлений через WebHook. После вызова этого метода бот перестает получать уведомления о новых событиях, и доступна доставка уведомлений через API с длительным опросом.

https://dev.max.ru/docs-api/methods/DELETE/subscriptions

Attributes:

Name Type Description
bot Bot

Экземпляр бота для выполнения запроса.
url str

URL, который нужно удалить из подписок на WebHook
Source code in maxapi/methods/unsubscribe_webhook.py 
25
26
27
28
29
30
31
def __init__(
    self,
    bot: "Bot",
    url: str,
):
    self.bot = bot
    self.url = url
fetch() async

Отправляет запрос на подписку бота на получение обновлений через WebHook

Returns:

Name Type Description
Unsubscribed Unsubscribed

Объект с информацией об операции
Source code in maxapi/methods/unsubscribe_webhook.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
async def fetch(self) -> Unsubscribed:
    """
    Отправляет запрос на подписку бота на получение обновлений через WebHook

    Returns:
        Unsubscribed: Объект с информацией об операции
    """

    bot = self._ensure_bot()

    params = bot.params.copy()

    params["url"] = self.url

    response = await super().request(
        method=HTTPMethod.DELETE,
        path=ApiPath.SUBSCRIPTIONS,
        model=Unsubscribed,
        params=params,
    )

    return cast(Unsubscribed, response)