Перейти к основному содержимому

Работа со сниппетами

Сниппет — это встроенный в платформу инструмент, позволяющий выполнять произвольный код на языке JavaScript в ответ на действия пользователя. Этот мощный механизм реакции предназначен для реализации сложной бизнес-логики и интеграции со сторонними сервисами.

Ключевые возможности​

С помощью сниппетов вы можете:

  • Взаимодействовать с внешними API — отправлять запросы на сторонние серверы для получения или отправки данных (например, для проверки статуса заказа, получения информации о погоде и т. д.).
  • Генерировать динамические ответы — формировать ответы пользователю на основе данных из контекста диалога, результатов вычислений или информации, полученной из внешних систем.
  • Реализовывать кастомную бизнес-логику — выполнять сложные вычисления, валидацию данных, форматирование и любые другие операции, необходимые для вашего сценария.

Ограничения и рекомендации по использованию​

Для обеспечения стабильности и производительности платформы на сниппеты наложены следующие ограничения:

  • Память: Объём оперативной памяти, доступной для одного сниппета, ограничен 128 МБ.
  • Время выполнения: Время выполнения сниппетов теперь настраивается как на уровне проекта, так и для каждого сниппета индивидуально.

Настройка таймаутов​

Платформа предоставляет гибкие возможности настройки времени выполнения сниппетов для оптимизации работы с медленными внешними системами.

Настройка таймаутов на уровне проекта

Где настроить: Настройки проекта → Таймауты

Параметры:

  • Значение по умолчанию: 30 секунд
  • Минимальное значение: 30 секунд
  • Максимальное значение: 3 минуты (180 секунд)
warning

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

  • Запросы к Лия API будут работать дольше стандартных 30 секунд
  • В интеграциях с внешними системами необходимо внести соответствующие изменения в настройки таймаутов
  • Увеличение таймаута влияет на общее время ответа пользователям
Настройка таймаутов для отдельных сниппетов

Где настроить: Страница редактирования сниппета → Настройки таймаута

Ограничения:

  • Таймаут сниппета не может превышать общий таймаут проекта
  • При планировании времени учитывайте, что в одном API-вызове Лии могут выполняться несколько сниппетов и других реакций и таймаут будут суммироваться, но сумма не должна превышать общий таймаут проекта
к сведению

Рекомендации по планированию времени:

  • Закладывайте дополнительное время на обработку других реакций и сниппетов в том же API-вызове
  • Для сниппетов, работающих с медленными CRM или внешними системами, устанавливайте таймаут с запасом
  • Тестируйте таймауты в debug-чате — они работают так же, как и в продакшене
к сведению

Рекомендации по оптимизации:

  • Умеренное количество сниппетов: Старайтесь минимизировать количество сниппетов в рамках одного сценария. Каждый сниппет, особенно тот, который выполняет запросы к внешним системам, увеличивает общее время ответа пользователю.
  • Обработка ошибок таймаута: Если сниппет не успевает выполниться за отведённое время, его выполнение принудительно прерывается, и сценарий переходит в ветку «Ошибка» (Fail).
  • Недопустимость пустых и закомментированных сниппетов: Критически важно избегать добавления в сценарий пустых сниппетов или сниппетов, в которых весь код закомментирован. Такие блоки могут привести к критической ошибке и остановке выполнения всего сценария.
warning

Критически важные правила выполнения:

  • Результат выполнения: Сниппет всегда возвращает либо успех, либо ошибку. Если в коде вы напишете функцию, которая вернет успех, но затем вызовете throw error или по какой-либо причине следующая функция упадет с ошибкой, которую вы не обработаете должным образом, сниппет вернет ошибку.
  • Пустая последняя строка: Последняя строка в сниппете не должна быть пустой. Это может вызвать ошибку исполнения всего сниппета.
  • Работа с параметрами контекста: При использовании параметров из контекста сначала присвойте их переменной, а затем используйте. Например: let param = context.param; core.sendText(param); вместо прямого вызова core.sendText(context.param).

Создание и интеграция в сценарий​

Создание сниппета​

  1. Перейдите в раздел «Сниппеты» в левом боковом меню.
  2. Нажмите кнопку «+ Добавить».
  3. В рабочей области появится шаблон асинхронной JavaScript-функции. Вся ваша логика должна быть реализована внутри этой функции.

