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

Сниппеты: Расширение функциональности с помощью JavaScript

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

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

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

• Взаимодействовать с внешними API: Отправлять запросы на сторонние серверы для получения или отправки данных (например, для проверки статуса заказа, получения информации о погоде и т.д.).

• Генерировать динамические ответы: Формировать ответы пользователю на основе данных из контекста диалога, результатов вычислений или информации, полученной из внешних систем.

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

---

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

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

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

• Время выполнения: Максимальное время выполнения одного сниппета составляет 5 секунд.

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

• Умеренное количество сниппетов: Старайтесь минимизировать количество сниппетов в рамках одного сценария. Каждый сниппет, особенно тот, который выполняет запросы к внешним системам, увеличивает общее время ответа пользователю.

• Обработка ошибок таймаута: Если сниппет не успевает выполниться за отведённые 5 секунд, его выполнение принудительно прерывается, и сценарий переходит в ветку «Ошибка» (Fail).

• Недопустимость пустых и закомментированных сниппетов: Критически важно избегать добавления в сценарий пустых сниппетов или сниппетов, в которых весь код закомментирован. Такие блоки могут привести к критической ошибке и остановке выполнения всего сценария.

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

• Результат выполнения: Сниппет всегда возвращает либо успех, либо ошибку. Если в коде вы напишете функцию, которая вернет успех, но затем вызовете 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().

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: [phone]
    };

    // 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() для отправки кнопок.

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: 'Я не согласен'}},
    ]);
}

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

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. Запустите сниппет — он получит доступ к заданным данным.

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