Общее описание сценариев

Сценарии позволяют описывать последовательность диалога autoFAQ с пользователями. Диалог может включать в себя переписку бота с пользователями, получение и сохранение данных во внешних системах и шаги по обработке информации.

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

Сценарии могут быть подключены к документам в базе знаний или к событиям в диалогах (интеграции). В первом случае AutoFAQ запустит сценарий если по запросу пользователя будет найден документ - вместо текстового ответа сервис начнет переписку с пользователем по полученному сценарию. Во втором случае AutoFAQ запустит сценарий если в диалоге произойдет указанное событие - в этом случае сервис приостановит обработку диалога, выполнит сценарий и после продолжит работу над диалогом.

Описание сценариев в системе ведется при помощи языка DSL AutoFAQ. Текст сценария состоит из последовательных операций (шагов).

Для открытия окна редактирования сценария в полноэкранном режиме необходимо нажать клавишу “F11”. Для выхода из полноэкранного режима необходимо нажать “F11” или “Esc”.

В окне редактирования сценария можно вызывать подсказки по шагам сценариев комбинацией клавиш “Ctrl+Пробел”.

Описание языка DSL AutoFAQ

Последовательность шагов

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

сообщениеПользователю("Спасибо, данные получил!") +
комментарий("Данные пользователя обновлены, завершаю работу") +
завершить

Шаги могут иметь модификаторы, которые уточняют поведение шага. Модификатор шага указывается через точку, например:

задатьПользователюВопрос("Я правильно понял, что вы заблудились в лесу?")
    .сохранитьРезультат("answer") +

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

если("{what} == да").то(
   задатьПользователюВопрос("Укажи нужное время").сохранитьРезультат("time")   
).иначе(
   сообщениеПользователю("Ну и ладно")
) +

DSL AutoFAQ поддерживает использование переменных в шагах. Для использования значения переменной надо указать имя переменной переменной в фигурных скобках {...}, например:

сообщениеПользователю("Получил сообщение {userSaid}") +

Кроме того в коде сценария поддерживается использование комментариев. Для оформления комментария строка должна начинаться с символа //. Строка, начинающаяся с // выполняться не будет.

// передача файла через идентификатор файла в хранилище
вызвать.внешнийСервис("{url}","POST").сТеломСообщения("{query}").сохранитьРезультат() +
// уведомляю пользователя
сообщениеПользователю("Зарегистрировал обращение") +
// комментарий("Все готово") +
завершить

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

завершить - простое завершение сценария, диалог остается в работе у бота;
завершитьСНовымЗапросом() - завершение сценария и эмуляция получения нового запроса от пользователя;
завершитьИПеревестиНаОператора - завершение сценария и принудительный перевод диалога в очередь операторам;
завершитьИЗакрытьДиалог() - завершение сценария и принудительное закрытие диалога.

Если в шаге сценария применен один из шагов завершения, то сценарий может завершить свою работу досрочно, например:

если("{http_code} != 200").то(
  комментарий("Данные пользователя не обновлены") +
  завершить 
)+
комментарий("Обовлены данные пользователя. Новые данные отправлены в CRM") +
завершить

Переменные в сценариях

Для хранения данных в сценариях возможно создавать переменные 4-х типов:

переменные сценария;
переменные диалога;
переменные пользователя;
переменные сервиса.

Ко всем переменным можно обратиться через указание названия переменной в обрамлении фигурными скобками {userSaid}, например:

сообщениеПользователю("Получил сообщение {userSaid}") +

Любая переменная может быть создана или изменена в любом сценарии - в сценарии документа либо в сценарии интеграции на событие.

Переменные сценария

Значение переменной сценария сохраняется только в рамках текущего сценария и будет потеряно после завершения сценария. Подходят для передачи информации между шагами одного сценария.

задатьПользователюВопрос("Как дела?").сохранитьРезультат("answer") +
если("{answer} == Хорошо").то(
    комментарий("Пользователь сказал что дела хорошо")
) +
завершить

Переменные диалога

Значение переменной диалога будет доступно в любом сценарии в рамках текущего диалога, включая все сценарии из документов и интеграций. Переменная может быть определена в момент создания диалога, заполнена в течение опроса пользователя и использована для передачи информации в CRM систему в момент завершения диалога.

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

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

Значение переменной пользователя сохраняется в профиле пользователя и доступно во всех диалогах этого пользователя. Переменные пользователя делятся на основные и дополнительные. Основные переменные - это ФИО пользователя, электронная почта, телефон и логин. Список дополнительных переменных пользователя может быть произвольным и определяется логикой сценариев. Все переменные пользователя отображаются на информационной панели оператора и в истории запросов.

Если значение переменной пользователя поменяется, то это отразится на всех диалогах с этим пользователем, включая уже завершенные.

Переменные сервиса

Особенный тип переменных, которые не могут быть созданы в рамках сценария. Переменные сервиса доступны во всех сценариях всего сервиса. Их может создать администратор сервиса только через UI в настройках сервиса.

Сценарии могут получить значение переменной или изменить его. Значение переменных сервиса не выводится в информационной панели оператора.

Встроенные переменные

Встроенные переменные содержат общие данные контекста диалога - данные о пользователе, канале перписки и данные самого диалога. Данные переменные доступны с самого начала в любом сценарии, их не надо создавать.

Переменные с контекстом диалога:

serviceId - идентификатор сервиса;

channelId - идентификатор канала, через который ведется переписка;

channelType - тип канала (Telegram, WhatsApp, Widget);

conversationId - идентификатор текущего диалога;

platformInMessageQuery - текст первоначального запроса пользователя, по которому был создан входящий диалог с AutoFAQ;

conversation - объект, который хранит все данные диалога включая данные о пользователе, список всех реплик и событий;

externalFiles - список файлов переданных пользователю или полученных от него в рамках текущего диалога.

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

userFullName - имя пользователя;
userLogin - логин пользователя;
userEmail - электронная почта пользователя;
userPhone - номер телефона пользователя;
userId - идентификатор пользователя;
userPayload.* - хранилище дополнительных данных о пользователе.

Прочие встроенные переменные

http_code - код статуса последнего шага API запроса;
telegram_message - полный набор информации о пользователе Telegram, содержит в себе локации пользователя, если он ей поделится с ботом

Данные контекста диалога заполнены всегда. Данные пользователя будут заполнены в зависимости от типа канала, так как каждый тип канала передает свой набор данных о пользователе. Данные о пользователе могут быть пополнены в результате работы модуля Идентификация, в рамках переписки с пользователем или через запрос к данным внешнего сервиса.

Справочник шагов сценария

Полный справочник шагов описан в разделе Справочник шагов сценария

Примеры готовых сценариев доступны в разделе Примеры сценариев

Проверка синтаксиса сценария

На странице документа базы знаний есть кнопка “Проверить сценарий”, которая запускает синтаксическую проверку указанного сценария.

f95dfd5b-cd86-40f1-80a4-5ec780736d0c-20240301-184643.png

Если в сценарии найдены ошибки, тогда открывается модальное окно с перечислением найденных ошибок. Синтаксический анализатор имеет ряд ограничений при описании найденных ошибок - не всегда имеется возможность указать номер строки, не все типы ошибок снабжены русским описанием.