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

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

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

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

Текущее состояние при диалоге с роботом хранится в объекте чата в поле external_data с ключом 'json_robot_current_state'.

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

При переходе к новому состоянию тут же выполняются actions, которые связаны с текущим состоянием, затем выводится список возможных переходов (step), которые можно осуществить, а также ключевых слов, которые нужно вводить для осуществления перехода.

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

Из всех состояний, за исключением содержащих действие "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 оператора.

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

1. Воспользуйтесь нашим скриптом, который осуществляет глубокую проверку добавляемого JSON-файла. Это файл json_robot_config_check.py, который необходимо запустить отдельно со следующими параметрами:

  1. Имя аккаунта, в уникальной папке которого лежит JSON-файл.
  2. Имя JSON-файла.

Скрипт выведет ошибки файла, если таковые найдутся.

2. Выложите файл на хост, в папку account-specific/ACCOUNT_NAME/configs, где ACCOUNT_NAME — имя Вашего аккаунта.

3. В настройку конфигурации "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-файла с описанием логики.

4. Выполните flush.