🎯 Гайд по действиям

Полное описание всех доступных действий с их параметрами и результатами.

📋 Содержание

ai_rag_service (4 действий)
ai_service (2 действий)
- completion
- embedding
bot_hub (4 действий)
invoice_service (7 действий)
scenario_helper (9 действий)
scenario_processor (2 действий)
- execute_scenario
- wait_for_action
tenant_hub (4 действий)
user_hub (8 действий)
validator (1 действий)
- validate

^{⭐ — расширение (дополнительный плагин). Для получения информации свяжитесь с разработчиком.}

ai_rag_service

Описание: RAG-расширение для AI Service (векторный поиск и управление embeddings)

⭐ delete_embedding

Описание: Удаление данных из vector_storage по document_id или по дате processed_at

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
document_id (string, опционально) — ID документа для удаления (удаляет все чанки документа). Если указан, остальные параметры игнорируются
until_date (string, опционально) — Удалить чанки с processed_at <= until_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с since_date
since_date (string, опционально) — Удалить чанки с processed_at >= since_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с until_date
metadata_filter (object, опционально) — Фильтр по метаданным (JSON объект): например, {'chat_id': 123, 'username': 'user1'}. Используется для фильтрации чанков по сохраненным метаданным. Можно использовать вместе с until_date/since_date

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Информация об ошибке
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
response_data (object) — Данные ответа
- deleted_chunks_count (integer) — Количество удаленных чанков

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

yaml

# В сценарии
- action: "delete_embedding"
  params:
    tenant_id: 123
    # document_id: string (опционально)
    # until_date: string (опционально)
    # since_date: string (опционально)
    # metadata_filter: object (опционально)

📖 Дополнительная информация

Удаление данных из vector_storage:

Способы удаления:

По document_id - удаляет все чанки документа (остальные параметры игнорируются)
По дате processed_at - удаляет чанки по дате обработки
По metadata_filter - удаляет чанки с определенными метаданными

Параметры даты:

since_date: удалить с даты (включительно)
until_date: удалить до даты (включительно)
Можно указать оба параметра (диапазон)
Формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'

Примеры:

yaml

# По document_id
data:
  document_id: "doc_12345"

# По дате
data:
  until_date: "2024-01-01"

# Диапазон дат
data:
  since_date: "2024-01-01"
  until_date: "2024-12-31"

# По метаданным
data:
  metadata_filter: {chat_id: 123}

⭐ get_recent_chunks

Описание: Получение последних N чанков по дате created_at (не векторный поиск, просто выборка по дате, сортировка по created_at для правильного порядка истории)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
limit_chunks (integer, опционально, диапазон: 1-200) — Количество чанков (по умолчанию 10 из настроек search_limit_chunks). Работает вместе с limit_chars - сначала выбирается limit_chunks чанков, затем фильтруются по limit_chars
limit_chars (integer, опционально, мин: 1) — Лимит по символам (опционально, без ограничения по умолчанию). Работает поверх limit_chunks - после получения limit_chunks чанков они отбираются по порядку (от новых к старым), пока сумма символов не превысит limit_chars. Возвращается столько чанков, сколько влезает в лимит
document_type (string|array, опционально) — Фильтр по типу документа. Строка для одного типа или массив для нескольких типов (например, ['message', 'document'])
document_id (string|array, опционально) — Фильтр по document_id. Строка для одного документа или массив для нескольких (например, ['doc_123', 'doc_456'])
until_date (string, опционально) — Фильтр: искать только чанки с processed_at <= until_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с since_date
since_date (string, опционально) — Фильтр: искать только чанки с processed_at >= since_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с until_date
metadata_filter (object, опционально) — Фильтр по метаданным (JSON объект): например, {'chat_id': 123, 'username': 'user1'}. Используется для фильтрации чанков по сохраненным метаданным. Можно комбинировать с другими фильтрами

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Информация об ошибке
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
response_data (object) — Данные ответа
- chunks (array) — Массив найденных чанков (отсортированы по created_at DESC - новые первыми)
- chunks_count (integer) — Количество найденных чанков

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

yaml

# В сценарии
- action: "get_recent_chunks"
  params:
    tenant_id: 123
    # limit_chunks: integer (опционально)
    # limit_chars: integer (опционально)
    # document_type: string|array (опционально)
    # document_id: string|array (опционально)
    # until_date: string (опционально)
    # since_date: string (опционально)
    # metadata_filter: object (опционально)

📖 Дополнительная информация

Получение последних чанков по дате (НЕ векторный поиск):

Возвращает последние N чанков, отсортированных по created_at (новые первыми, для правильного порядка истории)
Полезно для получения последних сообщений или истории диалога

Параметры:

limit_chunks: количество чанков (по умолчанию 10)
limit_chars: лимит по символам (работает поверх limit_chunks)

Фильтры (комбинируются):