Интеграция в сценарий​

  1. В нужном блоке сценария добавьте реакцию типа «Сниппет».
  2. Выберите один из ранее созданных сниппетов в панели настроек.
  3. Активируйте чекбокс «Ошибка», чтобы у блока появилась дополнительная ветка (Fail) для обработки потенциальных сбоев.
осторожно

Важно: В случае ошибки и перехода в ветку «Fail», projectStorage сохранит переменные, но факты, установленные в сниппете, не сохранятся в контексте и сгенерированные реакции не будут отправлены пользователю.

Взаимодействие с контекстом и отправка данных​

Работа с контекстом​

Вы можете управлять данными диалога, сохраняя и извлекая информацию из контекста.

Пример: Установка и использование фактов в тексте

Сначала в сниппете мы устанавливаем нужные факты с помощью context.set().

set-facts.js
async function snippet(core = new Core(), context = new Context()) {
    // Financial data configuration
    const balanceArray = [100, 200, 300];
    const currencies = ['USD', 'EUR', 'RUB'];

    // Client configuration
    const clientConfig = {
        type: 'vk',
        phone: 892512312312
    };

    // Set balance-related values
    context.set('balance', balanceArray);
    context.set('first_balance', balanceArray[0]);

    // Set client information
    context.set('client_type', clientConfig.type);
    context.set('phone', clientConfig.phone);

    // Set currency information
    context.set('currency', currencies);
}

Затем в блоке "Текст" вы можете использовать эти данные с помощью синтаксиса Mustache.

  • {{phone}} — для вывода простого значения.
  • {{{balance}}} — для вывода массива или объекта в формате JSON без экранирования спецсимволов.

Динамическая отправка сообщений​

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

Пример: Отправка текста и кнопок

Используйте core.sendText() для отправки текстовых сообщений и core.sendButtons() для отправки кнопок.

send-text-and-buttons.js
async function snippet(core = new Core(), context = new Context()) {
    const dynamicText = "Это динамический текст из сниппета.";
    
    // Пример отправки текстовой строки
    core.sendText(dynamicText);

    // Пример отправки кнопок
    core.sendButtons('Вы согласны с условиями?', [
        {type: 'text', title: 'Да', params: {text: 'Я согласен'}},
        {type: 'text', title: 'Нет', params: {text: 'Я не согласен'}},
    ]);
}

Правильная работа с параметрами контекста:

context-params.js
async function snippet(core = new Core(), context = new Context()) {
    // ❌ НЕПРАВИЛЬНО - прямое использование параметра
    // core.sendText(context.param);
    
    // ✅ ПРАВИЛЬНО - сначала присваиваем переменной
    let param = context.param;
    core.sendText(param);
    
    // Или для более сложных случаев
    let userMessage = context.get('user_input');
    let responseText = `Вы сказали: ${userMessage}`;
    core.sendText(responseText);
}
к сведению

Выбор между установкой фактов в контекст и прямой отправкой через core.sendText() зависит от логики вашего сценария и предпочтений команды. Оба подхода являются корректными.

Встроенные библиотеки​

Для вашего удобства в окружение сниппетов предустановлены популярные JS-библиотеки: moment.js, request, axios.

Готовые шаблоны​

Мы подготовили шаблоны с часто используемыми методами, которые можно перетаскивать прямо в редактор кода (методы запросов, работа с контекстом и т. д.).

Хранилище проекта (projectStorage)​

projectStorage — это инструмент для хранения временных данных на уровне всего проекта (кеширование, временные токены). Данные в projectStorage доступны из любого сниппета для всех пользователей вашего проекта.

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

Тестирование и отладка​

Для проверки базовой логики сниппета вне сценария используйте кнопку «Run» под редактором кода. Результат выполнения будет отображаться в консоли.

Тестирование с контекстом​

Если сниппет использует данные из контекста, его запуск вне сценария вызовет ошибку. Для полноценного тестирования необходимо симулировать контекст:

  1. Под тестовым чатом найдите кнопку «Факты».
  2. Задайте необходимые факты в формате JSON-объекта.
  3. Запустите сниппет — он получит доступ к заданным данным.
warning

Важно: После завершения тестирования не забудьте очистить поле «Факты», оставив в нём пустой объект {}.