# Чат-бот BSS - Dialog Composer

Для клиентов **Webim**, начиная с версии [10.4](https://webim.ru/webim-10-4/) доступна интеграция с чат-ботом [Dialog Composer](https://bssys.com/products/retail-customers/chat-bot/) от компании **BSS**, который может быть особенно интересен банкам, так как он разрабатывается компанией, создающей информационные банковские продукты.

**Dialog Composer** позволит осуществлять техническую поддержку круглосуточно, снижая нагрузку на операторов и быстро обрабатывая обращения пользователей. Это "умный" бот, который интегрируется с **Webim** через собственное API.

!!! Note "N.B."
    **Dialog Composer** - синхронный бот. Это накладывает на него некоторые ограничения: бот может **только отвечать** на сообщения посетителей с таймаутом ответа в 10 секунд. В случае, если бот не успел ответить за таймаут, обращение будет автоматически переведено на живого оператора.

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

Возможности бота могут варьироваться, так как каждая интеграция делается индивидуально, но в целом в рамках **Dialog Composer** может быть доступно следующее:

  * Начало и закрытие чата

  * Отправка текстовых сообщений

  * Отправка кнопочного меню и обработка ответов

  * Отправка чата в общую очередь при выключенном [автоназначении](https://webim.ru/kb/for-admins/chat-assignment-modes.html)

  * Назначение чата на другого оператора из того же отдела при включенном [автоназначении](https://webim.ru/kb/for-admins/chat-assignment-modes.html)

!!! Note "N.B."
    **Dialog Composer** передаёт кнопки в объекте `data` внутри массива `buttons`: поле `label` внутри элемента массива соответствует тексту кнопки, а поле `tag` - идентификатору кнопки.

**Webim** поддерживает следующий список действий (action) **Dialog Composer**:

  * `continue`: продолжение общения с ботом

  * `finish`: закрытие диалога

  * `transfer`: перевод чата

!!! Note "N.B."
    В случае, если бот передаст системе необрабатываемое действие (action), чат будет отправлен в общую очередь или назначен на оператора из того же отдела.

## Эндпоинты бота

В **Dialog Composer** существуют три эндпоинта, связанных с различными действиями бота в системе **Webim**:

  * `/start` - Начало сессии бота

  * `/next` - Отправка текстового или кнопочного сообщения

  * `/end` - Завершение сессии бота

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

## Настройка интеграции

Чтобы настроить интеграцию с **Dialog Composer**, выполните следующие шаги:

  1. В **Настройках** выберите раздел **Боты**.

    ![Раздел Боты](https://webim.ru/kb/img/integration/chat-bots/bss-chat-bot/section-bots.webp){ style="width: 209px; max-width: 100%" }

  1. Нажмите **Создать новый бот**.

  1. В открывшейся форме заполните следующие поля:

    * **Оператор для бота**: выберите учётную запись из списка доступных, которая будет использоваться в качестве учётной записи бота. Настоятельно рекомендуем для чат-бота создавать отдельную учёную запись.

    * **Тип бота**: укажите тип бота **BSS**.

    * **Порядок сортировки**: отвечает за определение приоритета операторов(ботов) при включенном автоназначении.

    * **Статус**: установите статус, в котором будет пребывать **Dialog Composer**. Можно установить следующие статусы: *Онлайн*, *Невидимка* и *Офлайн*.

    * **Базовая ссылка на API**: введите здесь ссылку на API (URL вебхука, например, `https://dc1.voice.bssys.com/api/public/v1.0`) бота для передачи запросов из **Webim**. Не допускается вводить символ `/` на конце ссылки.

    * **Токен для внешнего API**: введите здесь токен авторизации бота.

    ![Пример заполнения формы](https://webim.ru/kb/img/integration/chat-bots/bss-chat-bot/bss-bot-filled-form-example.webp)

  1. После заполнения формы нажмите **Сохранить**. Новый бот отобразится в списке всех доступных ботов. Также будет отображена информация о статусе бота (*Онлайн*, *Невидимка*, *Офлайн*), учётной записи, от лица которой действует бот, типе бота (в данном случае **BSS**) и порядке сортировки.

    ![Чат-бот BSS в списке доступных ботов](https://webim.ru/kb/img/integration/chat-bots/bss-chat-bot/bots-list.webp)

     Чтобы отредактировать бот, нажмите у нужного бота в списке кнопку ![Иконка редактирования бота](https://webim.ru/kb/img/icons/icon-bot-edit.svg).

    !!! Note "N.B."
        Обратите внимание, что для созданного бота нельзя изменить учётную запись (поле **Оператор для бота**) и его тип! Эти поля настраиваются один раз и их можно изменить, только если удалить бот и создать новый.

## Проверка работы

Для проверки работы Dialog Composer начните чат с ним в качестве посетителя. Например, используя sample page:

  * chat.mycompany.com/sample-page.php — для hosted-клиентов

  * accountname.webim.ru/sample-page.php — для облачных клиентов

Где:

  * chat.mycompany.com — доменное имя, назначенное хосту (серверу), на котором развернут Webim Server (то есть адрес вашего hosted-стенда)

  * accountname — имя аккаунта вашей организации в Webim

Если интеграция настроена верно, то чат-бот будет отвечать на сообщения и полноценно участвовать в диалоге с посетителем.

  ![Пример диалога с ботом Dialog Composer со стороны посетителя](https://webim.ru/kb/img/integration/chat-bots/bss-chat-bot/chat-bss-example-visitor.webp){ style="width: 338px; max-width: 100%" }

## Примеры запросов и ответов

### Инициализация сессии с Dialog Composer

```
POST "https://<some_domain>/api/public/v1.0/start" -H "accept: application/json" -H "Authorization: Bearer $token" -H "Content-Type: application/json" –d "
{
  "channel_id": "channel1",
  "channel_type": "text",
  "session_id": "client1-scriptid-channel1-user1",
  "use _id": "user1",
  "variables":
  {
    "var1": "Value"
  },
  "formatting_type": "html",
  "formatting_options": ["ALL"]
}"
```

### В чат посетителю возвращается ответ, полученный от Dialog Composer

```
{
  "action": "continue", 
  "error_code": 0,
  "error_info": "",
  "messages": 
  [
    {
      "content": "Здравствуйте", 
      "content_type": "text", 
      "buttons": []
    }, 
    {
      "content": "Что Вас интересует?", 
      "content_type": "text", 
      "buttons":[]
    }
  ], 
  "session_id": "client1-b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9", 
  "variables": {}
}
```
### Отправка кнопочного меню

```
{
  "action": "continue",
  "error_code": 0,
  "error_info": "",
  "messages": [
    {
      "content": "Выберите одну из опций:",
      "content_type": "text",
      "buttons": [
        {
          "tag": "b28b8e7f-674b-43b5-8f8a-5b1e3d8581a5",
          "label": "Опция 1"
        },
        {
          "tag": "c96efb2d-8d0d-42a5-bcaf-bbdca8175e53",
          "label": "Опция 2"
        }
      ]
    }
  ],
  "session_id": "client1-b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9",
  "variables": {}
}
```
!!! Warning "Важно!"
    Идентификатор кнопки должен быть не более 24 символов в длину. Допустимые символы: буквы, цифры, дефис, точка, подчёркивание.
    
### Выбор варианта ответа посетителем

```
{
  "content": "банкоматы",
  "session_id": "client1-b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9",
  "content_type": "text"
}, 
{
  "user_id":"5ddbc40e7778fd002748def7",
  "mapping_id":"5de9f27294979a03c7f1d4cb",
  "channel_type":"api"
}
```

### Возвращение ответа от Dialog Composer

```
{
  "action": "continue",
  "error_code": 0,
  "error_info": "",
  "messages": 
  [
    {
      "content": "Ближайший к Вам банкомат находится по адресу Москва , это примерно в 28.234010131635284 от вашего местоположения.",
      "content_type": "text",
      "buttons": []
    }, 
    {
      "content": "Что Вас интересует?",
      "content_type": "text",
      "buttons": []
    }
  ], 
  "session_id": "client1-b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9",
  "variables": {}
}
```

### Завершение диалога с ботом

```
{
  "action": "finish",
  "error_code": 0,
  "error_info": "",
  "messages": 
  [
    {
      "content": "Спасибо",
      "content_type": "text",
      "buttons": []
    }
  ],
  "session_id": "client1-b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9",
  "variables": {}
}
```

---

Источник: https://webim.ru/kb/integration/chat-bots/bss-chat-bot.html