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

Message

Сообщение с текстом, вложением и клавиатурой. Отслеживает ID, источник и состояние отправки.

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

message = app.message(ctx, text="Ready")

Для edit/update/replace/close сообщение уже отправлено. send() используют на новом объекте.

init

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

def __init__(app: App, context: Event | int | None = None, *, source: str | None = None, text: str | Text = '', media: Media | None = None, keyboard: Keyboard | list[list[Button]] | None = None) -> None: ...

Аргументы

app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
context: Event | int | None, по умолчанию None. Текущее событие либо числовой чат. None допустимо, если чат будет передан позже.
source: str | None, по умолчанию None. Источник telegram или bot; None наследует контекст у конструкторов сообщений.
text: str | Text, по умолчанию ''. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
media: Media | None, по умолчанию None. Только Media либо None. Для bytes или ID сначала вызови app.media().
keyboard: Keyboard | list[list[Button]] | None, по умолчанию None. Клавиатура либо список её строк. None создаёт пустую клавиатуру.

Результат

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

Права

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

Ошибки

ValueError('Unknown message source'): условие проверяется до продолжения операции.
TypeError('Use app.media for an attachment'): условие проверяется до продолжения операции.

Пример

# Обычный способ получения объекта:
message = app.message(ctx, text="Ready")

id

Возвращает ID отправленного сообщения либо None. Для приватного ответа используй также ephemeral_id.

def id() -> int | None: ...

Свойство: читается без скобок и без await.

Аргументы

Нет.

Результат

int | None. Возвращает ID отправленного сообщения либо None. Для приватного ответа используй также ephemeral_id.

Права

Ошибки

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

Пример

value = message.id

ephemeral_id

Возвращает идентификатор приватного сообщения бота либо None.

def ephemeral_id() -> int | None: ...

Свойство: читается без скобок и без await.

Аргументы

Нет.

Результат

int | None. Возвращает идентификатор приватного сообщения бота либо None.

Права

Ошибки

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

Пример

value = message.ephemeral_id

receiver

Возвращает получателя приватного сообщения из результата либо sender_id контекста; до отправки возвращает None.

def receiver() -> int | None: ...

Свойство: читается без скобок и без await.

Аргументы

Нет.

Результат

int | None. Возвращает получателя приватного сообщения из результата либо sender_id контекста; до отправки возвращает None.

Права

Ошибки

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

Пример

value = message.receiver

set_text

Меняет текст локально без отправки.

def set_text(text: str | Text) -> Self: ...

Аргументы

text: str | Text, обязательный. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).

Результат

Self. Тот же объект после успешной операции. Меняет текст локально без отправки.

Права

Ошибки

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

Пример

result = message.set_text("Ready")

attach

Локально устанавливает Media или создаёт вложение из файла. Для замены уже отправленного вложения нужен edit().

def attach(file: Media | str | bytes, kind: str = 'document', **data: JSON) -> Self: ...

Аргументы

file: Media | str | bytes, обязательный. Media либо ID файла Cluster, либо bytes с filename.
kind: str, по умолчанию 'document'. Тип photo, video, animation, audio, document, voice или video_note. gif является алиасом animation.
data: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

Self. Тот же объект после успешной операции. Локально устанавливает Media или создаёт вложение из файла. Для замены уже отправленного вложения нужен edit().

Права

Ошибки

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

Пример

result = message.attach("file-id", parse_mode="HTML")

send

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

async def send(chat: int | None = None, **options: JSON) -> Self: ...

Аргументы

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

Результат

Self. Тот же объект после успешной операции. Отправляет новое сообщение один раз через выбранный источник. Клавиатура автоматически создаёт зарегистрированную форму.

Права

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

Ошибки

ValueError('The message has already been sent'): условие проверяется до продолжения операции.
ValueError('A message chat is required'): условие проверяется до продолжения операции.
ValueError('Private messages require the bot transport'): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await message.send(parse_mode="HTML")

edit

Меняет активное сообщение или форму. Для добавления кнопок к обычному сообщению и удаления вложения используй replace().

async def edit(text: str | Text | None = None, **options: JSON) -> Self: ...

Аргументы

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

Результат

Self. Тот же объект после успешной операции. Меняет активное сообщение или форму. Для добавления кнопок к обычному сообщению и удаления вложения используй replace().

Права

Ошибки

ValueError('The message is not active'): условие проверяется до продолжения операции.
ValueError('Use replace to add registered buttons to a plain message'): условие проверяется до продолжения операции.
ValueError('Use replace to remove a message attachment'): условие проверяется до продолжения операции.
ValueError('This attachment cannot be replaced'): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await message.edit(parse_mode="HTML")

update

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

async def update() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Отправляет текущее локальное состояние как редактирование.

Права

Ошибки

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

Пример

result = await message.update()

replace

Сначала отправляет новое сообщение с текущим содержимым, затем удаляет прежнее. При ошибке отправки сохраняет прежнюю ссылку; ошибка удаления может оставить оба сообщения.

async def replace(**options: JSON) -> Self: ...

Аргументы

options: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

Self. Тот же объект после успешной операции. Сначала отправляет новое сообщение с текущим содержимым, затем удаляет прежнее. При ошибке отправки сохраняет прежнюю ссылку; ошибка удаления может оставить оба сообщения.

Права

Ошибки

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

Пример

result = await message.replace(parse_mode="HTML")

close

Удаляет активное сообщение или форму и отмечает объект закрытым.

async def close() -> bool: ...

Аргументы

Нет.

Результат

bool. Удаляет активное сообщение или форму и отмечает объект закрытым.

Права

Ошибки

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

Пример

result = await message.close()