# Webim (External Bot API 2.0)

[Webim](https://webim.ru/) – одна из популярных омниканальных платформ для общения с клиентами в текстовых каналах. Вы можете использовать ее в качестве канала для публикации вашего Агента в качестве бота-оператор. В данной статье рассмотрено подключение ботов через асинхронный API -  [Webim External Bot API 2.0](https://webim.ru/kb/bots/external-api/15043-robot-external-api-2-0/)Webim может использоваться как сервис по подписке на облаке, так и быть размещен на частных серверах клиента как коробочное решение. Адрес аккаунта Webim используется для настройки подключения Агента в качестве бота-оператора - см. Подключение

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

## Подключение

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

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

1. Авторизуйтесь в [Webim](https://webim.ru/) как администратор.
2. Перейдите в раздел Настройки → Боты.
3. Начните создавать нового бота и заполните следующие поля:
4.
   1. Оператор для бота — выберите оператора, к которому будет прикреплен бот, рекомендуется создавать отдельных операторов для ботов
   2. Тип бота — выберите Умный бот
   3. Порядок сортировки — порядок определяет, на каком месте в списке ботов данный бот будет находиться. Чем меньше число, тем выше приоритет
   4. Статус — выберите статус бота
   5. Версия — выберите версию 2
   6. Ссылка на внешний API — введите адрес вебхука, его можно получить при настройке Канал Проекта — см. 2. Конфигурация агента в Платформа - п.2.4
   7. ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-Y2eeKW3Aaq/b4f7c103fb3845f21a45eae83acae5ed558afe881f49e10abfa9d96e97576f4c1018ae38c2be45bb77018c7e5ba6bf85f132dddb53ab0095460dfb35b360b40f4e9c23d8e03be0d59aebd687eb3324d891d1b95d5e779fc1f7303569a667dbf10076b3df)
5. Установите ссылку на вебхук, полученную при конфигурации канала агента в Платформе в поле Ссылка на внешний API, сохраните бота и получите токен авторизации. Используйте токен для завершения конфигурации канала агента с п.2.5![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-LAa7OC5hOT/02d61069290265c3586766492aa3a31e3d8adc39af82f69235a106d9d51111e8db0c30b89ea420eff0a5cf0378196b87dd5dfb9c9c553ecc8e40fe33c68c649503965efe6dc837f12ea02737acc225c3bc6686288b19325d64044ace0e607d035e8c8625)

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

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

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

1. Кликните по кнопке настроек Агента.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-m_bL4GvN1_/de0e6c51b47058d8e7854370e44e3e29e8d1195855e34484c55e0ba55e6f4cbc2f103ac4ebcc2b78bf606d6b02118303275d07760b64f89e5ea954cd86466379ab9850814435bbe8d5ab7d3e80e7ac68c8a471b3ba0022e97fb3209a771f11a86b6c817e)
2. Нажмите кнопку Add channel.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-KJ7zJqauLN/e76804ae1c32c84507914bcbac89b59e5fa7160e857084643655c65f3192dbec4709a2cd8abae87edc6a858acbd80d17c3296d23c47a2c39eccf56433201a9779ccf4ea2580c347508e5f68b0ee94654585fa349ceadd2e6587a4bdebd6c5d9715835322)
3. Откроется панель выбора Конечный канал.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-s7QCSakdqU/c56376ab80440775df7dbe9b0854040613e5a1ee2dfabe51e794ca3caca9f5c8c062bd04ca5adeb304c0f4263f35aed50aacf13347520584de4625babdd1006e377ba6864d170804e7cbe276c0779c5c33c28b39a9ea44aa7a6d57b9774f7412ad104b53)
4. Выберите Webim (External Bot API 2.0).
5. Откроется панель создания Канал Проекта.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-OYWt2PzN0w/2f7f55bf50570dc7cc8d387a6a19b3fa8de70f627ca8a3b263f7713f47e58b63f92e3e604bef7b7cc869ca81142edb1b328ae7a452f202205b448ac8c8f14d4e5dbbe185987917c39be5347cc55e8ab5f39fd287f6892e93440b46d72eeba02352a98082)
6. По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-9AFtXOUgav/e95d1d77bb601cc8521e0778e860e9879caf6b10f660c240c8920190fe2d256acd76809e92059d93d0d2985c9720ffc77b5da61fcf46ae5dee44039e989e7b1cf35ebf2b0a35c766591d3f9892dbb109c57005137b2586452cc7b83b30dec91f177178f1)
7. Пропишите адрес [Webim External Bot API 2.0](https://webim.ru/kb/bots/external-api/15043-robot-external-api-2-0/) для вашего аккаунта в поле Webim (External Bot API 2.0) webhook URL в виде https://\<some-name>.webim.ru/api/bot/v2 где \<some-name> - имя поддоммена, которые вы установите в настройках аккаунта Webim.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-4yYUZKVEu-/5e46bed4ffd716f0090bc4f789b6376086126350bb5a42e14e5c6940d77a768931efe7bef9b8638d2b109e94b87b71473b0ef6b8cbbd26b836ac75b4d6ac9884b75366662df0ef89fc3cb7acac2f10b9d1abd015620a97c2a54b6138996d9ed15ba60aca)
8. Установите полученный в настройках бота Webim токен в поле Webim (External Bot API 2.0) token.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-q65iZQ8QLG/a9c224b90b7d7ce9d05a9dbed5d8c70ece822bec35bcbd9eb6f6913855b68de42804ec618611fc3229f0776417f7f91215dbaecab63c317b0e94ddae386e0cdc5d5a7e83053d3bc629b45d5d1fd251f63991c1311efa256c83cf18a57c0895aaee1e951c)
9. Cсылку на вебхук Канал Проекта (поле Chatbot webhook URL) скопируйте и вставьте в поле Ссылка на внешний API в настройках бота в Webim.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-nX4Vs2zNWL/a372b73129ecea8b7c2a5799f4cad3d4833a9a82cd4225fbed46017da4a4cb8da447f3461fee0d2e1b2d582e29ad747cb0c9599e37c6bf330c3682509b241359394def5d3af7479f6bcc03ca9c26418a45c07b8b8b242c1b6d5368f2fe7da13feea1cf5d)
10. Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.\
    ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-liNwKmuLwB/d057a3a9ffe0055d2702301ca7712296c6547f647791b83f117d226121a02c98547ceaf05f0432246873be9c7504e782c9d75d825fd8df2bcd6f32fdac6e8e3ad2f99f743e1394ed468ffb7557efbf4ba91d1e5024b31e4a7d4eab7075f440bbd399465c)
11. Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.\
    ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-Nerxb9Yv64/36e3e2c782b5f9c524ad731e5772f07d21e38f4955e100c51b208bcfbcddba7db33afda4597b30d033e9efa58b434813fc4992d316ad071aadee780e23ce9170207ad50af05bcf7f6ffb7b77ab4a160038caacacb54e770289b3ffa69a2dd33d13ee13de)
12.
    1. Канал Проекта будет сохранен и активирован, если:
    2.
       1. Агент обучен;
       2. токен в поле Webim (External Bot API 2.0) token token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
       3. будет доступен адрес Канал Проекта;
       4. удастся зарегистрировать вебхук канала.
    3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены.
13. Для отмены создания Канал Проекта нажмите кнопку CANCEL.\
    ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-Kjbypyqe4U/07307be576e66bf187e408c630bd57fd7dec7266ae9f8cd0995ea080d5b09b15ca8e7ab28ad66f87e7debd682b8e4d855979f9af6eee39263b7dc98deb229bcb3dc39a423c3749fa2ae8da66b1e4b35c9e09d79c86cc967fd8c7a3fec684a1442e702939)

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

Для редактирования Канал Проекта, необходимо кликнуть по его иконке на карточке Агента.\
![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-LNPwPci64Y/9a8c925713bc0b64bec959fd30a17face4d9afb1fa35c6be6065dab5e2462bdb70a120025f5caa62c07966d329e49a9f6d8fd1885fafdad924c35d14f3ee11e2d8e200b7c276968e537f8a32712a42ae6122ca0a0b19a62205e042fa147f9a75b3367d7e)

1. Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение.
2. Чтобы применить изменения к активированному Канал Проекта, нажмите кнопку APPLY.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-hbgOWgT3BK/e09100a1f1562d47f31144102b834cdb0693a14dcf98c3614e0ecce72b1d4c1d68306c5d4de64766d78d168fbfd0f5b8cd33793d8991cb5bbe0e7357dbcfae23f34ad7f05bbd7d2395dc63d13ee4add33ee87b89a792a069cfba3f767bfea098411133e3)
3.
   1. Изменения будут применены, если:
   2.
      1. Агент обучен;
      2. токен в поле Webim (External Bot API 2.0) token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
      3. будет доступен адрес Канал Проекта;
      4. удастся зарегистрировать вебхук канала.
   3. Изменения не будут применены, если одно или больше условий не будут выполнены.
4. Чтобы деактивировать  Канал Проекта, нажмите кнопку DEACTIVATE.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-OtFUWmOtXq/ef5544868be33c1e431f6e8f601ed5a176aaca33d7ae7d59ce17a94972ab468142b6d529e0869395e06051bf832e64743bc4a493ef13bb3adc1176b2f2809bbb6184174e99f1c311b8e5396cb53afb844daa13e47a8fd207befdaf1fc18e1f70c4448a08)
5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-cBvVfg5bo5/3102732467a762c63f4f7cea13ab78c503e0bd639827aa0ab454d52bd77ad6d3a520759d160b200ba8463646690737c4b2c1e367f4f3fa80813481937c29bd61816be520ed2bb0a1c9cc549db9a4e2cdf04f93b9f63432e0bd4b4f96e10c5cb0a0a9e71c)
6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-BTVZkb_uZN/dbff874c0256fc5280defd7dd1a166c28c56f2f5fa28b6fb6f4d1b6a4a2ec3ca734d7273a494c11b53691ac54e287a43110437e1bc998eab611521ab386832a8492a182bc8ce64341df1da38d5501647adcb2c499df5f8899163fb4a95995c2c91f73f43)
7.
   1. Изменения будут применены и Канал Проекта будет активирован, если:
   2.
      1. Агент обучен;
      2. токен в поле Webim (External Bot API 2.0) token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
      3. будет доступен адрес Канал Проекта;
      4. удастся зарегистрировать вебхук канала.
   3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены.
8. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-pee7Fktkh4/8d417ff737e1b0d8e30ac6265ba170d9863bdc9dbd1a563d3f7fe481ba1712d88d91a0d3fecfbfcbbe30605cbc89f0b88231cc7630cea1c600f01369726b8fa14bf6c97125d8547a776e599e7501aec583c7f4248ff28d7fb3dcbf1e854a007720dd6cc4)
9. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.\
   ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-2GzqhWmj4J/52ed2517a4b9b67db4a583f2843c2d1bb34286dd05c1d14e7ee808c57b726e74028ca3965b6778a624d279e601a28c261c492ad1256dc5509b065b3226637dd95f5013a41fbe75a5896dcb8b9eff2375a448017a9fe3f74c92ab2ca7b7243d73cc9d9114)

## Формат запроса на 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](https://webim.ru/kb/bots/external-api/15043-robot-external-api-2-0/) и согласно настройкам вашего аккаунта Webim. Агент является ботом-оператором в Webim.

| Переменная                  | Конечный канал               | Переменная в запросе из канала                      |
| --------------------------- | ---------------------------- | --------------------------------------------------- |
| channel\_conversation\_id   | Webim (External Bot API 2.0) | [chat.id](http://chat.id)                           |
| channel\_visitor\_id        | Webim (External Bot API 2.0) | [visitor.id](http://visitor.id)                     |
| channel\_visitor\_firstname | Webim (External Bot API 2.0) | [visitor.fields.name](http://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](http://visitor.fields.phone) |
| channel\_visitor\_email     | Webim (External Bot API 2.0) | [visitor.fields.email](http://visitor.fields.email) |
| channel\_visitor\_source    | Webim (External Bot API 2.0) | [visitor.fields.site](http://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](https://webim.ru/kb/bots/external-api/15043-robot-external-api-2-0/)\
