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

установитьПеременную(*переменная, *значение)

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

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

установитьПеременнуюВДиалог(*args)

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

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

Для указания переменной диалога необходимо указать следующие поля:

• ключ - название переменной, обязательное поле

• значение - значение переменной, может быть заполнено или изменено позднее

• название - название переменной для ее отображения в боковой панели оператора и истории диалога

• показыватьОператору - при установке поля в true переменная и ее значение отображаются в боковой панели оператора и истории чата

• редактируемое - при установке поля в true оператор имеет возможность изменять значение переменной непосредственно в боковой панели

• обязательное - при установке поля в true сервис AutoFAQ будет требовать заполнение переменной оператором перед закрытием диалога

• тип - тип переменной, список возможных типов см ниже

• множественныйВыбор - при установке поля в true для типа переменной “Выпадающий список“ устанавливается возможность множественного выбора элементов

• варианты - список возможных вариантов для переменной типа "Выпадающий список" в сеаризованном формате ключ-значение. Поддерживается многоуровневый список вариантов, а так же передача списка вариантов через переменную.

Список возможных типов с примерами использования:

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

установитьПеременнуюПользователю(*переменная, *значение)

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

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

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

получитьПеременнуюСервиса(*args)

Шаг получения текущего значения переменной сервиса.

Здесь можно подробно ознакомиться с переменными сервиса https://deephack.atlassian.net/wiki/spaces/AKB/pages/3352657922

получитьПеременнуюСервиса("имя_переменной_сервиса", "имя_переменной_куда_сохранять")

изменитьПеременнуюСервиса(*args)

Шаг изменения значения переменной сервиса.

Здесь можно подробно ознакомиться с переменными сервиса https://deephack.atlassian.net/wiki/spaces/AKB/pages/3352657922

изменитьПеременнуюСервиса("имя_переменной_сервиса", "значение_или_имя_переменной_откуда_записать")

Переписка с пользователями 

сообщениеПользователю.сШаблоном(*сообщение)  

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

Текст сообщения может содержать HTML теги для форматирования сообщения. Текст сообщения также может включать в себя вставку значений из переменных. Система самостоятельно проверит форматирование сообщения на соответствие требованиям канала. 

Пример вывода простого текстового сообщения:

Пример вывода текстового сообщения с переменой:

Пример вывода текстового сообщения с HTML форматированием ссылки:

.сФайлами(*файлы)

Модификатор шага, который позволяет отправить пользователю вместе с сообщением файлы из текущего документа. В качестве аргумента принимаетя список идентификаторов файлов в документе.

Идентификатор файла копируется из формы прикладывания файла к документу.

Open

задатьПользователюВопрос(*сообщение).сохранитьРезультат(*переменная)  

Шаг отправки пользователю вопроса пользователю и ожидания ответа.

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

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

Пример простого вопроса пользователю:

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

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

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

.сВариантамиОтвета(*варианты) 

Модификатор шага отправляет пользователю вместе с вопросом готовые варианты ответа. В случае если текущий пользовательский канал позволяет отображать кнопки - варианты будет представлены кнопками, в противном случае варианты будут представлены автоматически сгенерированным списком с номерами вариантов. В любом случае пользователь может выбрать вариант отправив в ответном сообщении его номер или может написать свой ответ вручную минуя варианты выбора.

Есть возможность передать сразу список кнопок без необходимости перечисления каждой отдельно. Обработка результатов выбора осуществляется как обычно. Пример передачи списка кнопок ниже:

.проверитьФормат(*формат, *сообщение)

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

запроситьФайл(*сообщение).сохранитьРезультат(*переменная)

Шаг запроса файла  у пользователя и записи его в переменную. В качестве аргумента шаг принимает текст просьбы или переменную с таким текстом. Файл будет сохранен в хранилище файлов диалога и будет доступен в указанной переменной.

Модификатор шага добавляет пользователю опцию пропуска отправки файла.

.можноПропустить(*сообщение)

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

Работа с API вызовами  

Шаги обращения к внешним сервисам и разбора полученных данных. В настоящее время поддерживается API вызовы REST и SOAP сервисов, планируется подключение к почтовым, FTP и прочим сервисам.

вызвать.внешнийСервис(*адрес, *тип).сохранитьРезультат(*args)

