📡 Гайд по событиям системы

Полное описание всех полей, доступных в событиях после парсинга через EventParser.

📋 Содержание

Типы событий — описание всех типов событий системы
Общие поля — поля, доступные во всех событиях
Поля scheduled сценариев — дополнительные поля для scheduled сценариев
Поля сообщений — дополнительные поля для событий типа message
Поля callback — дополнительные поля для событий типа callback
События платежей — поля для событий платежей через Telegram
События участников — поля для событий входа/выхода участников
Inline-клавиатура — структура inline-клавиатуры в сообщениях
Поля вложений — структура вложений в сообщениях
Примеры использования — как использовать поля в сценариях

Типы событий

Система поддерживает следующие типы событий:

Тип события	Описание	Когда возникает
`message`	Обычное сообщение от пользователя	Пользователь отправляет текстовое сообщение или медиа
`callback`	Нажатие на инлайн-кнопку	Пользователь нажимает на кнопку в сообщении
`member_joined`	Вступление участника в группу	Пользователь вступает в группу или супергруппу
`member_left`	Выход участника из группы	Пользователь покидает группу или супергруппу
`pre_checkout_query`	Запрос на подтверждение оплаты	Пользователь нажимает "Оплатить" в инвойсе, но до обработки платежа
`payment_successful`	Успешная оплата	Платеж через инвойс успешно обработан

Общие поля

Эти поля доступны во всех типах событий. Все эти поля приходят изначально при получении события и содержат исходные данные, которые сформировали событие.

ℹ️ Важно: Эти атрибуты — это исходная информация о событии, переданная из источника (например, Telegram). Они используются системой как значения по умолчанию для действий (например, chat_id и message_id берутся из события, если не указаны явно в параметрах действия).

⚠️ Ограничение для scheduled сценариев: В сценариях, запущенных по расписанию (с полем schedule), большинство общих полей недоступны, так как событие не связано с пользователем или чатом. Доступны только системные поля (bot_id, tenant_id) и специальные поля scheduled сценариев (см. раздел Поля scheduled сценариев).

Поле	Тип	Описание	Пример
`event_source`	string	Источник события	`"telegram"`
`event_type`	string	Тип события	`"message"`, `"callback"`, `"member_joined"`, `"member_left"`, `"pre_checkout_query"`, `"payment_successful"`
`user_id`	integer	ID пользователя, который инициировал событие	`123456789`
`chat_id`	integer	ID чата, из которого пришло событие	`-1001234567890`
`chat_type`	string	Тип чата	`"private"`, `"group"`, `"supergroup"`, `"channel"`
`is_group`	boolean	Является ли чат группой или супергруппой	`true` для `group` и `supergroup`, `false` для `private` и `channel`
`message_id`	integer	ID исходного сообщения, которое привело к событию. Для событий типа `message` — это ID текстового сообщения, для `callback` — ID сообщения с кнопкой, на которую был нажат callback	`1234`
`event_date`	string	Дата события (ISO)	`"2024-01-15T10:30:45+03:00"`
`username`	string	Username пользователя	`"john_doe"` (может быть null)
`first_name`	string	Имя пользователя	`"John"`
`last_name`	string	Фамилия пользователя	`"Doe"` (может быть null)
`language_code`	string	Код языка пользователя	`"ru"`, `"en"` (может быть null)
`is_bot`	boolean	Является ли пользователь ботом	`false`
`is_premium`	boolean	Премиум пользователь	`true`
`chat_title`	string	Название чата	`"Моя группа"` (может быть null)
`chat_username`	string	Username чата	`"my_group"` (может быть null)
`user_state`	string	Состояние пользователя	`"feedback"`, `"onboarding"` (может быть null)
`user_state_expired_at`	string	Время истечения состояния (ISO)	`"3000-01-01T00:00:00+00:00"` (может быть null)

🔧 Служебные поля

Система автоматически добавляет следующие служебные поля для корректной работы действий:

Поле	Тип	Описание	Назначение
`bot_id`	integer	ID бота	Обязательно для отправки сообщений и выполнения действий
`tenant_id`	integer	ID тенанта	Обязательно для загрузки сценариев и определения контекста
`polling_start_time`	string	Время запуска пуллинга бота (ISO)	Служебное для фильтрации событий по времени
`last_error`	string	Текст последней ошибки действия	Служебное для передачи ошибок между шагами сценария
`last_result`	string	Результат последнего выполненного действия	Служебное для отладки и проверки результата действия между шагами сценария
`scenario_chain`	array	Цепочка сценариев в порядке их вызова	Служебное для отладки и логирования, содержит массив названий сценариев в порядке выполнения

⚠️ Важно: Следующие поля добавляются автоматически:

