# Универсальный коннектор 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 | Нет | |
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://chatme-ai-4.gitbook.io/docs/kak-vyvesti-agenta-v-konechnye-kanaly/universalnyi-konnektor-chat-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.