# Сценарный бот
В данной статье содержится описание Сценарного бота, принцип работы, его основные параметры и настройки.
## Описание бота { #description }
**Сценарный бот** — это робот, работающий по заранее заданному сценарию в виде конечного автомата:
* сценарий состоит из **1 или более состояний**;
* между состояниями задаются **переходы** (по нажатию кнопок и/или через действия);
* каждое состояние включает **0 или более действий** и **0 или более кнопок**. При этом в состоянии должно быть задано **хотя бы одно** действие или кнопка.
Сценарный бот всегда находится в одном текущем состоянии. Когда бот входит в состояние (в начале диалога или после перехода), он выполняет действия состояния по порядку, затем показывает посетителю кнопки этого состояния.
Описание логики задаётся через страницу **Боты** административного интерфейса с помощью табличного редактора. Интеграции с внешними (относительно **Webim Server**) системами не требуется. Опция присутствует в версиях начиная с **10.0**; по умолчанию отключена. Для активации обратитесь к менеджеру или в службу [технической поддержки](mailto:support@webim.ru) **Webim**.
В версиях **9.х** этот бот назывался робот класса `JsonRobotLogic`, логика его находилась в JSON-файле, размещённом на сервере. Ключевые отличия бота в версии **10.0**:
* добавлен табличный редактор в административный интерфейс;
* посетитель выбирает варианты ответа через кнопки (переходы);
* конфигурация бота хранится в БД.
---
## Принцип работы бота { #work-principle }
Бот прикрепляется к профилю одного из существующих операторов, учётной записью которого определяется, в каких отделах бот будет обрабатывать сообщения.
!!! Note "N.B."
При прикреплении бота к профилю, под которым работает реальный оператор, корректная работа не гарантируется. Для бота требуется создавать отдельную учётную запись.
### Общий алгоритм
1. Когда диалог назначается на бот (только если статус бота **Онлайн**), бот устанавливает **начальное состояние** (с маркером **Является начальным**).
1. При входе в состояние бот:
* выполняет **действия** этого состояния по порядку (см. [Действия](#actions));
* затем показывает посетителю доступные **кнопки** этого состояния (см. [Кнопки](#buttons)).
1. Когда посетитель нажимает кнопку, бот переходит в состояние, указанное в поле **ID состояния** у этой кнопки, и повторяет шаг «вход в состояние» (действия → кнопки).
### Если посетитель отправил сообщение вместо нажатия кнопки
Помимо нажатия кнопок посетитель может отправить текст, файл, стикер и т. п. Такое входящее сообщение бот не сопоставляет с переходом по кнопке. Дальнейшее поведение определяется настройкой бота **ID состояния для перехода при сообщении от посетителя, которое бот не может обработать** (см. [Переход при сообщении от посетителя](#fallback-state)):
* если значение задано, бот перейдёт в указанное состояние;
* если значение не задано, бот **останется в текущем состоянии** и повторит его обработку: заново выполнит действия текущего состояния и снова покажет кнопки.
Сообщения посетителя (в том числе «неожиданные») не теряются: они сохраняются в истории диалога и будут видны оператору после перенаправления, если оно предусмотрено сценарием.
### Проверки и типовые требования к сценарию
* У состояния, кроме состояний с действием **Перенаправление на оператора**, должна быть предусмотрена возможность перехода в другие состояния (например, возврата в меню). В противном случае вместо сохранения логики в верхней части страницы появится описание ошибки.
* Переходы (кнопки и действия **Переход в другое состояние**) должны ссылаться на существующие состояния сценария.
* Рекомендуется проектировать сценарий так, чтобы у посетителя всегда был «выход»: возврат в главное меню и/или передача на оператора.
* Не рекомендуется задавать переход в текущее состояние без необходимости: это приводит к повторному выполнению действий и повторному показу кнопок и может восприниматься посетителем как «зацикливание».
* Рекомендуется избегать чрезмерно больших сценариев (очень большого числа состояний, действий и кнопок): это усложняет сопровождение и может негативно влиять на удобство редактирования и диагностику логики.
---
## Порядок сортировки { #sorting-order }
Порядок сортировки используется для определения приоритетного бота в отделе для назначения на него диалогов. На примере ниже чаты будет брать робот, отмеченный красной стрелкой.
{ style="width: 1108px; max-width: 100%" }
Также, если более приоритетный бот по какой-либо причине не смог принять диалог (например, на момент версии **10.0** бот не поддерживает обращения из следующих каналов: **Apple Messages for Business**, **XMPP**), диалог примет на себя бот с более низким приоритетом, чем предыдущий. Такая цепочка будет продолжаться, пока диалог не попадёт на бот, который сможет обработать диалог, либо на оператора.
---
## Переход при сообщении от посетителя { #fallback-state }
Параметр **ID состояния для перехода при сообщении от посетителя, которое бот не может обработать** задаётся для бота целиком (в общих настройках бота, над блоком состояний).
Если посетитель отправил сообщение (текст, файл и т. п.) вместо нажатия кнопки:
* при заданном значении бот перейдёт в указанное состояние;
* при пустом значении бот останется в текущем состоянии и повторит его обработку (действия → кнопки).
---
## Состояние { #states }
Состояние описывает текущее состояние бота: его ID, действия и кнопки, которые будут выведены при входе в состояние.
{ style="width: 1060px; max-width: 100%" }
| Название параметра | Принимаемые значения | Описание |
|------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| **ID состояния** | Текст | Уникальный идентификатор состояния. Используется для перехода с помощью действия **Переход в другое состояние** или при нажатии кнопки. |
| **Является начальным** | `True`/`False` | Маркер, определяющий первое состояние, в котором будет находиться бот. Начальное состояние может быть только одно. |
| **Добавить действие** | | См. [описание типа](#actions). |
| **Добавить кнопку** / **Добавить кнопку с ссылкой** | | См. [Кнопки](#buttons): обычная кнопка или [кнопка с ссылкой](#link-button). |
---
## Действия { #actions }
Действия, которые выполняются в момент входа в состояние.
{ style="width: 1060px; max-width: 100%" }
| Название действия | Принимаемые значения | Пример | Описание |
| -------------------------------- | -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Сообщение** | Текст | *Добрый день. Я сценарный робот.* | В поле указывается сообщение, которое будет отправлено пользователю от лица бота при выполнении данного действия. |
| **Переход в другое состояние** | ID состояния | `start` | В поле указывается ID существующего состояния, в которое перейдёт бот при выполнении данного действия. |
| **Перенаправление на оператора** | Название отдела | *Текущий*, *Без отдела* | В поле указывается отдел, в который перенаправится диалог.
*Текущий* — отдел, в котором находится диалог в данный момент.
*Без отдела* — диалог попадёт в общую очередь. |
| **Возврат в предыдущее состояние** | | | Бот вернётся в предыдущее состояние, из которого был осуществлён переход в текущее. |
Параметр **Если офлайн** в действии **Перенаправление на оператора** определяет, что будет делать бот, если в отделе, куда перенаправляется диалог, нет операторов в статусе *Онлайн*:
* **перенаправить**: диалог перенаправится в отдел, даже если в нём нет операторов в статусе *Онлайн*
* **не перенаправлять**: никаких действий с диалогом совершено не будет, выполнятся следующие по списку действия
---
## Кнопки { #buttons }
Кнопки, которые будут выведены посетителю после выполнения действий текущего состояния.
В блоке **Кнопки** состояния можно добавить элементы двумя способами:
* **+ Добавить кнопку** — обычная кнопка перехода по сценарию;
* **+ Добавить кнопку с ссылкой** — кнопка перехода, у которой дополнительно задаётся URL (см. [ниже](#link-button)).
{ style="width: 1060px; max-width: 100%" }
| Название параметра | Принимаемые значения | Описание |
|--------------------|----------------------|-----------------------------------------------------------------------------------------------------|
| **Заголовок** | Текст | Текст, указанный в данном поле, будет написан на кнопке. |
| **ID состояния** | ID состояния | В поле указывается ID существующего состояния, в которое перейдёт бот при нажатии на данную кнопку. |
| **Ссылка** | URL (`http://` или `https://`) | Только у кнопки, добавленной через **+ Добавить кнопку с ссылкой**. Обязательный адрес; допускаются схемы `http` и `https`, формат проверяется в редакторе. Ссылка передаётся клиенту чата при нажатии кнопки; поведение (открытие в браузере и т. п.) зависит от канала и приложения. |
### Кнопка с ссылкой { #link-button }
Такая кнопка ведёт себя как обычная с точки зрения сценария: при нажатии бот переходит в состояние из поля **ID состояния**. Отличие в том, что в интерфейсе чата у кнопки есть связанный **URL** — например, чтобы отправить посетителя на страницу справки, оплату или сайт, не ограничиваясь только текстом сообщений бота.
Чтобы добавить кнопку с ссылкой, в блоке кнопок состояния нажмите **+ Добавить кнопку с ссылкой**, заполните **Заголовок**, **ID состояния для перехода** и **Ссылку** (допустимы только схемы `http` и `https`).
---
## Основная настройка робота { #setup }
1. [Создайте](https://webim.ru/kb/getting-started/registration-agent.html) нового оператора и добавьте его в отделы, чаты которых должен обрабатывать бот.
1. В боковом меню **Административного интерфейса** в пункте **Настройки** нажмите на блок [Боты](https://webim.ru/kb/bots/add-new-bot.html). Откроется страница настройки существующих ботов.
{ style="width: 1108px; max-width: 100%" }
1. На странице **Боты** нажмите кнопку **Создать новый бот**.
{ style="width: 1108px; max-width: 100%" }
1. Укажите данные создаваемого бота:
* Выберите оператора, учётная запись которого была зарегистрирована специально для бота.
* Выберите **Тип бота** — Сценарный бот.
* Укажите [порядок сортировки](https://webim.ru/kb/for-admins/registration-agents-and-supervisors.html#order-of-sort).
* Укажите статус бота (если хотите, чтобы бот был активен сразу после настройки, укажите статус *Онлайн*).
* При необходимости задайте **ID состояния для перехода при сообщении от посетителя, которое бот не может обработать** (см. [Переход при сообщении от посетителя](#fallback-state)).
{ style="width: 1052px; max-width: 100%" }
1. С помощью [состояний](#states), [кнопок](#buttons) и [действий](#actions) опишите логику работы бота и нажмите кнопку "**Сохранить**" в нижней части страницы.
{ style="width: 1060px; max-width: 100%" }
---
Источник: https://webim.ru/kb/bots/scenario-bot.html