Робот класса JsonRobotLogic

Робот класса JsonRobotLogic — это простой сценарный бот, действующий как конечный автомат, находящийся всегда в одном из заранее определенных состояний и переключающийся между ними в соответствии с изначально сформулированными условиями и ответами клиента. Описание логики такого робота помещается в текстовый конфигурационный файл формата JSON. Интеграции с какими-либо внешними относительно Webim Server системами не требуется. Эта опция присутствует в версиях Webim 9.1-9.2.

Обратите внимание!

Начиная с версии 10.0 данный бот был заменён более совершенным сценарным ботом (ScenarioRobotLogic).

Для создания бота и его настройки есть интерфейс в разделе Боты Панели управления, если при добавлении бота выбрать тип Кнопочное меню.

Чтобы создать и подключить робота класса JsonRobotLogic, следуйте инструкциям ниже.

Принцип работы бота

Текущее состояние при диалоге с роботом хранится в объекте чата в поле external_data с ключом 'json_robot_current_state'. При назначении чата на робота (производится только в том случае, если логика робота в дескрипторе была описана верно) робот устанавливает в качестве текущего состояние "start", далее выполняются связанные с ним действия(actions) и выводятся возможные переходы(steps). При переходе к новому состоянию тут же выполняются actions, которые связаны с текущим состоянием, затем выводится список возможных steps, которые можно осуществить, а также ключевых слов, которые нужно вводить для осуществления перехода.

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

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

Если пользователь пишет что-то непонятное вместо ключевых слов, возникает ошибка "unrecognized_response" и выполняются связанные с ней actions.

При откреплении чата от робота в объекте чата полю external_data с ключом 'json_robot_current_state' присваивается значение None.

Пример реального JSON-бота (с изменёнными названиями) Вы можете скачать здесь.

Структура конфигурационного файла

JSON-файл, используемый роботом, должен иметь определенный формат:

{  
   "states": {  
      "start": State,
      "state1": State,
      ...
   },
   "errors": {  
      "unrecognized_response": Error,
      "error1": Error,
      ...
   },
   "general_properties": {  
      "steps_header": String,
      "steps_template": String,
      "message_if_no_operators_online": String
   }
}

Название параметра	Тип	Пример	Описание
`states`	`Dictionary`	`{"start": State, "first": State, "second": State}`	Словарь, содержащий объекты типа `State` (состояния).
`start`	`State`	См. описание типа	Первый объект типа `State`, обязателен.
`state1`	`State`	См. описание типа	Объект типа `State`.
`errors`	`Dictionary`	`{ "unrecognized_response": Error, "one_more_error": Error }`	Словарь, содержащий объекты типа `Error` (штатные ошибки).
`unrecognized_response`	`Error`	См. описание типа	Первый объект типа `Error`, обязателен.
`error1`	`Error`	См. описание типа	Объект типа `Error`.
`general_properties`	`Dictionary`	`{ "steps_header":"Введите цифру одного из пунктов меню:", "steps_template":"{0} - {1}n", "message_if_no_operators_online":"К сожалению, сейчас нет операторов онлайн. Пожалуйста, обратитесь в рабочее время с 09:00 до 22:00" }`	Опциональный блок, содержащий различные настройки робота, не относящиеся к состояниям или ошибкам.
`steps_header`	`String`	`"Введите цифру одного из пунктов меню:"`	Опционально. Текст, выводящийся перед перечислением состояний, в которые можно перейти.
`steps_template`	`String`	`"{0} - {1}n"`	Опционально. Описывает формат вывода состояний, в которые можно перейти. Должен дважды содержать `{}`.
`message_if_no_operators_online`	`String`	`"К сожалению, сейчас нет операторов онлайн."`	Опционально. Текст, выводящийся при отсутствии операторов онлайн.

State

Состояние (вершина графа) описывает текущее состояние робота: его название, действия, шаги в другие состояния.

Формат:

{  
   "title": String,
   "actions": [  
      action1,
      ...
   ],
   "steps": [  
      step1,
      ...
   ]
}

Название параметра	Тип	Пример	Описание
`title`	`String`	`"Вернуться в главное меню"`	Заголовок состояния. Отображается в списке возможных переходов к другим состояниям.
`actions`	`List`	`[action1,...]`	Список (массив), содержащий объекты типа `Action` (действия).
`action1`	`Action`	См. описание типа	Объект типа `Action`.
`steps`	`List`	`[step1,...]`	Список (массив), содержащий объекты типа `Step` (переходы).
`step1`	`Step`	описание типа	Объект типа `Step`.

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

Обязательно описывается состояние "start"— с этого состояния начинается любой диалог с роботом.

Action

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

Формат:

{  
   "type": String,
   "parameters": {
      "parameter1": String,
      ...
   }
}

Название параметра	Тип	Пример	Описание
`type`	`String`	`"send_message"`	Тип действия (по нему выбирается метод, который будет вызываться). В настоящее время доступны два типа: `"send_message"` (отправляет сообщение) и `"redirect_to_queue"` (переводит обращение в очередь операторов).
`parameters`	`Dictionary`	`{"text":"Ваше обращение будет перенаправлено на оператора"}`	Словарь, содержащий имена и значения параметров.
`parameter1`	`String`	`"Ваше обращение будет перенаправлено на оператора"`	Параметр.

При необходимости добавления новых методов для новых, еще не реализованных actions, в класс JsonRobotLogic следует добавить метод вида:

def on_action_ACTION_NAME(self, parameter1, ...):
    ...

Название параметра	Тип	Пример	Описание
`ACTION_NAME`	`String`	"send_message"	Название `action` (уникальное)

Step

Описывает возможный переход от текущего состояния к другому состоянию.

Формат:

{  
   "keyword": String,
   "step_id": String
}

Название параметра	Тип	Пример	Описание
`keyword`	`String`	`"1"`	Ключевое слово, которое нужно ввести пользователю для перехода.
`step_id`	`String`	`"32"`	`Title` состояния, к которому ведет переход.

Error

Штатная ошибка при общении с роботом. При ее возникновении выполняются связанные с ней action.

Формат:

{  
   "actions":[  
      "action1",
      ...
   ]
}

Название параметра	Тип	Пример	Описание
`actions`	`List`	`[action1,...]`	Список (массив), содержащий объекты типа `Action` (действия), которые будут выполнены при возникновении этой ошибки.
`action1`	`Action`	См. описание типа	Объект типа `Action`.

Обязательно должна быть описана ошибка "unrecognized_response" — возникает в случае, когда визитор не ввел ключевое слово, а ввел что-то непонятное. Другие ошибки пока не реализованы, но если возникнет такая необходимость, их можно будет добавить.

Инструкция по настройке

После того как JSON-файл готов, нужно создать учётную запись оператора, под которой будет функционировать бот. Как это сделать, можно прочесть здесь. Затем нужно указать ID оператора в системе Webim. Определить его можно двумя путями:

Запросить список операторов через API.
Открыть профиль этого оператора и скопировать его id в системе — число в конце URL-адреса открытой страницы. К примеру, если профиль оператора находится по адресу https://test.webim.ru/operator/operator.php?operatorid=123456, то нужно взять именно число 123456.

Далее Ваши действия зависят от сетевой конфигурации. Если у Вас облачная конфигурация (в большинстве случаев это так), то Вам нужно прислать файл в нашу поддержку через чат или по e-mail (support@webim.ru), также сообщив id оператора.

Если же у Вас локальная конфигурация, следует выполнить ещё несколько шагов (если на каком-либо этапе у Вас возникнут затруднения, следует обратиться к Вашему системному администратору):

Воспользуйтесь нашим скриптом, который осуществляет глубокую проверку добавляемого JSON-файла. Это файл json_robot_config_check.py, который необходимо запустить отдельно со следующими параметрами:
1. Имя аккаунта, в уникальной папке которого лежит JSON-файл.
2. Имя JSON-файла.
Скрипт выведет ошибки файла, если таковые найдутся.
Выложите файл на хост, в папку account-specific/ACCOUNT_NAME/configs, где ACCOUNT_NAME — имя Вашего аккаунта.

В настройку конфигурации "robots" следует внести информацию следующего вида:

{  
   "OPERATOR_ID": {  
      "type": "json",
      "logic_descriptor_filename": String
   },
   ...
}

Название параметра	Тип	Пример	Описание
`OPERATOR_ID`	`String`	`"533"`	ID оператора, за которым закреплен робот.
`type`	`String`	`"json"`	Тип файла с описанием логики (`"json"`).
`logic_descriptor_filename`	`String`	`"example.json"`	Имя JSON-файла с описанием логики.

Выполните flush.