document_type, document_id: строка или массив
since_date, until_date: диапазон дат (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS')
metadata_filter: JSON объект (например, {chat_id: 123})

Примеры:

yaml

# Последние 10 чанков
data:
  limit_chunks: 10

# Последние сообщения
data:
  document_type: "message"
  limit_chunks: 20

# Последние чанки документа
data:
  document_id: "doc_123"
  limit_chunks: 10

# Последние чанки за период
data:
  since_date: "2024-01-01"
  until_date: "2024-12-31"
  limit_chunks: 50

⭐ save_embedding

Описание: Сохранение текста в vector_storage с автоматическим разбиением на чанки и генерацией embeddings. Поддерживает сохранение только текста без эмбеддинга через параметр generate_embedding=false

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
text (string) — Текст для сохранения (будет очищен и разбит на чанки)
document_id (string, опционально) — Уникальный ID документа. Если не указан - будет сгенерирован автоматически через IdSequence (детерминированный по seed)
document_type (string, обязательное, значения: [knowledge, chat_history, other]) — Тип документа: knowledge (база знаний), chat_history (история диалога), other (другое - добавляется в ДОП. КОНТЕКСТ)
role (string, опционально, значения: [system, user, assistant]) — Роль для OpenAI messages (по умолчанию 'user'). Используется при формировании контекста в completion
chunk_metadata (object, опционально) — Метаданные чанка (JSON объект): chat_id, username и др. Сохраняется в chunk_metadata и используется для фильтрации при поиске и удалении. Может быть использовано в chunk_format для отображения в контексте AI
model (string, опционально) — Модель для генерации embedding (по умолчанию из настроек ai_client.default_embedding_model)
dimensions (integer, опционально) — Размерность embedding (по умолчанию 1024)
chunk_size (integer, опционально, диапазон: 100-8000) — Размер чанка в символах (по умолчанию 512)
chunk_overlap (integer, опционально, диапазон: 0-500) — Перекрытие между чанками в символах (по умолчанию 100, ~20% от chunk_size). Сохраняет контекст на границах чанков для лучшего поиска
replace_existing (boolean, опционально) — Заменить существующий документ (по умолчанию false - добавить). Если документ существует и replace_existing=false - вернется ошибка ALREADY_EXISTS
generate_embedding (boolean, опционально) — Генерировать ли embedding для чанков (по умолчанию true). Если false - сохраняется только текст без эмбеддинга (полезно для истории без векторного поиска)
created_at (string, опционально) — Реальная дата создания (для правильной сортировки истории). Поддерживает форматы: ISO, YYYY-MM-DD, YYYY-MM-DD HH:MM:SS. Если не указано - используется текущее локальное время
🔑 ai_token (string) — AI API ключ из конфига тенанта (_config.ai_token). Требуется только если generate_embedding=true

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки: ALREADY_EXISTS (документ существует), INTERNAL_ERROR, VALIDATION_ERROR
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Данные ответа
- document_id (string) — ID сохраненного документа (переданный или сгенерированный)
- document_type (string) — Тип документа
- chunks_count (integer) — Количество созданных чанков
- model (string) (опционально) — Использованная модель embedding (только если generate_embedding=true)
- dimensions (integer) (опционально) — Размерность embedding (только если generate_embedding=true)
- total_tokens (integer) (опционально) — Общее количество токенов во всех чанках (только если generate_embedding=true)
- text_length (integer) — Длина исходного текста (после очистки)

Примечание:

🔑 — поле, которое автоматически берется из конфигурации тенанта (_config) и не требует явной передачи в params

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

yaml

# В сценарии
- action: "save_embedding"
  params:
    tenant_id: 123
    text: "example"
    # document_id: string (опционально)
    document_type: "example"
    # role: string (опционально)
    # chunk_metadata: object (опционально)
    # model: string (опционально)
    # dimensions: integer (опционально)
    # chunk_size: integer (опционально)
    # chunk_overlap: integer (опционально)
    # replace_existing: boolean (опционально)
    # generate_embedding: boolean (опционально)
    # created_at: string (опционально)
    ai_token: "example"

📖 Дополнительная информация

Автоматическое сохранение текста с разбиением на чанки:

Очистка текста (лишние пробелы, невидимые символы)
Разбиение на чанки (гибридный подход: по предложениям/абзацам → по символам)
Генерация embeddings (параллельно, если generate_embedding=true)
Сохранение в vector_storage

Режимы сохранения:

generate_embedding=true (по умолчанию): с эмбеддингами для векторного поиска
generate_embedding=false: только текст без эмбеддингов (экономит токены, не требует ai_token)

Перекрытие чанков (chunk_overlap):

Сохраняет контекст на границах для лучшего поиска
Рекомендуется ~20% от chunk_size (по умолчанию 100 при chunk_size=512)
Расширяется до целых предложений при разбиении

Генерация document_id:

Если не указан → генерируется автоматически (детерминированный)
Seed: {tenant_id}:{document_type}:{MD5(text)}
Повторная загрузка того же текста вернет тот же ID

Обработка существующих документов:

replace_existing=false (по умолчанию): ошибка ALREADY_EXISTS если документ существует
replace_existing=true: старые чанки удаляются, создаются новые

Пример:

yaml

action: save_embedding
data:
  text: "Длинный текст..."
  document_type: "knowledge"
  chunk_size: 512
  chunk_overlap: 100

# Ответ:
result: success
response_data:
  document_id: "doc_12345"
  chunks_count: 5
  total_tokens: 150

⭐ search_embedding

Описание: Поиск похожих чанков по тексту или вектору (semantic search) через cosine similarity

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
query_text (string, опционально) — Текст запроса для поиска (будет преобразован в embedding). Необходимо указать либо query_text, либо query_vector
query_vector (array, опционально) — Готовый вектор для поиска (массив чисел). Размерность должна совпадать с сохраненными embeddings. Необходимо указать либо query_text, либо query_vector
limit_chunks (integer, опционально, диапазон: 1-200) — Количество результатов (top-k, по умолчанию 10). Работает вместе с limit_chars - сначала выбирается limit_chunks чанков, затем фильтруются по limit_chars
limit_chars (integer, опционально, мин: 1) — Лимит по символам (опционально, без ограничения по умолчанию). Работает поверх limit_chunks - после получения limit_chunks чанков они отбираются по порядку (от большего similarity), пока сумма символов не превысит limit_chars. Возвращается столько чанков, сколько влезает в лимит
min_similarity (number, опционально, диапазон: 0.0-1.0) — Минимальный порог схожести (cosine similarity, по умолчанию из настроек search_min_similarity)
document_id (string|array, опционально) — Фильтр по document_id. Строка для одного документа или массив для нескольких (например, ['doc_123', 'doc_456'])
document_type (string|array, опционально) — Фильтр по типу документа. Строка для одного типа или массив для нескольких типов (например, ['message', 'document'])
until_date (string, опционально) — Фильтр: искать только чанки с processed_at <= until_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с since_date
since_date (string, опционально) — Фильтр: искать только чанки с processed_at >= since_date включительно (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'). Можно использовать вместе с until_date
metadata_filter (object, опционально) — Фильтр по метаданным (JSON объект): например, {'chat_id': 123, 'username': 'user1'}. Используется для фильтрации чанков по сохраненным метаданным. Можно комбинировать с другими фильтрами
model (string, опционально) — Модель для генерации embedding (используется только если указан query_text, по умолчанию из настроек ai_client.default_embedding_model)
dimensions (integer, опционально) — Размерность embedding (используется только если указан query_text, по умолчанию 1024)
🔑 ai_token (string) — AI API ключ из конфига тенанта (_config.ai_token). Требуется только если указан query_text

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Информация об ошибке
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
response_data (object) — Данные ответа
- chunks (array) — Массив найденных чанков
- chunks_count (integer) — Количество найденных чанков

Примечание:

🔑 — поле, которое автоматически берется из конфигурации тенанта (_config) и не требует явной передачи в params

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

yaml

# В сценарии
- action: "search_embedding"
  params:
    tenant_id: 123
    # query_text: string (опционально)
    # query_vector: array (опционально)
    # limit_chunks: integer (опционально)
    # limit_chars: integer (опционально)
    # min_similarity: number (опционально)
    # document_id: string|array (опционально)
    # document_type: string|array (опционально)
    # until_date: string (опционально)
    # since_date: string (опционально)
    # metadata_filter: object (опционально)
    # model: string (опционально)
    # dimensions: integer (опционально)
    ai_token: "example"

📖 Дополнительная информация

Семантический поиск похожих чанков:

Поиск по cosine similarity между векторами
Использует HNSW индекс для быстрого поиска
Результаты сортируются по убыванию similarity

Запрос (требуется одно из):

query_text: текст (генерируется embedding автоматически)
query_vector: готовый вектор (не требует API ключ)

Параметры поиска:

limit_chunks: top-k результатов (по умолчанию 10)
limit_chars: лимит по символам (работает поверх limit_chunks)
min_similarity: минимальный порог (0.0-1.0, по умолчанию 0.7)

Фильтры (комбинируются):

document_type, document_id: строка или массив
since_date, until_date: диапазон дат (формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS')
metadata_filter: JSON объект (например, {chat_id: 123})

Примеры:

yaml

# Поиск по тексту
data:
  query_text: "Как работает RAG?"
  limit_chunks: 10
  min_similarity: 0.75

# Поиск с фильтрами
data:
  query_text: "Вопрос"
  document_type: ["message", "document"]
  since_date: "2024-01-01"
  until_date: "2024-12-31"

# Поиск с лимитом по символам
data:
  query_text: "Вопрос"
  limit_chunks: 20
  limit_chars: 5000

ai_service

Описание: Сервис для интеграции ИИ в сценарии

completion

Описание: AI completion через ИИ

Входные параметры:

prompt (string) — Текст запроса пользователя
system_prompt (string, опционально) — Системный промпт для контекста
model (string, опционально) — Модель AI (по умолчанию из настроек)
max_tokens (integer, опционально) — Максимальное количество токенов (по умолчанию из настроек)
temperature (float, опционально, диапазон: 0.0-2.0) — Температура генерации (по умолчанию из настроек)
context (string, опционально) — Кастомный контекст (добавляется в финальное user сообщение в блок ДОП. КОНТЕКСТ вместе с other чанками из rag_chunks)
rag_chunks (array, опционально) — Массив чанков из RAG поиска для автоматического формирования messages. Чанки группируются по типам: chat_history (диалог), knowledge (база знаний), other (другое - добавляется в ДОП. КОНТЕКСТ). Формат: [{content, document_type, role, processed_at, ...}]
json_mode (string, опционально, значения: [json_object, json_schema]) — Режим JSON для структурированного ответа: 'json_object' или 'json_schema'
json_schema (object, опционально) — JSON схема для режима json_schema (обязательна при json_mode='json_schema')
tools (array, опционально) — Список доступных функций для вызова моделью (tool calling)
tool_choice (string, опционально) — Управление выбором инструментов: 'none', 'auto', 'required' или объект с конкретной функцией
chunk_format (object, опционально) — Формат отображения чанков в контексте. Шаблоны используют маркеры $ для подстановки значений: $content (обязательно) + любые поля из chunk_metadata. Поддерживается модификатор fallback: $field|fallback:значение. Маркеры работают только с данными чанка (content + chunk_metadata), не затрагивая общий контекст.
🔑 ai_token (string) — AI API ключ из конфига тенанта (_config.ai_token)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error, timeout
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Данные ответа
- response_completion (string) — Completion ответ от ИИ
- prompt_tokens (integer) — Токены на вход (prompt + context)
- completion_tokens (integer) — Токены на выход (сгенерированный ответ)
- total_tokens (integer) — Общее количество токенов (prompt + completion)
- model (string) — Использованная модель
- response_dict (object) (опционально) — Распарсенный словарь из JSON ответа (только при использовании json_mode)
- tool_calls (array) (опционально) — Список вызовов функций, которые модель решила выполнить (только при использовании tools)

Примечание:

🔑 — поле, которое автоматически берется из конфигурации тенанта (_config) и не требует явной передачи в params

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

yaml

# В сценарии
- action: "completion"
  params:
    prompt: "example"
    # system_prompt: string (опционально)
    # model: string (опционально)
    # max_tokens: integer (опционально)
    # temperature: float (опционально)
    # context: string (опционально)
    # rag_chunks: array (опционально)
    # json_mode: string (опционально)
    # json_schema: object (опционально)
    # tools: array (опционально)
    # tool_choice: string (опционально)
    # chunk_format: object (опционально)
    ai_token: "example"

📖 Дополнительная информация

JSON режимы:

json_object: модель возвращает валидный JSON (парсится в response_dict)
json_schema: строгая JSON схема (требуется json_schema параметр)

Tool Calling:

Параметр tools позволяет модели вызывать функции
Модель решает, какие функции вызвать и с какими параметрами
Результаты вызовов в response_data.tool_calls
tool_choice: управление выбором ('none', 'auto', 'required', или конкретная функция)

Формат чанков (chunk_format):

Настройка отображения чанков из RAG через шаблоны с маркерами $
Доступны: $content (обязательно) + любые поля из chunk_metadata
Поддерживается fallback: $field|fallback:значение (если поле пустое/отсутствует)
Маркеры работают только с данными чанка (content + chunk_metadata)
Примеры: "[$username]: $content", "[$category|fallback:Общее]: $content"
Можно задать разные шаблоны для chat_history, knowledge, other

embedding

Описание: Генерация embedding для текста через ИИ

Входные параметры:

text (string) — Текст для генерации embedding
model (string, опционально) — Модель для генерации embedding (по умолчанию из настроек ai_client.default_embedding_model)
dimensions (integer, опционально) — Размерность embedding (по умолчанию из настроек ai_client.default_embedding_dimensions). Поддерживается только для OpenAI text-embedding-3-small и text-embedding-3-large
🔑 ai_token (string) — AI API ключ из конфига тенанта (_config.ai_token)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Данные ответа
- embedding (array) — Вектор embedding (список чисел)
- model (string) — Использованная модель
- dimensions (integer) — Размерность embedding
- total_tokens (integer) — Общее количество токенов

Примечание:

🔑 — поле, которое автоматически берется из конфигурации тенанта (_config) и не требует явной передачи в params

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

yaml

# В сценарии
- action: "embedding"
  params:
    text: "example"
    # model: string (опционально)
    # dimensions: integer (опционально)
    ai_token: "example"

📖 Дополнительная информация

Генерация векторных представлений текста (embeddings):

Используется для RAG (Retrieval-Augmented Generation) и векторного поиска
Возвращает массив чисел (embedding) - векторное представление текста

Размерность (dimensions):

По умолчанию 1024 (настраивается в ai_client.default_embedding_dimensions)
Поддерживается не всеми моделями (для моделей без поддержки размерность фиксирована)

Пример:

yaml

action: embedding
data:
  text: "Текст для векторизации"
  dimensions: 1024

# Ответ:
result: success
response_data:
  embedding: [0.123, -0.456, ...]  # Вектор из 1024 чисел
  dimensions: 1024
  total_tokens: 15

bot_hub

Описание: Центральный сервис для управления всеми ботами

answer_callback_query

Описание: Ответ на callback query (всплывающее уведомление или простое уведомление при нажатии на inline-кнопку)

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота
callback_query_id (string, обязательное, мин. длина: 1) — ID callback query (можно использовать плейсхолдер {callback_id} из события)
text (string, опционально, макс. длина: 200) — Текст уведомления (до 200 символов). Если не указан, показывается простое уведомление без текста
show_alert (boolean, опционально) — Показать всплывающее окно (alert). По умолчанию false - простое уведомление вверху экрана. true - модальное окно с текстом
cache_time (integer, опционально, диапазон: 0-3600) — Время кэширования ответа в секундах (0-3600). По умолчанию 0

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)

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

yaml

# В сценарии
- action: "answer_callback_query"
  params:
    bot_id: 123
    callback_query_id: "example"
    # text: string (опционально)
    # show_alert: boolean (опционально)
    # cache_time: integer (опционально)

build_keyboard

Описание: Построение клавиатуры из массива ID с использованием шаблонов

Входные параметры:

items (array) — Массив ID для генерации кнопок (например, [1, 2, 3] или tenant_ids из get_tenants_list)
keyboard_type (string, обязательное, значения: [inline, reply]) — Тип клавиатуры: 'inline' или 'reply'
text_template (string, обязательное, мин. длина: 1) — Шаблон текста кнопки с плейсхолдером $value$ (например, 'Tenant $value$' или 'Пользователь #$value$'). Используется синтаксис $value$ вместо {value} чтобы избежать конфликта с системой плейсхолдеров
callback_template (string, опционально, мин. длина: 1) — Шаблон callback_data для inline клавиатуры с плейсхолдером $value$ (обязателен для inline, например, 'select_tenant_$value$'). Используется синтаксис $value$ вместо {value} чтобы избежать конфликта с системой плейсхолдеров
buttons_per_row (integer, опционально, диапазон: 1-8) — Количество кнопок в строке (по умолчанию 1, например, 2 для двух кнопок в ряд)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Данные ответа
- keyboard (array) — Готовая клавиатура в формате массива строк (можно использовать напрямую в параметре inline или reply действия send_message)
- keyboard_type (string) — Тип клавиатуры: 'inline' или 'reply'
- rows_count (integer) — Количество строк в клавиатуре
- buttons_count (integer) — Общее количество кнопок в клавиатуре

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

yaml

# В сценарии
- action: "build_keyboard"
  params:
    items: []
    keyboard_type: "example"
    text_template: "example"
    # callback_template: string (опционально)
    # buttons_per_row: integer (опционально)

delete_message

Описание: Удаление сообщения ботом

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота
delete_message_id (integer, опционально, мин: 1) — ID сообщения для удаления. Если не указан, используется message_id из контекста события. Chat ID по умолчанию берется из события (chat_id), если не указан явно

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)

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

yaml

# В сценарии
- action: "delete_message"
  params:
    bot_id: 123
    # delete_message_id: integer (опционально)

send_message

Описание: Отправка сообщения ботом

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота
target_chat_id (integer|array|string, опционально) — ID чата или массив ID чатов для отправки (по умолчанию берется chat_id из события)
text (string, опционально) — Текст сообщения (может быть пустым, если есть вложение)
parse_mode (string, опционально, значения: [HTML, Markdown, MarkdownV2]) — Режим парсинга (HTML, Markdown, MarkdownV2)
message_edit (integer|boolean|string, опционально) — Редактирование сообщения: integer (ID сообщения) или true/false. При редактировании работа происходит только с первым чатом из списка (по умолчанию редактирует текущее сообщение из события)
message_reply (integer, опционально, мин: 1) — ID сообщения для ответа
inline (array, опционально) — Inline клавиатура (массив строк с кнопками). Можно указать только одну клавиатуру (inline или reply) - это ограничение Telegram API. Если указаны обе клавиатуры, используется inline (имеет приоритет)
reply (array, опционально) — Reply клавиатура (массив строк с кнопками). Можно указать только одну клавиатуру (inline или reply) - это ограничение Telegram API. Если указаны обе клавиатуры, используется inline (имеет приоритет)
attachment (array, опционально) — Вложения (файлы, фото, видео и т.д.)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Данные ответа
- 🔀 last_message_id (integer) — ID последнего отправленного сообщения (при отправке в несколько чатов возвращается ID первого отправленного)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "send_message"
  params:
    bot_id: 123
    # target_chat_id: integer|array|string (опционально)
    # text: string (опционально)
    # parse_mode: string (опционально)
    # message_edit: integer|boolean|string (опционально)
    # message_reply: integer (опционально)
    # inline: array (опционально)
    # reply: array (опционально)
    # attachment: array (опционально)

invoice_service

Описание: Сервис для работы с инвойсами (создание, управление, обработка платежей)

cancel_invoice

Описание: Отмена инвойса (установка флага is_cancelled)

Входные параметры:

invoice_id (integer, обязательное, мин: 1) — ID инвойса (обязательно)

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "cancel_invoice"
  params:
    invoice_id: 123

confirm_payment

Описание: Подтверждение платежа (ответ на pre_checkout_query с подтверждением)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
bot_id (integer, обязательное, мин: 1) — ID бота
pre_checkout_query_id (string, обязательное, мин. длина: 1) — ID запроса на подтверждение (обязательно)
invoice_payload (string, опционально, мин. длина: 1) — ID инвойса из payload (опционально, для проверки статуса инвойса перед подтверждением)
error_message (string, опционально) — Сообщение об ошибке при отклонении платежа (опционально, используется если инвойс отменен или уже оплачен)

Выходные параметры:

result (string) — Результат: success (платеж подтвержден), failed (платеж отклонен по бизнес-логике), error (техническая ошибка)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки. Возможные значения: INVOICE_CANCELLED (при result=failed - инвойс отменен), INVOICE_ALREADY_PAID (при result=failed - инвойс уже оплачен)
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "confirm_payment"
  params:
    tenant_id: 123
    bot_id: 123
    pre_checkout_query_id: "example"
    # invoice_payload: string (опционально)
    # error_message: string (опционально)

create_invoice

Описание: Создание инвойса в БД и отправка/создание ссылки

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
bot_id (integer, обязательное, мин: 1) — ID бота
target_user_id (integer, опционально, мин: 1) — ID пользователя для создания инвойса (опционально, по умолчанию user_id из события)
chat_id (integer, опционально) — ID чата для отправки (обязательно для отправки, не нужен для ссылки)
title (string, обязательное, мин. длина: 1) — Название товара/услуги (обязательно)
description (string, опционально) — Описание товара/услуги
amount (integer, обязательное, мин: 1) — Количество звезд (обязательно, целое число)
currency (string, опционально) — Валюта (по умолчанию XTR для звезд)
as_link (boolean, опционально) — Создать как ссылку вместо отправки (по умолчанию false - отправка)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа
- invoice_id (integer) — ID созданного инвойса
- invoice_message_id (integer) (опционально) — ID отправленного сообщения с инвойсом (если as_link=false)
- invoice_link (string) (опционально) — Ссылка на инвойс (если as_link=true)

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

yaml

# В сценарии
- action: "create_invoice"
  params:
    tenant_id: 123
    bot_id: 123
    # target_user_id: integer (опционально)
    # chat_id: integer (опционально)
    title: "example"
    # description: string (опционально)
    amount: 123
    # currency: string (опционально)
    # as_link: boolean (опционально)

get_invoice

Описание: Получение информации об инвойсе

Входные параметры:

invoice_id (integer, обязательное, мин: 1) — ID инвойса (обязательно)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа
- invoice (object) — Данные инвойса

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

yaml

# В сценарии
- action: "get_invoice"
  params:
    invoice_id: 123

get_user_invoices

Описание: Получение всех инвойсов пользователя

Входные параметры:

target_user_id (integer, опционально, мин: 1) — ID пользователя для получения инвойсов (опционально, по умолчанию user_id из события)
include_cancelled (boolean, опционально) — Включать отмененные инвойсы (по умолчанию false)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа
- invoices (array) — Массив инвойсов пользователя

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

yaml

# В сценарии
- action: "get_user_invoices"
  params:
    # target_user_id: integer (опционально)
    # include_cancelled: boolean (опционально)

mark_invoice_as_paid

Описание: Отметить инвойс как оплаченный (обработка события payment_successful)

Входные параметры:

invoice_payload (string, обязательное, мин. длина: 1) — ID инвойса из payload события (обязательно)
telegram_payment_charge_id (string, обязательное, мин. длина: 1) — ID платежа в Telegram (обязательно)
paid_at (string, опционально) — Дата оплаты (опционально, по умолчанию текущая дата)

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "mark_invoice_as_paid"
  params:
    invoice_payload: "example"
    telegram_payment_charge_id: "example"
    # paid_at: string (опционально)

reject_payment

Описание: Отклонение платежа (ответ на pre_checkout_query с отклонением)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
bot_id (integer, обязательное, мин: 1) — ID бота
pre_checkout_query_id (string, обязательное, мин. длина: 1) — ID запроса на подтверждение (обязательно)
error_message (string, опционально) — Сообщение об ошибке (опционально)

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "reject_payment"
  params:
    tenant_id: 123
    bot_id: 123
    pre_checkout_query_id: "example"
    # error_message: string (опционально)

scenario_helper

Описание: Вспомогательные утилиты для управления выполнением сценариев

check_value_in_array

Описание: Проверка наличия значения в массиве

Входные параметры:

array (array) — Массив для проверки
value (any) — Значение для поиска в массиве

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success (найдено), not_found (не найдено), error (ошибка)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 response_index (integer) — Порядковый номер (индекс) первого вхождения значения в массиве (только при result: success)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "check_value_in_array"
  params:
    array: []
    value: "value"

choose_from_array

Описание: Выбор случайных элементов из массива без повторений

Входные параметры:

array (array) — Исходный массив для выбора элементов
count (integer, обязательное, мин: 1) — Количество элементов для выбора (без повторений)
seed (any, опционально) — Seed для детерминированной генерации (опционально, может быть числом, строкой или другим типом)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 random_list (array) — Массив выбранных элементов (без повторений)
- random_seed (string) (опционально) — Использованный seed (если был передан, сохраняется как есть)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "choose_from_array"
  params:
    array: []
    count: 123
    # seed: any (опционально)

format_data_to_text

Описание: Форматирование структурированных данных (JSON/YAML) в текстовый формат для промптов и сообщений

Входные параметры:

format_type (string, обязательное, значения: [list, structured]) — Тип форматирования: 'list' (простой список с шаблоном через $), 'structured' (структурированный формат с заголовками и вложенными блоками)
input_data (any) — Массив объектов для форматирования
title (string, опционально) — Заголовок для списка (опционально)
item_template (string, опционально, мин. длина: 1) — Шаблон элемента для формата 'list' через $ (например: '- "$id" - $description'). Обязателен при format_type: 'list'

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 formatted_text (string) — Отформатированный текст

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "format_data_to_text"
  params:
    format_type: "example"
    input_data: "value"
    # title: string (опционально)
    # item_template: string (опционально)

📖 Дополнительная информация

Форматы:

list — простой список с шаблоном через $
structured — структурированный формат: name — description, блок Параметры: с деталями

Примеры:

yaml

# Формат list
- action: "format_data_to_text"
  params:
    format_type: "list"
    title: "Доступные намерения:"
    item_template: '- "$id" - $description'
    input_data: "{storage_values.ai_router.intents}"
# Результат в _cache.format_data_to_text.formatted_text:
# Доступные намерения:
# - "random_user" - Выбрать случайного пользователя

# Формат structured
- action: "format_data_to_text"
  params:
    format_type: "structured"
    title: "Доступные действия:"
    input_data: "{storage_values.ai_router.actions}"
# Результат в _cache.format_data_to_text.formatted_text:
# Доступные действия:
# call_random_user — Выбрать N пользователей из группы
#   Параметры:
#   - count (integer) — Количество пользователей. По умолчанию: 1

Важно:

Шаблон для list использует $ вместо {} для избежания конфликта с плейсхолдерами
Результат сохраняется в _cache.format_data_to_text.formatted_text (по умолчанию)
Если указан _namespace в params, результат будет в _cache.{_namespace}.formatted_text

generate_array

Описание: Генерация массива случайных чисел в заданном диапазоне (по умолчанию без повторений)

Входные параметры:

min (integer) — Минимальное значение (включительно)
max (integer) — Максимальное значение (включительно)
count (integer, обязательное, мин: 1) — Количество чисел для генерации
seed (any, опционально) — Seed для детерминированной генерации (опционально, может быть числом, строкой или другим типом)
allow_duplicates (boolean, опционально) — Разрешить повторения в массиве (по умолчанию false - без повторений)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 random_list (array) — Массив сгенерированных чисел
- random_seed (string) (опционально) — Использованный seed (если был передан, сохраняется как есть)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "generate_array"
  params:
    min: 123
    max: 123
    count: 123
    # seed: any (опционально)
    # allow_duplicates: boolean (опционально)

generate_int

Описание: Генерация случайного целого числа в заданном диапазоне

Входные параметры:

min (integer) — Минимальное значение (включительно)
max (integer) — Максимальное значение (включительно)
seed (any, опционально) — Seed для детерминированной генерации (опционально, может быть числом, строкой или другим типом)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 random_value (integer) — Сгенерированное случайное число
- random_seed (string) (опционально) — Использованный seed (если был передан, сохраняется как есть)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "generate_int"
  params:
    min: 123
    max: 123
    # seed: any (опционально)

generate_unique_id

Описание: Генерация уникального ID через автоинкремент в БД (детерминированная генерация - при одинаковых seed возвращает тот же ID). Если seed не указан, генерируется случайный UUID

Входные параметры:

seed (string, опционально, мин. длина: 1) — Seed для генерации ID. При повторном запросе с тем же seed вернется тот же ID. Если не указан, генерируется случайный UUID

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 unique_id (integer) — Уникальный ID (гарантированно уникальный, при одинаковых входных данных возвращается тот же ID)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "generate_unique_id"
  params:
    # seed: string (опционально)

modify_array

Описание: Модификация массива: добавление, удаление элементов или очистка

Входные параметры:

operation (string, обязательное, значения: [add, remove, clear]) — Операция: 'add' (добавить элемент), 'remove' (удалить элемент), 'clear' (очистить массив)
array (array) — Исходный массив для модификации
value (any, опционально) — Значение для добавления или удаления (обязательно для операций 'add' и 'remove')
skip_duplicates (boolean, опционально) — Пропускать дубликаты при добавлении (по умолчанию true - не добавлять если элемент уже есть)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success (успешно), not_found (элемент не найден при операции remove), error (ошибка)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 modified_array (array) — Модифицированный массив

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "modify_array"
  params:
    operation: "example"
    array: []
    # value: any (опционально)
    # skip_duplicates: boolean (опционально)

set_cache

Описание: Установка временных данных в кэш сценария. Все переданные параметры возвращаются в response_data и автоматически попадают в плоский _cache по умолчанию.

Входные параметры:

cache (object) — Объект с данными для установки в кэш. Все переданные параметры будут доступны в последующих шагах сценария через {_cache.ключ} (плоский доступ по умолчанию)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Все переданные параметры из объекта cache возвращаются в response_data и автоматически попадают в плоский _cache по умолчанию.
- * (any) — Динамические ключи из переданного объекта cache. Все ключи доступны через {_cache.имя_ключа} (плоский доступ по умолчанию)

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

yaml

# В сценарии
- action: "set_cache"
  params:
    cache: {}

📖 Дополнительная информация

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

yaml

step:
  - action: "set_cache"
    params:
      cache:
        selected_user: "@username"
        reason: "Случайный выбор"
        metadata:
          timestamp: "2024-01-15"
          source: "ai_router"
  
  - action: "send_message"
    params:
      text: |
        Пользователь: {_cache.selected_user}
        Причина: {_cache.reason}
        Время: {_cache.metadata.timestamp}
        Источник: {_cache.metadata.source}

Важно:

Данные должны быть переданы в ключе cache в params
Это позволяет явно указать, что именно нужно кэшировать
Весь контекст сценария (user_id, chat_id, bot_id и др.) не попадет в кэш

Доступ к данным:

Все переданные параметры доступны через плейсхолдеры {_cache.ключ} (плоский доступ по умолчанию)
Поддерживаются вложенные структуры: {_cache.metadata.timestamp}
Данные автоматически очищаются после завершения выполнения сценария

sleep

Описание: Задержка выполнения на указанное количество секунд

Входные параметры:

seconds (float, обязательное, мин: 0.0) — Количество секунд задержки (можно использовать дробные значения, например 0.5 или 22.5)

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sleep"
  params:
    seconds: "value"

scenario_processor

Описание: Сервис для обработки событий по сценариям

execute_scenario

Описание: Выполнение сценария или массива сценариев по имени

Входные параметры:

scenario (string|array) — Название сценария (строка) или массив названий сценариев
tenant_id (integer, обязательное, мин: 1) — ID tenant'а (передается автоматически из контекста)
return_cache (boolean, опционально) — Возвращать ли _cache из выполненного сценария (по умолчанию true). ВАЖНО: работает только для одиночных сценариев (строка), для массива сценариев игнорируется и кэш не возвращается

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа с результатом выполнения сценария
- scenario_result (string) — Результат выполнения сценария: success, error, abort, break, stop
- _cache (object) (опционально) — Кэш из выполненного сценария, возвращается только для одиночных сценариев (не для массива), если return_cache=true и в сценарии был установлен _cache через set_cache. Данные попадают в _cache[action_name] автоматически

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

yaml

# В сценарии
- action: "execute_scenario"
  params:
    scenario: "value"
    tenant_id: 123
    # return_cache: boolean (опционально)

wait_for_action

Описание: Ожидание завершения асинхронного действия по action_id. Возвращает результат основного действия AS IS (как будто оно выполнилось напрямую)

Входные параметры:

action_id (string, обязательное, мин. длина: 1) — Уникальный ID асинхронного действия для ожидания
timeout (integer, опционально, мин: 0.0) — Таймаут ожидания в секундах (опционально). При истечении таймаута wait_for_action возвращает ошибку timeout, но выполнение сценария продолжается. Основное асинхронное действие продолжает выполняться в фоне даже после таймаута.

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат зависит от основного действия: если основное действие завершилось успешно - возвращается его результат (success/error и т.д.), если ошибка ожидания (таймаут, Future не найден) - возвращается ошибка wait_for_action (timeout/error)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа. Если основное действие завершилось успешно - возвращаются данные основного действия (полностью подменяются), если ошибка ожидания - отсутствует

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

yaml

# В сценарии
- action: "wait_for_action"
  params:
    action_id: "example"
    # timeout: integer (опционально)

tenant_hub

Описание: Сервис для управления конфигурациями тенантов - координатор загрузки данных

delete_storage

Описание: Удаление значений или групп из storage. Если указан key или key_pattern - удаляется значение, иначе удаляется группа

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
group_key (string, опционально) — Ключ группы (точное совпадение, приоритет над group_key_pattern)
group_key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска группы (ILIKE, используется если group_key не указан)
key (string, опционально) — Ключ атрибута (точное совпадение, приоритет над key_pattern). Если указан - удаляется значение, иначе удаляется группа
key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска ключа (ILIKE, используется если key не указан). Если указан - удаляется значение, иначе удаляется группа

Выходные параметры:

result (string) — Результат: success, error, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "delete_storage"
  params:
    tenant_id: 123
    # group_key: string (опционально)
    # group_key_pattern: string (опционально)
    # key: string (опционально)
    # key_pattern: string (опционально)

get_storage

Описание: Получение значений storage для тенанта. Поддерживает получение всех значений, группы, конкретного значения, а также поиск по паттернам

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
group_key (string, опционально) — Ключ группы (точное совпадение, приоритет над group_key_pattern)
group_key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска группы (ILIKE, используется если group_key не указан)
key (string, опционально) — Ключ атрибута (точное совпадение, приоритет над key_pattern). Используется только если указан group_key или group_key_pattern
key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска ключа (ILIKE, используется если key не указан). Используется только если указан group_key или group_key_pattern
format (boolean, опционально) — Если true, возвращает дополнительное поле formatted_text с данными в формате YAML

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 storage_values (any) — Запрошенные данные. Если указаны group_key и key - возвращается прямое значение (примитив или объект как есть). Если указан только group_key - возвращается структура группы {key: value}. Если ничего не указано - возвращается полная структура {group_key: {key: value}}
- formatted_text (string) (опционально) — Отформатированный текст в формате YAML (возвращается только если format=true)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_storage"
  params:
    tenant_id: 123
    # group_key: string (опционально)
    # group_key_pattern: string (опционально)
    # key: string (опционально)
    # key_pattern: string (опционально)
    # format: boolean (опционально)

get_storage_groups

Описание: Получение списка уникальных ключей групп для тенанта. Возвращает только список group_key без значений (с ограничением на количество групп)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 group_keys (array) — Список уникальных ключей групп (ограничен настройкой storage_groups_max_limit)
- is_truncated (boolean) (опционально) — Флаг, указывающий что список был обрезан (true если групп больше лимита, иначе поле отсутствует)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_storage_groups"
  params:
    tenant_id: 123

set_storage

Описание: Установка значений storage для тенанта. Поддерживает смешанный подход: полная структура через values или частичная через group_key/key/value

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта (обязательно)
group_key (string, опционально) — Ключ группы (с поддержкой плейсхолдеров). Если указан, используется смешанный подход
key (string, опционально) — Ключ значения (с поддержкой плейсхолдеров). Используется вместе с group_key
value (any, опционально) — Значение для установки. Используется вместе с group_key и key
values (object, опционально) — Структура для установки. Если указан group_key - структура для группы {key: value}, иначе полная структура {group_key: {key: value}}
format (boolean, опционально) — Если true, возвращает дополнительное поле formatted_text с данными в формате YAML

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 storage_values (any) — Установленные данные. Если установлено одно значение (group_key + key + value) - возвращается прямое значение (примитив или объект как есть). Если установлена группа (group_key + values) - возвращается структура группы {key: value}. Если установлена полная структура (values) - возвращается полная структура {group_key: {key: value}}
- formatted_text (string) (опционально) — Отформатированный текст в формате YAML (возвращается только если format=true)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "set_storage"
  params:
    tenant_id: 123
    # group_key: string (опционально)
    # key: string (опционально)
    # value: any (опционально)
    # values: object (опционально)
    # format: boolean (опционально)

user_hub

Описание: Центральный сервис для управления состояниями пользователей

clear_user_state

Описание: Очистка состояния пользователя

Входные параметры:

user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
tenant_id (integer, обязательное, мин: 1) — ID тенанта

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "clear_user_state"
  params:
    user_id: 123
    tenant_id: 123

delete_user_storage

Описание: Удаление значений из storage пользователя

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
key (string, опционально) — Ключ для удаления конкретного значения (точное совпадение, приоритет над key_pattern). Если не указаны key и key_pattern - удаляются все записи пользователя
key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска ключей для удаления (ILIKE, используется если key не указан). Если не указаны key и key_pattern - удаляются все записи пользователя

Выходные параметры:

result (string) — Результат: success, error, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)

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

