> For the complete documentation index, see [llms.txt](https://chatme-ai-4.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chatme-ai-4.gitbook.io/docs/kak-vyvesti-agenta-v-konechnye-kanaly/universalnyi-konnektor-chat-api.md). # Универсальный коннектор Chat API Chat API — универсальный канал с публичным API, предназначенный для подключения Агента к Конечный каналам, для которых нет встроенного в Платформа Коннектор.Организовать такой универсальный канал можно с помощью Коннектора Chat API ## Подключение ### Конфигурация канала агента в Платформе Агенту необходимо создать и настроить Канал Проекта с коннектором Chat API 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-VZl30xrWpL/5c5b76b5745c14ded815dbb4401223acd193f4cdfd2130f9b6bd15572e258f663b4c21afc0b0edba192b26f9afc8e553758376197927466e64e35d2cdfbfcb9aa8c53a96001a926cc20792d85979c016e41ba8341d5a77bf270358f6f30260d3a237ac4b) 4. Выберите Chat API. 5. Откроется панель создания Канал Проекта.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-AMJit-RG-H/b6567874f399eda18f650d580d52715023844f69fd1ae0a7ea8475e598d857b6e345717b1e8d8684e1526b31f8fb701c8b75bc114653cb100a12536b6c7e04a160dbf8fb5f3d5933490fc80c625d4f8d1050c0ab9aa640190232fbbd9a6e5def801ae0b4) 6. По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-iIoAWLhka8/34ec5c24974f11e775050b2579a4a1329ba0d4fcd122860d939ac927543bfa674e18d476be267910b60a4180083dddbca5daec9d3ab697cae44e937f281dc8c7165132da5e023c9acb5656f407aee266977bc2030261a7a4c76cd7da29503ee9381adc30) 7. Пропишите адрес вашего сервера в поле Channel webhook URL в виде https\://{server\_adress}, где {server\_adress} — адрес Платформа.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-G9M8tcvU9q/6d83d1c0ff003e089bbb57a622b6dde5b62244c87571a5646d63e8b62cb587cf1aacfdeef2c5f12087e669c85912eac0c926d712528a435a14d94f9f62eaf58058ac9325776da3de6e9e79b197969fab61cf011b1ba8601a6cc0a7a7c2366ccfb1ffeb17) 8. > Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: . 9. По необходимости установите токен в поле Channel token.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-uz5yG9RGZJ/76a18a9f9610899bd2257c17a5e0b5d473fe4efc3a8a9da8a8986be36ef07b435ac51e57698ec4d79304b7736a8049e736d2678e131dae91ddc34a38874099a138c0a6b32000e72f112845d89895cc9758cdcc49d68c8be35471edae47adf1f389e1fabb) 10. > Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в Авторизация на стороне клиента. 11. Скопируйте ссылку на вебхук канала агента (поле Chatbot webhook URL), нажав кнопку Copy this webhook. 12. ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-xRCwWJ24MG/4e70c92b7dbd89b3caeca7f184f9bcc87949a084eeb3e18eab461ea9d84fbe52e5326cf919f0c71ef87d028f872e50c7c34ab0b9d44130a77c6482ce71dd77dd8f06a9cd446040df8ce6afacdcdaeea7e33a404af55624adc71df0db65d66cfe88d338cf) 13. Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-TfZPt7ZXF4/067d539ea71c477e2ac396e7287684236c3cf0790208ab0276f1fdfc067d8d91483160428f0944a0a768b0cc378065967f48f769f82e6cb8843df70ba761dda2e305140ebf9ebd7420c0e56da8a9e1e8277bbc0a46ddfefa2f192483d014e9a5afee0731) 14. Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-PF8AUCxqG2/0b1c0ad60e9d44b955d2d4b3be41a91d42e985f9e33aac24eefebbcda61251da787d0bdeb6afe9e42ce24527b71eed485776805d5dfc62eca613e5ad4cbf3335e99dcc3c90a3d3ffd5ae5ebfd26e276434d9dc3424fdb30866815b89da88b62d97f5da32) 15. 1. Канал Проекта будет сохранен и активирован, если: 2. 1. Агент обучен; 2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле); 3. будет доступен адрес Канал Проекта; 4. удастся зарегистрировать вебхук канала. 3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены. 16. Для отмены создания Канал Проекта нажмите кнопку CANCEL.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl--LfJvENzO1/a7ab5255c7c79dc13cbb55f2973c420a87dfe878654dbf971b62257eeed90e6b05acc0420e8a412285333f566fe6fa44a4be327b2498fb1612475892bfd6051acb695fdcd4467194a7652bf702ecf5f24d3690032bf9cb7a04c41b347dd4e183033140fc) ## Редактирование и удаление Канала Агента Для редактирования Канал Проекта, необходимо кликнуть по его иконке на карточке Агента.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-NtfXLioeB1/77c900674c502f9109c3e21ea985cb468996ffb566ea2d07eb2d7e109007ab380e3754929bb107731c7450f9c0f2e742803c973533ec1da1b96048f37f843eb4b2fad6a94b90c13ef03c241526c544429194400b930aedd5b261189791323dee9ce3411f) 1. Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение. 2. Чтобы применить изменения к активированному Канал Проекта, нажмите кнопку APPLY.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-DwBZ_kuGER/8ddb5ca41adb909444df4bdfb031efe875227f24c689366eaf05df6a22b6bb3ae2b2b91584220a641a59323f7fe95f4ba7362361b16ee54a817c632d057337419ddb6017d68ef66087be6fd5062d0602fced7430e412f6fa25cab2a4c7571106439a3fa2) 3. 1. Изменения будут применены, если: 2. 1. Агент обучен; 2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле); 3. будет доступен адрес Канал Проекта; 4. удастся зарегистрировать вебхук канала. 3. Изменения не будут применены, если одно или больше условий не будут выполнены. 4. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-D3hFjKiP0u/bee7c546d7e9f887be5a192a2cfdba448f38afd10a151bfb45e90b53cf8103bfb1420131feff52f45af62661d9a5b3560f0a7f179a25697b0fc52f5a4d2daf477ac1750beed521ac8e47e8aee38fa4734837dcc93381807a6966a73a2befb093c8cad94a) 5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-hqHzDJEC3Y/8a9870d05e2b391d95142d60960f6ddbc7164c084872dc71c32a8c22412dcfe525beb25129dadfbb1a51c8d5aafed7c95158e8138b73af8549bd2aa1e5a76a8484924f4d91598b2177fcc6357719a7ea29dbb4188eef63fdf2ea8b2afa0b2140a0d26a12) 6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-LuGZY0J7ei/63ff936fa5662d5ad67d3019db86e266cfdcd223ed972592e639c178c4ffc9dca2fa1c97068bba911d40668c7432423fb6e8ba80cdd27a08d5e3fa270224b87b7110a387adcf425eb11af38afb699268f6eaf253376d9909e1b8d43860f805a3fcbd7f48) 7. 1. Изменения будут применены и Канал Проекта будет активирован, если: 2. 1. Агент обучен; 2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле); 3. будет доступен адрес Канал Проекта; 4. удастся зарегистрировать вебхук канала. 3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены. 8. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-p3UmfejP4I/1454c2bd8d28ec75ae3bca0c89125ff004c2fb5f932cf9480c7d9c203fb3e6788213062d05e632316a5f0105e8b3cd536156614a6571c45c3a2de43abf98036f6329d5960171c689f1e3e71a99c6054983fb9f6b26afaafcb2349a7d055a628b51f3d663) 9. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.\ ![image.png](https://codahosted.io/docs/_pM7PjYCmj/blobs/bl-egjmap52RY/a8f2ef845e0745061f84f6d8fcc8e3ca5dd903e1a95ddb017d717f46fdf3439c713af079f89028f52d187524c9f52f99125996e614860f5400c9123830be5a003319ccf9d9efbaa91b3a15a47eee5e989c7bc656459bae33a059388dbb84475e059b651f) ## Запросы из канала/сервера клиента к Агенту на Платформе Поддерживаемый протокол и метод:HTTPS, POST c content-type JSONEndpoint для получения запросов каналом агента:Запросы отправляются на Chatbot Webhook URL, указанный при подключении Канал Проекта.Формат endpoint (Chatbot Webhook URL): * Платформа развернута в облаке * Платформа развернута в контуре клиента https\://{server\_adress}/connector/chatapi/chatapi\_message/{token}/bot\_api\_webhookГде: * {server\_adress} — адрес Платформа, * {token} — токен авторизации. ### Общая структура запроса Вид тела запроса: ``` { "event": (string), "chat_id": (string), "visitor"(optional object): {   "id": (string),   "fields": {     Fields (object)   } }, "message": {   Message (object) }, "service_data"(optional object): {   Service data (object) }} ``` > Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, нажатие на кнопку) и может состоять из разных видов данных и полей. #### Тип события event event — тип события, которое Бот обрабатывает по определенной логике.Поддерживаемые типы событий: * new\_message — cобытие, которое передается Агенту каналом/сервером клиента и содержит сообщение от Собеседника. #### Идентификатор chat\_id chat\_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе. #### Объект Visitor Visitor — объект, содержащий информацию о Собеседнике.Вид Visitor: ``` {  "id": (string — псевдоуникальный идентификатор Собеседника, назначенный сервером клиента),  "fields": {    "name": (string),    "login": (string),    "phone": (string),    "email": (string),    "site": (string)  }} ``` Пример Visitor: ``` {  "id": "03e1c040d8214bfa8ccfbb053186a24a",  "fields": {    "name": "Иван",    "login": "ivan",    "phone": "+79991111111",    "email": "ivan@gmail.com",    "site": "https://site.com"  }} ``` #### Объект Message Message — объект, содержащий информацию, передаваемую в Агента для обработки. ``` {  "kind": (string — тип сообщения),  "text": (string — текст сообщения Собеседника),  "data": (JSON — данные о файле или нажатой кнопке)} ``` #### Поддерживаемый контент сообщений Ниже представлены примеры содержимого объекта Message для различных типов сообщений. * Текст Вид Message: ``` {"kind": "text","text": (string — message text)} ``` Пример Message: ``` {  "kind": "visitor",  "text": "Здравствуйте"} ``` * Файл Вид Message: ``` {"kind": "attachment","attachment": { "id": (string — file id), "content_type": (string — Internet Media Type), "url": (string — file URL) }} ``` Пример Message: ``` { "kind": "file_visitor",  "attachment": {    "id": "81f0488",    "content_type": "text",    "size": 560,    "url": "https://yoursite.com/content/file.txt"  }} ``` > При kind == attachment Публичный API "Chat API" получает данные о файле и преобразует их в текстовое сообщение для Агента в формате: file:{file\_type}|{file\_id}|{file\_url} . Сам файл Агент не выкачивает. * Нажатие на кнопку Вид Message: ``` {  "kind": "keyboard_response",  "keyboard_response": {    "button": {      "id": (string — идентификатор кнопки),      "text": (string — текст кнопки)    }  }} ``` \ Пример Message: ``` {  "kind": "keyboard_response",  "keyboard_response": {    "button": {      "id": "937bec4863154a2fb0889ff1320d1e2f",      "text": "Задать вопрос оператору"    }  }} ``` * Объект Service data Service data — любой объект, содержащий кастомную информацию, отправленную в Агента для обработки, например, для использования этой информации в Диалоге. Необязательный объект. ## Ответы на запросы из канала/сервера клиента к Агенту на Платформе ### Ответ Платформы при успешном запросе HTTP status: 200 OKBODY: ``` {  "result": "ok"} ``` ### Ответ Платформы при неуспешном запросе * Канал Агента неактивен или присутствует ошибка в токене Chatbot Webhook в URL * HTTP status: 400 Bad RequestBODY: ``` {    "error": "There is no active channel for received event."} ``` * Отсутствует обязательный параметр в теле запроса * HTTP status: 400 Bad Request * Указан некорректный URL * HTTP status: 404: Not Found * Некорректный JSON тела запроса: невалидный параметр event или kind * HTTP status: 200 OK ## Запросы от Платформы в канал/сервер клиента Ниже изложены форматы, примеры и описания запросов от Публичного API "Chat API" на сервер клиента. ### Базовый URL Запросы отправляются на URL-адрес клиентского сервера, прописанного в поле Channel Webhook: URL при подключении Канал Проекта.Формат URL-адреса: https\://{server\_address}/{method}, где: * {server\_adress} — адрес Платформа, * {method} — один из методов Публичного API "Chat API". \ Методы Публичного API "Chat API": * /send\_message — отправка сообщения Агентом Собеседнику. * /close\_chat — отправка события для закрытия Диалога. ### Авторизация на стороне клиента Авторизация может осуществляться через: * Уникальный URL Нужно указать URL, содержащий токен, в поле Channel webhook: URL при подключении Канал Проекта. При этом поле Channel webhook: Token заполнять не нужно. * Header Нужно указать токен авторизации в поле Channel webhook: Token при подключении Канал Проекта. Токен из поля Channel webhook: Token по умолчанию будет подставлен в header.Формат авторизации с помощью токена:Authorization: Token {token}Пример авторизации:Authorization: Token ac650a3c369a4b9599ad52ab71943712 ### Общая структура запроса Method: /send\_messageТип запроса: POSTContent-type: application/jsonQuery-string параметры: не нужныВид URL при отправке Агентом сообщения посетителю: ``` https://{server_adress}/send_message ``` где {server\_adress} — адрес Платформа.Вид тела запроса: ``` {    "message": Message (object),    "chat_id": (string)} ``` > Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, кнопки). #### Идентификатор chat\_id chat\_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе. #### Объект Message Message — объект, содержащий информацию, передаваемую в Агента для обработки. ``` {  "kind": (string — тип сообщения),  "text": (string — текст сообщения Агента),  "data": (JSON — данные о файле),  "buttons": (object — данные о кнопке/кнопках)} ``` #### Поддерживаемый контент сообщений Ниже представлены примеры содержимого объекта Message для различных типов сообщений. * Текст Вид Message: ``` {  "kind": "operator",  "text": (string — текст сообщения Агента)} ``` Пример Message: ``` {  "kind": "operator",  "text": "Здравствуйте, чем я могу вам помочь?" ``` * Файл Вид Message: ``` { "kind": "attachment", "attachment": {    "url": (string — file URL),    "type": (string — Internet Media Type),    "caption": (string — Attachment Caption. Optional field) }} ``` Пример Message: ``` {  "kind": "attachment",  "attachment": {    "url": "https://site.ru/wp-content/uploads/2019/04/diagram.png",    "type": "image/png",    "caption": "подпись"  }} ``` > Важно: отправка файлов происходит из слота . * Сообщение с кнопками Вид Message: ``` {  "kind": "keyboard",  "buttons": [    [      {        "text": (string — текст кнопки),        "id": (string — идентификатор кнопки)      }    ]  ]} ``` \ Пример Message: ``` {  "kind": "keyboard",  "buttons": [    [      {        "text": "Перевести на техподдержку",        "id": "fedc60c4dc0d4348b48b524d"      }    ],    [      {        "text": "Перевести на отдел продаж",        "id": "574f2caad88a41a7a2d6b667"      }    ]  ]} ``` > Важно: идентификатор кнопки может содержать только латинские буквы, цифры, символы дефиса и нижнего подчёркивания, и должен быть не более 24 символов в длину. ## Перевод на оператора Перевод на оператора не поддерживается с помощью Слота . Для выполнения перевода на оператора используется Внешний запрос с указанными характеристиками. > Важно: Публичный API "Chat API" имеет ограниченный набор возможностей. Если необходимо, чтобы Агент использовал другие методы со стороны API клиента, то работу с этими методами можно настроить внутри Агента при помощи конструктора запросов (Вкладка внешних запросов — External Requests). > Важно: Закрытие Диалога производится с помощью Слота Change Chat Mode. Диалог автоматически закрывается на стороне Платформа. ### Запрос для перевода на оператора Метод: /close\_chatТип запроса: POSTContent-type: application/jsonQuery-string параметры: не нужныURL: https\://{server\_address}/close\_chatВид тела запроса: ``` {    "chat_id": (string)} ``` ## Общение Взаимодействие с сервером клиента происходит через Публичный API "Chat API" согласно настройкам аккаунта в сервисе клиента. | Переменная | Конечный канал | Переменная в запросе из канала | | --------------------------- | -------------- | --------------------------------------------------- | | channel\_conversation\_id | Chat API | [chat.id](http://chat.id) | | channel\_visitor\_id | Chat API | [visitor.id](http://visitor.id) | | channel\_visitor\_firstname | Chat API | [visitor.fields.name](http://visitor.fields.name) | | channel\_visitor\_lastname | Chat API | нет | | channel\_visitor\_account | Chat API | visitor.fields.login | | channel\_visitor\_phone | Chat API | [visitor.fields.phone](http://visitor.fields.phone) | | channel\_visitor\_email | Chat API | [visitor.fields.email](http://visitor.fields.email) | | channel\_visitor\_source | Chat API | [visitor.fields.site](http://visitor.fields.site) | | channel\_service\_data | Chat API | service\_data | | Функционал общения | Конечный канал | Доступность в канале | Примечания | | ------------------------------------------------------------------------------ | -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | channel\_chat\_id | Chat API | Да | Формат:\\|chat\_api | | Сообщения дойдут до собеседника, если агент напишет первый в существующем чате | Chat API | На усмотрение канала | | | Кнопки | Chat API | Да | Нажатие на кнопку приходит как текст лейбла кнопки. | | Перевод на оператора | Chat API | Нет | Не поддерживается перевод на оператора через слот Change Chat Mode в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request. | | Передача файлов в виде файлов от Агента (Attachment) | Chat API | Нет | | | Передача файлов в виде ссылок от Агента (Attachment) | Chat API | Да | | | Получение файла от Собеседника в сценарий | Chat API | Да | Формат: file:Тип файла\|ID файла\|Ссылка на файл | | Доставка сообщений более 1000 символов от Агента до Собеседника | Chat API | На усмотрение канала | | | Использование маркдауна | Chat API | Нет | |