Обязательные поля (bot_id, tenant_id) — требуются для выполнения действий (отправка сообщений, работа с БД, управление состояниями)
- ℹ️ В scheduled сценариях: Поля bot_id и tenant_id доступны автоматически и не требуют явного указания в параметрах действий. Они автоматически подставляются из контекста синтетического события
Служебные поля (polling_start_time, last_error, last_result, scenario_chain) — используются системой для внутренней логики:
- polling_start_time — фильтрация событий по времени
- last_error — сохранение текста ошибки действия для последующих шагов сценария
- last_result — сохранение результата выполнения действия (например, success, error, timeout, not_found) для отладки и проверки в последующих шагах сценария
- scenario_chain — массив названий сценариев в порядке их вызова, автоматически обновляется при запуске каждого сценария и при переходах (jump_to_scenario). Текущий сценарий доступен как scenario_chain[-1], предыдущий — как scenario_chain[-2] (если есть). Используется для отладки и логирования потока выполнения
Поля состояний (user_state, user_state_expired_at) — могут быть null, если состояние не установлено или истекло

Поля scheduled сценариев

Дополнительные поля для сценариев, запущенных по расписанию:

Поле	Тип	Описание	Пример
`scheduled_at`	string	Время запуска scheduled сценария (ISO)	`"2024-01-15T10:30:00+03:00"`
`scheduled_scenario_id`	integer	ID scheduled сценария в базе данных	`123`
`scheduled_scenario_name`	string	Название scheduled сценария	`"daily_report"`

ℹ️ Важно: Эти поля доступны только в scheduled сценариях (с полем schedule в конфигурации). В обычных сценариях, запущенных по событиям, эти поля отсутствуют.

⚠️ Ограничение: В scheduled сценариях большинство общих полей (например, user_id, chat_id, event_text, message_id и др.) недоступны, так как событие не связано с пользователем или чатом. Для отправки сообщений используйте параметр target_chat_id в действиях.

Поля сообщений

Дополнительные поля для событий типа message:

Поле	Тип	Описание	Пример
`event_text`	string	Текст сообщения	`"Привет! Как дела?"`
`media_group_id`	string	ID медиагруппы	`"1234567890123456789"` (может быть null)
`event_attachment`	array	Вложения	`[{"type": "photo", "file_id": "AgACAgIAAxkBAAIB..."}]`
`inline_keyboard`	array	Inline-клавиатура сообщения	`[[{"Кнопка 1": "action_1"}]]` (может быть null)
`is_reply`	boolean	Ответ на сообщение	`true`
`is_forward`	boolean	Пересланное сообщение	`false`

Поля ответных сообщений

Поле	Тип	Описание	Пример
`reply_message_id`	integer	ID ответного сообщения	`1233`
`reply_message_text`	string	Текст ответного сообщения	`"Как дела?"`
`reply_user_id`	integer	ID автора ответного сообщения	`123456789`
`reply_username`	string	Username автора ответного сообщения	`"jane_doe"`
`reply_first_name`	string	Имя автора ответного сообщения	`"Jane"`
`reply_last_name`	string	Фамилия автора ответного сообщения	`"Smith"`
`reply_date`	string	Дата ответного сообщения (ISO)	`"2024-01-15T10:25:30+03:00"`
`reply_attachment`	array	Вложения ответного сообщения	`[{"type": "document", "file_id": "BQACAgIAAxkBAAIB..."}]`

Поля пересланных сообщений

Поле	Тип	Описание	Пример
`forward_message_id`	integer	ID пересланного сообщения	`5678`
`forward_from_user_id`	integer	ID автора пересланного сообщения	`987654321`
`forward_from_user_username`	string	Username автора пересланного сообщения	`"original_author"`
`forward_from_user_first_name`	string	Имя автора пересланного сообщения	`"Original"`
`forward_from_user_last_name`	string	Фамилия автора пересланного сообщения	`"Author"`
`forward_from_chat_id`	integer	ID чата пересланного сообщения	`-1009876543210`
`forward_from_chat_title`	string	Название чата пересланного сообщения	`"Исходная группа"`
`forward_from_chat_type`	string	Тип чата пересланного сообщения	`"supergroup"`
`forward_date`	string	Дата пересланного сообщения (ISO)	`"2024-01-15T09:15:20+03:00"`

Поля callback

Дополнительные поля для событий типа callback:

Поле	Тип	Описание	Пример
`callback_id`	string	ID callback	`"1234567890123456789"`
`callback_data`	string	Данные callback	`"menu_main"`
`callback_message_text`	string	Текст исходного сообщения, к которому привязан callback (текст или подпись)	`"Выберите действие:"` (может быть null)
`inline_keyboard`	array	Inline-клавиатура сообщения, к которому привязан callback	`[[{"Кнопка 1": "action_1"}]]` (может быть null)

События платежей

События, связанные с оплатой через Telegram инвойсы.

Поля pre_checkout_query

Событие pre_checkout_query возникает, когда пользователь нажимает кнопку "Оплатить" в инвойсе, но до обработки платежа. Это запрос на подтверждение оплаты от Telegram к боту.

ℹ️ Важно: На это событие нужно ответить через действие answer_pre_checkout_query для подтверждения или отклонения платежа. Если не ответить в течение 10 секунд, платеж будет автоматически отклонен.