yaml

# В сценарии
- action: "delete_user_storage"
  params:
    tenant_id: 123
    user_id: 123
    # key: string (опционально)
    # key_pattern: string (опционально)

get_tenant_users

Описание: Получение списка всех user_id для указанного тенанта

Входные параметры:

tenant_id (integer) — ID тенанта

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 user_ids (array) — Массив ID пользователей Telegram
- user_count (integer) — Количество пользователей

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_tenant_users"
  params:
    tenant_id: 123

get_user_state

Описание: Получение состояния пользователя с проверкой истечения

Входные параметры:

user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
tenant_id (integer, обязательное, мин: 1) — ID тенанта

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа
- 🔀 user_state (string) (опционально) — Состояние пользователя или None если истекло/не установлено
- user_state_expired_at (string) (опционально) — Время истечения состояния (ISO) или None если не установлено

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_user_state"
  params:
    user_id: 123
    tenant_id: 123

get_user_storage

Описание: Получение значений storage для пользователя. Поддерживает получение всех значений, конкретного значения (key) или поиск по паттерну (key_pattern)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
key (string, опционально) — Ключ для получения конкретного значения (точное совпадение, приоритет над key_pattern)
key_pattern (string, опционально, мин. длина: 1) — Паттерн для поиска ключей (ILIKE, используется если key не указан)
format (boolean, опционально) — Если true, возвращает дополнительное поле formatted_text с данными в формате YAML

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 user_storage_values (any) — Запрошенные данные. Если указан key - возвращается прямое значение (примитив или объект как есть). Если ничего не указано - возвращается полная структура
- formatted_text (string) (опционально) — Отформатированный текст в формате YAML (возвращается только если format=true)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_user_storage"
  params:
    tenant_id: 123
    user_id: 123
    # key: string (опционально)
    # key_pattern: string (опционально)
    # format: boolean (опционально)