Шаг вызова REST API сервисов. Данный шаг ожидает получение ответа в формате плоского JSON. Для работы с SOAP сервисами используется данный шаг с модификаторам, которые будут указаны ниже.

В качестве аргументов для вызвать.внешнийСервис принимаются адрес ендпонта и тип вызова. Поддерживаются основные типы вызовов - GET, POST, PUT, DELETE. В качестве адреса ендпойнта принимается строка с адресом или переменная, которая содержит данную строку.

В качестве аргументов для сохранитьРезультат принимается список пар из названия поля в полученном JSON и названия переменной, в которую сценарий сохранит полученное значение.

Пример GET запроса, из ответа которого будет выбрано 1 поле result

Пример POST запроса с указанием адреса вызова из переменной, телом запроса и разбором двух полей из ответа - message и code

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

.сПараметрами(*args)

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

.сЗаголовками(*args)

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

.сТеломСообщения(*args)

Модификатор шага вызова сервиса для передачи тела запроса.

Поддерживаются форматы x-www-form-urlencoded и json. JSON передается кодированный в строку. Названия и значения параметров принимаются строкой или переменной, которая содержит эту строку.

Асинхронные API вызовы

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

Модификатор шага .получитьАдресВебхука для получения адреса вебхука в диалоге.

Модификатор шага .выставитьВебхук(limit) для выставления вебхука и ожидания поступления вызова от другого сервиса, где limit это время ожидание ответа в секундах. Используется вместе с модификатором .сохранитьРезультатКакСтроку()

.сСоставнымТеломСообщения(*args)

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

.сохранитьРезультатКакСтроку(*переменная)

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

Ответ может быть разобран далее по ходу сценария.

Сервисные шаги

если(*условие).то(*операции) 

Шаг условного выполнения операций. В качестве условия указывается сравнение двух значений. Для оценки условия доступны операции сравнения - равенство (==), больше (>), меньше (<), неравенство (!=). В качестве сравниваемых значений можно указывать переменные сценарий, текст или числа.

Пример сообщения, отправляемого пользователю при равенстве переменной error единице.

Блок операций может состоять из нескольких шагов. В этом случае различные шаги в блоке должны быть соединены знаком “+”, но последний шаг в блоке не должен содержать “+“

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

.иначе(*операции)

Модификатор шага, содержащий блок операций, которые будут выполнятся, если условие не будет соблюдено

.и(*условие)

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

.или(*условие) - 

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

установитьМетку(*название)

Шаг установки метки в коде сценария. Метка используется для перехода из любого места сценария.

перейтиНаМетку(*метка)

Шаг перехода на установленную в коде сценария метку.

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

.неБольше(*количество)

Модификатор для установки лимита по количеству переходов. При достижении лимита сценарий не перейдет на метку, а продожит работу далее по коду.

комментарий(*сообщение)

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

выполнитьJs(*скрипт)

Шаг выполнения скрипта на JavaScript. Шаг позволяет реализовать произвольную логику вычислений или разбор сложных объектов. В качестве аргумента шаг принимает текст JS скрипта.

JS скрипт имеет доступ ко всем переменным сценария. Результаты скрипта следует записать в JSON объект и передать его на выход, в DSL сценарии можно будет получить к ним доступ по названиям полей.

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

Внутри JavaScript есть возможность получить данные об операторе для случая, когда запущен сценарий на интеграцию по кнопке. Название объекта - initByOperator.

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

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

id: String, login: String, fullName: Option[String], isActive: Boolean, isNotify: Boolean, serviceId: String, actions: Seq[UserRoleType], email: Option[String], settings: UserSettings = UserSettings()

knowledgeBases: Seq[Long] = Seq.empty, autoAssignEnabled: Boolean = false

Также есть доступ к библиотеке crypto-js и подготовлена готовая функции encode для генерации JWT токенов:

Управление диалогом

запросВБазыЗнаний(*args)

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

Если в базах знаний есть ответ, который удовлетворяет требованиям по точности, переменной будет присвоено значение true, если ответа нет - false.

назначитьТематику(*идентификатор)

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

Получить идентификатор базы знаний можно из списка баз знаний в разделе Базы знаний или из карточки само базы знаний.

Open

Идентификатор базы знаний в интерфейсе

назначитьОператора(*логин)

