Webim (External Bot API 2.0)

Webim – одна из популярных омниканальных платформ для общения с клиентами в текстовых каналах. Вы можете использовать ее в качестве канала для публикации вашего Агента в качестве бота-оператор. В данной статье рассмотрено подключение ботов через асинхронный API - Webim External Bot API 2.0Webim может использоваться как сервис по подписке на облаке, так и быть размещен на частных серверах клиента как коробочное решение. Адрес аккаунта Webim используется для настройки подключения Агента в качестве бота-оператора - см. Подключение

• При использовании Webim как облачного сервиса по подписке адрес аккаунта Webim выглядит как <some-name>.webim.ru, где <some-name> - имя поддоммена, которые вы установите в настройках аккаунта Webim. Например, адрес может быть таким https://chatmeai006.webim.ru/

• При размещении Webim на частных серверах клиента адрес аккаунта устанавливается клиентом и зависит от домена размещения.

Подключение

1. Конфигурация бота на стороне Webim

В первую очередь нужно произвести конфигурацию на стороне Webim.

1. Авторизуйтесь в Webim как администратор.

2. Перейдите в раздел Настройки → Боты.

3. Начните создавать нового бота и заполните следующие поля:

4. 1. Оператор для бота — выберите оператора, к которому будет прикреплен бот, рекомендуется создавать отдельных операторов для ботов

   2. Тип бота — выберите Умный бот

   3. Порядок сортировки — порядок определяет, на каком месте в списке ботов данный бот будет находиться. Чем меньше число, тем выше приоритет

   4. Статус — выберите статус бота

   5. Версия — выберите версию 2

   6. Ссылка на внешний API — введите адрес вебхука, его можно получить при настройке Канал Проекта — см. 2. Конфигурация агента в Платформа - п.2.4

   7. 

5. Установите ссылку на вебхук, полученную при конфигурации канала агента в Платформе в поле Ссылка на внешний API, сохраните бота и получите токен авторизации. Используйте токен для завершения конфигурации канала агента с п.2.5

На этом конфигурация бота в Webim завершена.

2. Конфигурация канала агента в Платформе

Агенту необходимо создать и настроить Канал Проекта с Коннектором “Webim (External Bot API 2.0)”.

1. Кликните по кнопке настроек Агента.
2. Нажмите кнопку Add channel.
3. Откроется панель выбора Конечный канал.
4. Выберите Webim (External Bot API 2.0).

5. Откроется панель создания Канал Проекта.
6. По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.
7. Пропишите адрес Webim External Bot API 2.0 для вашего аккаунта в поле Webim (External Bot API 2.0) webhook URL в виде https://<some-name>.webim.ru/api/bot/v2 где <some-name> - имя поддоммена, которые вы установите в настройках аккаунта Webim.
8. Установите полученный в настройках бота Webim токен в поле Webim (External Bot API 2.0) token.
9. Cсылку на вебхук Канал Проекта (поле Chatbot webhook URL) скопируйте и вставьте в поле Ссылка на внешний API в настройках бота в Webim.
10. Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.
11. Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.
12. 1. Канал Проекта будет сохранен и активирован, если:

    2. 1. Агент обучен;

       2. токен в поле Webim (External Bot API 2.0) token token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

       3. будет доступен адрес Канал Проекта;

       4. удастся зарегистрировать вебхук канала.

    3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены.

13. Для отмены создания Канал Проекта нажмите кнопку CANCEL.

Редактирование и удаление Канала Агента

Для редактирования Канал Проекта, необходимо кликнуть по его иконке на карточке Агента.

1. Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение.

2. Чтобы применить изменения к активированному Канал Проекта, нажмите кнопку APPLY.
3. 1. Изменения будут применены, если:

   2. 1. Агент обучен;

      2. токен в поле Webim (External Bot API 2.0) token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения не будут применены, если одно или больше условий не будут выполнены.

4. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.
5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.
6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.
7. 1. Изменения будут применены и Канал Проекта будет активирован, если:

   2. 1. Агент обучен;

      2. токен в поле Webim (External Bot API 2.0) token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены.

8. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.
9. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.

Формат запроса на Webim (External Bot API 2.0) коннектор

Корректный запрос на “Omnichannel” Коннектор имеет следующий формат:

{    "event": "new_message",    "chat_id": "12345",    "message": {        "kind": "visitor",        "text": "hello!"    },    "visitor": {        "id": 123,        "fields": {            "name": "John"        }    }}

visitor — опциональное поле.

Общение

Взаимодействие с Webim происходит через Webim External Bot API 2.0 и согласно настройкам вашего аккаунта Webim. Агент является ботом-оператором в Webim.

Переменная	Конечный канал	Переменная в запросе из канала
channel_conversation_id	Webim (External Bot API 2.0)	chat.id
channel_visitor_id	Webim (External Bot API 2.0)	visitor.id
channel_visitor_firstname	Webim (External Bot API 2.0)	visitor.fields.name
channel_visitor_lastname	Webim (External Bot API 2.0)	нет
channel_visitor_account	Webim (External Bot API 2.0)	visitor.fields.login
channel_visitor_phone	Webim (External Bot API 2.0)	visitor.fields.phone
channel_visitor_email	Webim (External Bot API 2.0)	visitor.fields.email
channel_visitor_source	Webim (External Bot API 2.0)	visitor.fields.site

Функционал общения	Конечный канал	Доступность в канале	Примечания
channel_chat_id	Webim (External Bot API 2.0)	Да	формат <webim chat_id>|omnichannel т.к. используется Коннектор Omnichannel
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате	Webim (External Bot API 2.0)	Да
Кнопки	Webim (External Bot API 2.0)	Да	нажатие на кнопку приходит как текст лейбла кнопкиВ WhatsApp через Webim: если бот отправил собеседнику кнопки, то Webim преобразует их в нумерованный список и обработает только ввод номера элемента, ввод лейбла кнопки или другого текста не будет обработан - Webim не будет воспринимать другие символы\текст
Перевод на оператора	Webim (External Bot API 2.0)	Нет	Не поддерживается перевод на оператора через слот Change Chat Mode в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request
Передача файлов в виде файлов от Агента (Attachment)	Webim (External Bot API 2.0)	Нет
Передача файлов в виде ссылок от Агента (Attachment)	Webim (External Bot API 2.0)	Да
Получение файла от Собеседника в сценарий	Webim (External Bot API 2.0)	Да
Доставка сообщений более 1000 символов от Агента до Собеседника	Webim (External Bot API 2.0)	Да
Использование маркдауна	Webim (External Bot API 2.0)	Нет
Рассылки с помощью Notification	Webim (External Bot API 2.0)	Нет

Перевод на оператора

Не поддерживается в текущей реализации функционала Платформа.Предлагается выполнять перевод на оператора с помощью External Request, используя соответствующий метод Webim External Bot API 2.0