get_users_by_storage_value

Описание: Поиск пользователей по ключу и значению в storage. Позволяет найти всех пользователей, у которых в storage есть определенный ключ с определенным значением (например, найти всех пользователей с подключенной подпиской)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
key (string, обязательное, мин. длина: 1) — Ключ для поиска в storage
value (string|integer|float|boolean|array|object) — Значение для поиска (может быть простым типом или JSON объектом)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 user_ids (array) — Массив ID пользователей Telegram, у которых storage[key] == value
- user_count (integer) — Количество найденных пользователей

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_users_by_storage_value"
  params:
    tenant_id: 123
    key: "example"
    value: "value"

set_user_state

Описание: Установка состояния пользователя

Входные параметры:

user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
tenant_id (integer, обязательное, мин: 1) — ID тенанта
state (string, опционально) — Состояние пользователя (None или пустая строка для сброса)
expires_in_seconds (integer, опционально, мин: 0) — Время истечения в секундах (None или 0 = навсегда, устанавливается 3000 год)

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные ответа
- user_state (string) (опционально) — Состояние пользователя или None если истекло/не установлено
- user_state_expired_at (string) (опционально) — Время истечения состояния (ISO) или None если не установлено

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

yaml

# В сценарии
- action: "set_user_state"
  params:
    user_id: 123
    tenant_id: 123
    # state: string (опционально)
    # expires_in_seconds: integer (опционально)