Шаг указания оператора для диалога. В качестве аргумента шаг принимает логин оператора.

При попадании такого диалога в процедуру перевода диалога на оператора система в первую очередь попытается назначить диалог на оператора с указанным логином. Если такой оператор существует и удовлетворяет всем требованиям назначения - система назначит диалог на данного оператора. Если оператора с таким логином не существует или он не удовлетворяет требованиям автоназначения система проведет назначение на другого оператора по стандартным правилам.

Генерация форм для операторов

При работе оператора над диалогом система позволяет вывести для оператора форму сбора данных.

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

добавитьПолеВФормуОператора(*args)

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

Пример добавления текстового поля на форму:

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

• Нередактируемый текст - вывод нередактируемого текстового сооющения на форме

• Однострочный редактируемый текст - вывод однострочного поля для ввода

• Многострочный редактируемый текст - вывод многострочного поля для ввода

• Целое число - вывод поля для ввода целого числа

• Выпадающий список - вывод поля для выбора одного значения из выпадающего списка

• Множественный выбор - вывод поля для выбора нескольких значений из выпадающего списка

• Переключатель - вывод переключателя, который сохранит булево значение true или false

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

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

показатьФормуОператору(имя = "форма")

Шаг отображения формы оператора. Шаг отобразит форму со всеми установленными ранее полями. Сценарий отобразит форму и будет ожидать пока оператор не нажмет на форме кнопку “Отмена” или “Продолжить”. После нажатия кнопки “Отмена” сценарий прекратит свою работу. После нажатия кнопки “Продолжить” сценарий продолжит свою работу со следующего шага. Все заполненные поля будут доступны в сценарии по имени переменной.

Работа с группами диалога

определитьИдентификаторГруппы(*переменная)

Шаг определения текущей группы диалога. В качестве аргумента шаг принимает название переменной куда будет установлен текстовый идентификатор текущей группы диалога.

перевестиНаГруппу(*идентификатор).иЗавершить

Шаг завершения текущего сценария, перевода диалога на другую группу. Шаг совмещает смену группы и завершение текущего сценария в одном. В качестве аргумента шаг принимает идентификатор группы, в которую надо перевести диалог. Идентификатор каждой группы можно выяснить в разделе Настройки - Группы. Если в сервисе не будет обнаружено группы с таким идентификатором, то перевод на группу будет проигнорирован.

После смены группы диалог продолжит работу в зависимости от места выполнения шага:

• если смена группы произошла в сценарии поступления диалога в систему, то после завершения сценария диалог запустит приветствие данной группы, а после переведет запрос в базы знаний;

• если смена группы произошла в сценарии приветствия, то после завершения сценария диалог передаст запрос в базы знаний;

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

перевестиНаГруппу(*идентификатор).иЗавершитьСНовымЗапросом(*запрос)

Шаг завершения текущего сценария, перевода диалога на другую группу и передачи запроса в базы знаний этой группы вне зависимости от того где был использован данный шаг. Шаг совмещает смену группы и завершение текущего сценария в одном.

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

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

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

перевестиНаГруппу(*идентификатор).иЗавершитьИПеревестиНаОператора

Шаг завершения текущего сценария, перевода диалога на указанную группу и передачи диалога операторам этой группы вне зависимости от того где был использован данный шаг. Шаг совмещает смену группы и завершение текущего сценария в одном.

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

По результатам выполнения данного шага диалог будет передан в указанную группу и назначен на операторов этой группы.

Шаги завершения сценария

завершить

Шаг завершения сценария. По результатам выполнения этого шага текущий сценарий будет завершен. После завершения сценария диалог продолжит работу в зависимости от места выполнения шага:

• если завершен сценарий при поступлении диалога в систему, то диалог будет переведен в приветствие, а после него диалог передаст запрос в базы знаний и болталку;

• если завершен сценарий приветствия, то диалог передаст запрос в базы знаний и болталку;

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

завершитьСНовымЗапросом("вопрос")

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

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

завершитьИПеревестиНаОператора

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

завершитьИЗакрытьДиалог()

Шаг завершения текущего сценария и закрытия всего диалога. Следующая реплика пользователя создаст новый диалог.

В данном шаге закрытия диалога есть возможность отключить сбор оценки, используя опцию “отключитьОценку = true”: