Cluster · разработчикам

app.bot

Методы личного бота юзербота. Для общих вызовов используй bot.api или invoke(); токен остаётся в ядре.

Получение объекта

me = await app.bot.get_me()

init

Создаёт Bot. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(app: App) -> None: ...

Аргументы

app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.

Результат

None. Создаёт Bot. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
me = await app.bot.get_me()

native

Вызывает Bot API из словаря параметров. Извлекает chat_id через pop(), поэтому переданный словарь изменяется.

async def native(method: str, data: JSON) -> JSON: ...

Аргументы

method: str, обязательный. Точное имя метода Telegram: для request выделенное имя, для native имя из соответствующей схемы, для invoke имя общего API.
data: JSON, обязательный. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.

Результат

JSON. Вызывает Bot API из словаря параметров. Извлекает chat_id через pop(), поэтому переданный словарь изменяется.

Права

Нужны bot.full.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

me = await app.bot.native("getMe", {})

request

Вызывает Bot API по имени. Для выделенных методов действуют частные права, для остальных нужен bot.full.

async def request(method: str, chat: int | None = None, **data: JSON) -> JSON: ...

Аргументы

method: str, обязательный. Точное имя метода Telegram: для request выделенное имя, для native имя из соответствующей схемы, для invoke имя общего API.
chat: int | None, по умолчанию None. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

JSON. Вызывает Bot API по имени. Для выделенных методов действуют частные права, для остальных нужен bot.full.

Права

Зависят от method: частное право выделенного метода либо bot.full для общего API.

Ошибки

resources.error(result['error']): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

me = await app.bot.request("getMe")

get_me

Получает публичные сведения о личном боте.

async def get_me() -> BotUser: ...

Аргументы

Нет.

Результат

BotUser. Получает публичные сведения о личном боте.

Права

Нужны bot.read.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.get_me()

invoke

Вызывает доступный модулю метод Bot API с полным доступом. Управление получением обновлений и служебными настройками бота недоступно.

async def invoke(method: str, **data: JSON) -> JSON: ...

Аргументы

method: str, обязательный. Точное имя метода Telegram: для request выделенное имя, для native имя из соответствующей схемы, для invoke имя общего API.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

JSON. Вызывает доступный модулю метод Bot API с полным доступом. Управление получением обновлений и служебными настройками бота недоступно.

Права

Нужны bot.full.

Ошибки

resources.error(result['error']): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

me = await app.bot.invoke("getMe")

send_message

Отправляет текст от личного бота в выбранный чат.

async def send_message(chat: int | None, text: str, **data: JSON) -> TelegramMessage: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
text: str, обязательный. Текст сообщения. Для конструктора Text передай str(text) и соответствующий parse_mode.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

TelegramMessage. Отправляет текст от личного бота в выбранный чат.

Права

Нужны bot.send.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.send_message(ctx.chat_id, "Ready", parse_mode="HTML")

edit_message

Меняет текст сообщения личного бота.

async def edit_message(chat: int | None, message_id: int, text: str, **data: JSON) -> TelegramMessage | bool: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
message_id: int, обязательный. ID сообщения внутри выбранного чата.
text: str, обязательный. Текст сообщения. Для конструктора Text передай str(text) и соответствующий parse_mode.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

TelegramMessage | bool. Меняет текст сообщения личного бота.

Права

Нужны bot.send.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.edit_message(ctx.chat_id, ctx.id, "Ready", parse_mode="HTML")

edit_caption

Меняет подпись вложения в сообщении личного бота.

async def edit_caption(chat: int | None, message_id: int, caption: str, **data: JSON) -> TelegramMessage | bool: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
message_id: int, обязательный. ID сообщения внутри выбранного чата.
caption: str, обязательный. Подпись медиа; формат определяется parse_mode или сущностями.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

TelegramMessage | bool. Меняет подпись вложения в сообщении личного бота.

Права

Нужны bot.send.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.edit_caption(ctx.chat_id, ctx.id, "Ready", parse_mode="HTML")

delete_message

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

async def delete_message(chat: int | None, message_id: int) -> bool: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
message_id: int, обязательный. ID сообщения внутри выбранного чата.

Результат

bool. Удаляет сообщение личного бота, если Telegram разрешает удаление.

Права

Нужны bot.send.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.delete_message(ctx.chat_id, ctx.id)

send_file

Отправляет готовый файл Cluster через выбранный метод личного бота.

async def send_file(chat: int | None, file: str, **data: JSON) -> TelegramMessage: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
file: str, обязательный. ID готового файла Cluster. Байты и пути на сервере здесь не принимаются.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

TelegramMessage. Отправляет готовый файл Cluster через выбранный метод личного бота.

Права

Нужны bot.send + files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

resources.error(result['error']): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await app.bot.send_file(ctx.chat_id, "file-id", parse_mode="HTML")