set_user_storage

Описание: Установка значений storage для пользователя. Поддерживает смешанный подход: полная структура через values или частичная через key/value

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
user_id (integer, обязательное, мин: 1) — ID пользователя Telegram
key (string, опционально) — Ключ значения (с поддержкой плейсхолдеров). Если указан, используется смешанный подход
value (any, опционально) — Значение для установки. Используется вместе с key
values (object, опционально) — Полная структура для установки {key: value}. Используется только если не указан key
format (boolean, опционально) — Если true, возвращает дополнительное поле formatted_text с данными в формате YAML

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- 🔀 user_storage_values (any) — Установленные данные. Если установлено одно значение (key + value) - возвращается прямое значение (примитив или объект как есть). Если установлена структура (values без key) - возвращается структура
- formatted_text (string) (опционально) — Отформатированный текст в формате YAML (возвращается только если format=true)

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "set_user_storage"
  params:
    tenant_id: 123
    user_id: 123
    # key: string (опционально)
    # value: any (опционально)
    # values: object (опционально)
    # format: boolean (опционально)

validator

Описание: Сервис для валидации условий в сценариях

validate

Описание: Валидация условия с возвратом результата

Входные параметры:

condition (string, обязательное, мин. длина: 1) — Условие для валидации (поддерживает все операторы condition_parser)

