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

app.client

Методы подключённого Telegram-аккаунта. Ответы проходят сериализацию ядра; это не живые объекты Telethon.

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

me = await app.client.get_me()

init

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

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

Аргументы

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

Результат

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

Права

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

Ошибки

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

Пример

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

native

Отправляет подготовленный TL-запрос. Требует полного доступа Telegram; сессия и её файл модулю не передаются.

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

Аргументы

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

Результат

JSON. Отправляет подготовленный TL-запрос. Требует полного доступа Telegram; сессия и её файл модулю не передаются.

Права

Нужны telegram.full.

Ошибки

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

Пример

result = await app.client.native("help.GetConfig", {})

request

Вызывает выделенный метод Telegram или raw. Проверка прав зависит от выбранного метода.

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. Вызывает выделенный метод Telegram или raw. Проверка прав зависит от выбранного метода.

Права

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

Ошибки

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

Пример

me = await app.client.request("get_me")

get_me

Получает сведения о подключённом аккаунте.

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

Аргументы

Нет.

Результат

TelegramUser. Получает сведения о подключённом аккаунте.

Права

Нужны telegram.read.

Ошибки

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

Пример

result = await app.client.get_me()

get_messages

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

async def get_messages(chat: int | None, limit: int = 20) -> list[TelegramMessage]: ...

Аргументы

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

Результат

list[TelegramMessage]. Получает последние сообщения указанного чата с ограничением количества.

Права

Нужны telegram.read.

Ошибки

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

Пример

messages = await app.client.get_messages(ctx.chat_id, limit=20)

download_media

Сохраняет вложение сообщения в файл Cluster. Резервирует maximum байт и освобождает неиспользованное место после загрузки.

async def download_media(chat: int | None, message: int, maximum: float | None = 10485760) -> FileInfo: ...

Аргументы

chat: int | None, обязательный. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
message: int, обязательный. ID сообщения в выбранном чате: целое от 1 до 2**31 - 1.
maximum: float | None, по умолчанию 10485760. Граница min/max поля, конечное число от -1e12 до 1e12; None снимает границу.

Результат

FileInfo. Сохраняет вложение сообщения в файл Cluster. Резервирует maximum байт и освобождает неиспользованное место после загрузки.

Права

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

Ошибки

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

Пример

result = await app.client.download_media(ctx.chat_id, ctx.id)

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. Отправляет текст в чат от подключённого аккаунта.

Права

Нужны telegram.send.

Ошибки

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

Пример

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

edit_message

Меняет текст доступного для редактирования сообщения.

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

Аргументы

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

Результат

TelegramMessage. Меняет текст доступного для редактирования сообщения.

Права

Нужны telegram.send.

Ошибки

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

Пример

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

delete_messages

Удаляет от 1 до 100 сообщений в канале или супергруппе. Для обычного чата выделенный метод запрещён, поскольку messages.deleteMessages не содержит peer; для собственного сообщения используй delete_own_message().

async def delete_messages(chat: int | None, messages: list[int]) -> bool: ...

Аргументы

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

Результат

bool. True после успешного удаления.

Права

Нужны telegram.send.

Ошибки

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

Пример

await app.client.delete_messages(ctx.chat_id, [ctx.id])

delete_own_message

Удаляет сообщение, отправленное подключённым Telegram-аккаунтом. Проверяется отправитель, а не то, каким модулем создано сообщение; подходит и для команды самого владельца.

async def delete_own_message(chat: int | None, message: int) -> bool: ...

Аргументы

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

Результат

bool. True после успешного удаления.

Права

Нужны telegram.send.

Ошибки

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

Пример

await app.client.delete_own_message(ctx.chat_id, ctx.id)

send_album

Отправляет несколько готовых файлов Cluster одним альбомом.

async def send_album(chat: int | None, files: list[str], captions: list[str] | None = None, **data: JSON) -> list[TelegramMessage]: ...

Аргументы

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

Результат

list[TelegramMessage]. Отправляет несколько готовых файлов Cluster одним альбомом.

Права

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

Ошибки

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

Пример

result = await app.client.send_album(ctx.chat_id, ["first-file", "second-file"], parse_mode="HTML")

update_profile

Меняет разрешённые поля профиля Telegram: first_name, last_name и about.

async def update_profile(**data: JSON) -> JSON: ...

Аргументы

data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: first_name, last_name, about. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

JSON. Меняет разрешённые поля профиля Telegram: first_name, last_name и about.

Права

Нужны telegram.profile.

Ошибки

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

Пример

result = await app.client.update_profile(about="Cluster")

update_username

Меняет username подключённого аккаунта; доступность имени проверяет Telegram.

async def update_username(username: str) -> JSON: ...

Аргументы

username: str, обязательный. Новое имя пользователя Telegram без @.

Результат

JSON. Меняет username подключённого аккаунта; доступность имени проверяет Telegram.

Права

Нужны telegram.profile.

Ошибки

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

Пример

result = await app.client.update_username("example_name")

update_photo

Устанавливает фотографию профиля из готового файла Cluster.

async def update_photo(file: str) -> JSON: ...

Аргументы

file: str, обязательный. ID готового файла Cluster. Путь сервера или bytes здесь не принимаются.

Результат

JSON. Устанавливает фотографию профиля из готового файла Cluster.

Права

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

Ошибки

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

Пример

result = await app.client.update_photo("file-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. Путь сервера или bytes здесь не принимаются.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

TelegramMessage. Отправляет файл Cluster в чат. Дополнительные параметры выбирают подпись и способ отображения.

Права

Ошибки

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

Пример

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

edit_file

Заменяет вложение сообщения и подпись.

async def edit_file(chat: int | None, message: int, file: str, caption: str = '', **data: JSON) -> TelegramMessage: ...

Аргументы

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

Результат

TelegramMessage. Заменяет вложение сообщения и подпись.

Права

Ошибки

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

Пример

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

invoke

Вызывает именованный высокоуровневый метод или TL-запрос через полный доступ. Поддерживаемые короткие методы дополнительно проверяют свой обычный доступ.

async def invoke(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. Вызывает именованный высокоуровневый метод или TL-запрос через полный доступ. Поддерживаемые короткие методы дополнительно проверяют свой обычный доступ.

Права

Нужны telegram.full.

Ошибки

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

Пример

me = await app.client.invoke("get_me")