Поле	Тип	Описание	Пример
`pre_checkout_query_id`	string	ID запроса на подтверждение оплаты	`"1234567890123456789"`
`invoice_payload`	string	ID инвойса (payload, который был передан при создании)	`"123"`
`currency`	string	Валюта платежа	`"XTR"` (Telegram Stars)
`total_amount`	integer	Общая сумма платежа в минимальных единицах валюты	`100` (100 звезд)

Дополнительно: Событие содержит общие поля (см. раздел Общие поля).

Поля payment_successful

Событие payment_successful возникает после успешной обработки платежа через инвойс.

Поле	Тип	Описание	Пример
`invoice_payload`	string	ID инвойса (payload, который был передан при создании)	`"123"`
`currency`	string	Валюта платежа	`"XTR"` (Telegram Stars)
`total_amount`	integer	Общая сумма платежа в минимальных единицах валюты	`100` (100 звезд)
`telegram_payment_charge_id`	string	ID платежа в Telegram	`"1234567890"`

Дополнительно: Событие содержит общие поля (см. раздел Общие поля).

События участников

События типа member_joined и member_left используют стандартные общие поля (см. раздел Общие поля).

ℹ️ Важно:

Событие member_joined возникает при вступлении пользователя в группу (переход из статуса left, kicked или первого вступления)
Событие member_left возникает при выходе пользователя из группы (переход в статус left или kicked)
Эти события доступны только для групп и супергрупп

Поля вложений

Структура объектов в массиве event_attachment и reply_attachment:

Типы вложений

Тип	Описание	Примечание
`photo`	Фотография	Самое большое разрешение из доступных
`document`	Документ	Любой файл (PDF, DOC, ZIP и т.д.)
`video`	Видео	Видеофайл
`audio`	Аудио	Аудиофайл
`voice`	Голосовое сообщение	Голосовое сообщение
`sticker`	Стикер	Telegram стикер
`animation`	Анимация	GIF анимация
`video_note`	Видео заметка	Круглое видео сообщение

Структура объекта вложения

Поле	Тип	Описание	Пример
`type`	string	Тип вложения	`"photo"`
`file_id`	string	ID файла	`"AgACAgIAAxkBAAIB..."`

Пример структуры вложения

json

{
  "type": "photo",
  "file_id": "AgACAgIAAxkBAAIB..."
}

Примеры использования

Как использовать поля событий в сценариях:

Простые условия

yaml

# Проверка типа события
trigger:
  - event_type: "message"

# Проверка текста сообщения
trigger:
  - event_type: "message"
    event_text: "/start"

# Проверка callback данных
trigger:
  - event_type: "callback"
    callback_data: "menu_main"

# Проверка состояния пользователя
trigger:
  - event_type: "message"
    user_state: "feedback"

Сложные условия

yaml

# Проверка пользователя и чата
trigger:
  - event_type: "message"
    condition: |
      $user_id == 123456789 and
      $chat_type == "private" and
      $event_text ~ "привет"

# Проверка вложений
trigger:
  - event_type: "message"
    condition: |
      $event_attachment[0].type == "photo"

# Проверка ответного сообщения
trigger:
  - event_type: "message"
    condition: |
      $is_reply == true and
      $reply_user_id == 987654321

Использование в параметрах действий

yaml

# Отправка сообщения в тот же чат
- action: "send_message"
  params:
    bot_id: "{bot_id}"
    chat_id: "{chat_id}"
    text: "Привет, {first_name}!"

# Ответ на сообщение
- action: "send_message"
  params:
    bot_id: "{bot_id}"
    chat_id: "{chat_id}"
    text: "Получил ваше сообщение!"
    message_reply: "{message_id}"

# Управление состоянием пользователя
- action: "set_user_state"
  params:
    state: "feedback"
    expires_in_seconds: 3600

📡 Гайд по событиям системы ​

📋 Содержание ​

Типы событий ​

Общие поля ​

🔧 Служебные поля ​

Поля scheduled сценариев ​

Поля сообщений ​

Поля ответных сообщений ​

Поля пересланных сообщений ​

Поля callback ​

События платежей ​

Поля pre_checkout_query ​

Поля payment_successful ​

События участников ​

Поля вложений ​

Типы вложений ​

Структура объекта вложения ​

Пример структуры вложения ​

Примеры использования ​

Простые условия ​

Сложные условия ​

Использование в параметрах действий ​

📡 Гайд по событиям системы

📋 Содержание

Типы событий

Общие поля

🔧 Служебные поля

Поля scheduled сценариев

Поля сообщений

Поля ответных сообщений

Поля пересланных сообщений

Поля callback

События платежей

Поля pre_checkout_query

Поля payment_successful

События участников

Поля вложений

Типы вложений

Структура объекта вложения

Пример структуры вложения

Примеры использования

Простые условия

Сложные условия

Использование в параметрах действий