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

Event

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

Все методы SDK · Типы и ошибки

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

message = app.message(ctx)

__init__

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

def __init__(app: App, data: EventEnvelope) -> None: ...

Аргументы

• app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
• data: EventEnvelope, обязательный. Служебная оболочка router/poll. В обработчик готовый Event передаёт ядро.

Результат

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

Права

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

Ошибки

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

Пример

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

reply

Отвечает на сообщение через источник события. В приватном событии бота сохраняет адресата.

async def reply(text: str | Text, **kwargs: JSON) -> TelegramMessage: ...

Аргументы

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

Результат

TelegramMessage. Отвечает на сообщение через источник события. В приватном событии бота сохраняет адресата.

Права

Нужны telegram.send либо bot.send по source.

Ошибки

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

Пример

result = await ctx.reply("Ready", parse_mode="HTML")

edit

Редактирует исходное сообщение. Для callback обновляет сообщение формы; для Telegram и бота использует соответствующий метод.

async def edit(text: str | Text, **kwargs: JSON) -> JSON: ...

Аргументы

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

Результат

JSON. Редактирует исходное сообщение. Для callback обновляет сообщение формы; для Telegram и бота использует соответствующий метод.

Права

Нужны telegram.send либо bot.send; для callback нужен действующий контекст формы.

Ошибки

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

Пример

result = await ctx.edit("Ready", parse_mode="HTML")

answer

Отвечает на нажатие кнопки всплывающим уведомлением или alert и отмечает событие как отвеченное.

async def answer(text: str | Text = '', alert: bool = False) -> JSON: ...

Аргументы

• text: str | Text, по умолчанию ''. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
• alert: bool, по умолчанию False. Логический переключатель указанного действия.

Результат

JSON. Отвечает на нажатие кнопки всплывающим уведомлением или alert и отмечает событие как отвеченное.

Права

Контекст действующего callback; произвольный callback ID передать нельзя.

Ошибки

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

Пример

result = await ctx.answer()