Действия и хуки

Когда готовых звеньев и навыков не хватает, в сценарий добавляется действие: небольшой скрипт на JavaScript, который выполняется в изолированной среде на сервере. Платформа поставляет набор действий для типовых задач, собственные пишутся в разделе «Редактор кода».

Где выполняются действия

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

• При входе (onEnter) — выполняется, когда диалог приходит в звено, до того как бот покажет содержимое и начнёт ждать ответ. Здесь обычно запоминают данные, вызывают внешние системы, готовят текст ответа.
• При получении (onReceive) — выполняется, когда клиент ответил на вопрос этого звена, перед проверкой переходов. Здесь разбирают ответ: сохраняют введённое значение, проверяют его, ставят temp.valid.

Действия в списке выполняются по порядку; содержимое звена (тексты, кнопки) показывается между «При входе» и ожиданием ответа. Действие добавляется кнопкой «+» в инспекторе: в окне выбора видны название, категория и описание каждого действия, а под списком есть ссылка «Создать новый скрипт в редакторе кода».

Встроенные действия

Действие	Что делает
Задать переменную	Записывает значение в temp, session, user или bot; потом его подставляют в тексты как {{хранилище.имя}} и проверяют в переходах
Удалить переменную	Убирает переменную из хранилища (у bot значение становится null)
Задать глобальную переменную, Получить глобальную переменную, Сбросить глобальную переменную	Переменные, общие для всех клиентов бота, со сроком хранения (never, 30m, 1d); «Получить» копирует значение в temp
Сбросить сессию	Очищает temp и session клиента; контексты NLU и история сообщений остаются
Добавить контекст, Убрать контекст, Сбросить контекст	Управляют контекстами NLU: какие намерения рассматриваются для следующих сообщений и сколько ходов это действует, см. «Сущности, слоты и контексты»
Сменить язык	Записывает код языка в user.language: дальше бот отвечает содержимым на этом языке
Пауза	Задержка в миллисекундах перед следующим шагом, чтобы ответы приходили не мгновенно
Увеличить число диалогов, Получить число диалогов	Счётчик разговоров клиента; помогает по-разному встречать нового и постоянного клиента
Сохранить файл	Копирует присланный клиентом файл в хранилище платформы и подменяет временную ссылку мессенджера постоянной
Отправить оценку	Записывает оценку ответа (1 или −1) в аналитику; идентификатор оценённого сообщения берётся из temp.eventId
Пометить как непонятое	Отправляет фразу клиента в отчёт «Непонятые фразы» из сценария (модуль «Непонятые фразы»)

Действия навыков (basic-skills/call_api, basic-skills/call_gpt и другие) скрыты из списка: они добавляются только через навыки.

Собственное действие

1. Откройте «Редактор кода», нажмите «+» в разделе «Действия» бота (или откройте его из окна выбора действия). Появится шаблон с описанием, которое показывается в окне выбора действия: заполните @title (название), @category и список параметров @param.
2. Напишите код. Доступны:
   • event — текущее событие диалога, см. «Событие диалога»; event.preview текст клиента, event.state.temp и короткие имена temp, session, user, bot — переменные;
   • args — параметры, заданные в настройках звена (args.name); в их значениях работают шаблоны {{...}};
   • iqbot — SDK платформы: iqbot.logger.forBot(event.botId).info(...), iqbot.events.replyToEvent(event, [{ type: 'text', text: '...' }]), iqbot.cms.renderElement(...), iqbot.kvs.forBot(event.botId).set/get(...), iqbot.dialog.getHistory(event, { count: 10 });
   • axios для HTTP-запросов, _ (lodash), moment;
   • переменные окружения сервера только с префиксом EXPOSED_: process.env.EXPOSED_CRM_TOKEN. Так ключи внешних систем не попадают в содержимое бота и в архивы.
3. Сохраните файл: действие сразу появляется в окне выбора, перезапуск не нужен.

Пример: действие, которое запрашивает баланс и готовит переход «Успех / Ошибка».

/**
 * Запрашивает остаток по карте в ДБО и кладёт его в temp.balance.
 * @title Запросить баланс
 * @category Банк
 * @param {string} last4 - Последние 4 цифры карты
 */
const getBalance = async last4 => {
  try {
    const { data } = await axios.get(`https://dbo.bank.local/cards/${last4}/balance`, {
      headers: { Authorization: `Bearer ${process.env.EXPOSED_DBO_TOKEN}` },
      timeout: 3000
    })
    temp.balance = data.balance
    temp.valid = true
  } catch (err) {
    iqbot.logger.forBot(event.botId).warn(`Баланс не получен: ${err.message}`)
    temp.valid = false
  }
}

return getBalance(args.last4)

Что важно знать:

• Действие выполняется в песочнице с тайм-аутом; долгие операции прерываются. Нельзя читать файлы сервера и обращаться к модулям Node.js, кроме разрешённых.
• Действия бота лежат в его папке actions/ и переносятся вместе с ботом (экспорт, ревизии). Глобальные действия (раздел «Глобальные» редактора) общие для всех ботов: правка затрагивает все боты рабочего пространства.
• Ошибка в действии не роняет бота: диалог переходит в процесс «Ошибка», см. «Тайм-ауты и ошибки».
• Отлаживайте через «Панель отладки» Studio (вкладка «Журнал») и iqbot.logger.

Хуки

Хук это скрипт, который выполняется не в звене, а в определённый момент жизни бота или сообщения. Хуки лежат в папке hooks/<момент>/ бота (или глобально) и создаются в «Редакторе кода» в разделе «Хуки».

Папка	Когда выполняется	Для чего
before_incoming_middleware	Сообщение клиента только пришло, NLU ещё не работал	Нормализовать текст, отбросить служебные сообщения, записать канал
after_incoming_middleware	NLU отработал, диалог ещё не продолжен	Своя логика выбора процесса, обогащение event.state данными из внешней системы
before_outgoing_middleware	Бот отвечает, ответ ещё не отправлен	Изменить или дополнить ответ, добавить подпись
after_event_processed	Сообщение обработано полностью	Статистика, отправка событий во внешние системы
before_session_timeout	Сессия клиента вот-вот истечёт	Попрощаться, сохранить незавершённую заявку
before_conversation_end	Диалог завершается	Запросить оценку
before_suggestions_election	Платформа выбирает между ответом процесса, QnA и ИИ-агентом	Своё правило выбора ответа
after_bot_mount, after_bot_unmount	Бот запущен или остановлен на узле	Подготовить кэш, предупредить внешнюю систему
after_server_start	Платформа запустилась	Глобальные настройки
before_bot_import	Импортируется архив бота	Проверить или поправить содержимое архива
on_bot_error	В боте накопились ошибки (botMonitoring)	Оповестить дежурного

В хуке доступны iqbot и event (для хуков, связанных с сообщением). Хуки выполняются для каждого сообщения, поэтому держите их короткими и без тяжёлых запросов.