Выходные параметры:

result (string) — Результат: success, failed, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "validate"
  params:
    condition: "example"

📖 Дополнительная информация

Поддерживаемые операторы: ==, !=, >, <, >=, <=, in, not in, ~, !~, regex, is_null, not is_null

Плейсхолдеры:

✅ condition: "{_cache.storage_values.tenant_owner|exists} == True and {_cache.storage_values.tenant_owner|length} > 0"
✅ condition: "{_cache.storage_values.tenant_id} == 137"
✅ condition: "{_cache.storage_values.tenant_id} > 100"

Маркеры:

✅ condition: "$user_id > 100"
✅ condition: "$_cache.storage_values.tenant_owner not is_null"
✅ condition: "$event_type == 'message' and $user_id > 100"

🎯 Гайд по действиям ​

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

ai_rag_service ​

⭐ delete_embedding ​

⭐ get_recent_chunks ​

⭐ save_embedding ​

⭐ search_embedding ​

ai_service ​

completion ​

embedding ​

bot_hub ​

answer_callback_query ​

build_keyboard ​

delete_message ​

send_message ​

invoice_service ​

cancel_invoice ​

confirm_payment ​

create_invoice ​

get_invoice ​

get_user_invoices ​

mark_invoice_as_paid ​

reject_payment ​

scenario_helper ​

check_value_in_array ​

choose_from_array ​

format_data_to_text ​

generate_array ​

generate_int ​

generate_unique_id ​

modify_array ​

set_cache ​

sleep ​

scenario_processor ​

execute_scenario ​

wait_for_action ​

tenant_hub ​

delete_storage ​

get_storage ​

get_storage_groups ​

set_storage ​

user_hub ​

clear_user_state ​

delete_user_storage ​

get_tenant_users ​

get_user_state ​

get_user_storage ​

get_users_by_storage_value ​

set_user_state ​

set_user_storage ​

validator ​

validate ​

🎯 Гайд по действиям

📋 Содержание

ai_rag_service

⭐ delete_embedding

⭐ get_recent_chunks

⭐ save_embedding

⭐ search_embedding

ai_service

completion

embedding

bot_hub

answer_callback_query

build_keyboard

delete_message

send_message

invoice_service

cancel_invoice

confirm_payment

create_invoice

get_invoice

get_user_invoices

mark_invoice_as_paid

reject_payment

scenario_helper

check_value_in_array

choose_from_array

format_data_to_text

generate_array

generate_int

generate_unique_id

modify_array

set_cache

sleep

scenario_processor

execute_scenario

wait_for_action

tenant_hub

delete_storage

get_storage

get_storage_groups

set_storage

user_hub

clear_user_state

delete_user_storage

get_tenant_users

get_user_state

get_user_storage

get_users_by_storage_value

set_user_state

set_user_storage

validator

validate