> For the complete documentation index, see [llms.txt](https://help.yeahdesk.ru/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.yeahdesk.ru/docs/for-developers/custom-channels.md). # Кастомный канал Кастомный канал позволяет подключить к Еадеску любой сервис, для которого ещё нет готовой интеграции. Это может быть сторонняя площадка, ваше веб-приложение, мобильное приложение или любой другой источник сообщений от ваших клиентов. Например, вам нужны личные сообщения из Авито и у вас есть парсер, тогда вы с помощью кастомного канала передаёте нам информацию о входящих личных сообщениях в Авито вместе с контактной информацией по клиенту. Кастомный канал создаст новый диалог или прикрепит сообщение к существующему, создаст клиента или обновит его данные, а Еадеск будет вести историю всех сообщений. Когда ваш сотрудник ответит клиенту из интерфейса Еадеска — воспользуйтесь [вебхуками](/docs/for-developers/webhooks.md), чтобы отследить событие и отправить ему ответ через ваш парсер/скрипт. ### Создание кастомного канала {% hint style="warning" %} Кастомные каналы доступны только на [старших тарифах](https://yeahdesk.ru/pricing) и во время тестового периода. Смените тариф перед использованием. {% endhint %} Для начала работы создайте первый кастомный канал, перейдите в [*Настройка* → *Каналы*](https://app.yeahdesk.ru/settings/channels/custom/new) и нажмите на плюс, выберите «Другой». ![Перейдите в настройку и добавьте канал с типом «Другой»](/files/-LgZT6itqFw2jRHuQa5C) Затем укажите название, оно ни на что не влияет и помогает вам узнать канал среди прочих. ![Заполните название канала и нажмите «Подключить»](/files/-LgZTx33fcqSj2rVNraC) После создания кастомного канала вы получаете эндпоинт, на который нужно отправлять POST-запросы для создания сообщений. Пример эндпоинта: ``` https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e ``` ![Используйте полученный эндпоинт для отправки запросов](/files/-LgZVSnsV_XjNPzXq2WB) ### Создание диалогов Когда канал создан и вы получили эндпоинт, можно отправлять на него запросы. В URL для авторизации необходимо добавить ключ API через параметр `?token=1234567890`. Тогда URL запроса целиком будет выглядеть так: ``` https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e?token=1234567890 ``` [Подробнее об авторизации](/docs/for-developers/http-api/api-auth.md) в документации. Тело запроса содержит следующие параметры: {% hint style="info" %} Все параметры необязательные, если не указано обратное. {% endhint %} {% hint style="info" %} Если одновременно переданы оба параметра **dialog\_id** и **reference**, то параметр reference игнорируется. {% endhint %} | Параметр | Описание | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | dialog\_id | идентификатор диалога в Еадеске, куда должно быть помещено сообщение. Если не указано, создаёт новый диалог. | | reference | если параметр передан, система ищет диалог с таким же значением поля reference и сообщение записывается в найденный диалог. Если диалог не найден, то он создается, а в поле reference записывается переданное значение. | | dialog\_title | заголовок диалога, используется при создании или обновлении диалога. | | timestamp | (число) — количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Значением будет считаться временем создания сообщения, если не передано — используется `Date.now()` | | text | неформатированный текст сообщения. | | html | текст сообщения в формате html. | | integration\_data | произвольная строка, которая сохраняется в сообщении. Не интерпретируется Еадеск, но передаётся в вебхуках и может использоваться для интеграции. | | attachments | массив объектов: `{ url, size, name, mimeType, }`. | | contact\_object | (обязательный) — объект контактных данных, состоит из \_id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных). | | contacts\_id | (обязательный) — содержит всю структуру [контакта](/docs/for-developers/http-api/contacts.md), взаимоисключающий параметр с contact. | При создании или продолжении диалога одновременно производится создание или обновление контактов. ### Обновление контактных данных Внутри каждого клиента существуют контактные данные, например, Вася Пупкин с номером +79876543210. В этом случае Вася Пупкин — это контакт (клиент), а его номер — контактные данные. При отправке запроса можно обновить эти контактные данные. Для этого передайте в запросе contacts\_id. **contacts\_id** — это массив объектов, каждый из которых содержит: * id — уникальный идентификатор элемента контактных данных. * value — например, "". * type — например "mail", необходимый для интерпретации value. * service — например "mail", сервис для которого используется данное value. * origin — например "chatra", сервис, который создал данный элемент контактных данных. Пример контактных данных для кастомного канала: ``` "id" : "5c52bf6f3e308a00367a7fae", "value" : "phrw1oc544j18buxazs6tlg7q68vdfyin1emk06", "type" : "id", "service" : "custom", "origin" : "custom" ``` Примечания: * При передаче параметра contacts\_id требуется, чтобы контактные данные с таким id существовали и service == "custom", иначе возвращается ошибка. * При передаче параметра *contact\_object* (всей структуры контакта), так же требуется, чтобы в массиве контактных данных существовали данные с service == "custom". * Перед созданием нового контакта, алгоритм пытается найти существующий контакт с подходящими контактными данными и сделать их объединение. ### Примеры кода на Node.js Ниже приведены примеры на JavaScript для создания нового диалога и добавления новых сообщений в существующий в разных вариантах. ```javascript const rp = require('request-promise-native'); const requestUrl = 'https://app.yeahdesk.ru/api/custom-channel/message/6034f9eff21d1a0011371e7c?token=abe629106c851'; const makeIncomingMessageRequest = (body) => { rp(requestUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body, json: true, }); }; (() => { // Создание нового диалога (передача контакта целиком) const newDialogWithContactBody = { dialog_title: `Dialog ${Date.now()}`, text: 'Hello there!', contact_object: { _id: '123strongid', name: 'Peter', description: 'New client', contacts: [{ value: '34666123456', service: 'custom' }], }, integration_data: { messageId: '62397B58E3E0B', }, }; // Создание нового диалога (передача id контакта) const newDialogWithContactsIdBody = { dialog_title: `Dialog ${Date.now()}`, text: 'Hello there!', contacts_id: '6049ad4a75f4100012a682a9', integration_data: { messageId: '62397B58E3E0B', }, }; // Добавление новых сообщений в существующий диалог (передача контакта целиком) const newMessageIntoExistingDialogWithContactBody = { dialog_id: '6049adc740e3590012d3a193', text: 'Hello there!', contact_object: { _id: '123strongid', name: 'Peter', description: 'New client', contacts: [{ value: '34666123456', service: 'custom' }], }, integration_data: { messageId: '62397B58E3E0B', }, }; // Добавление новых сообщений в существующий диалог (передача id контакта) const newMessageIntoExistingDialogWithContactsIdBody = { dialog_id: '6049adc740e3590012d3a193', contacts_id: '6049ad4a75f4100012a682a9', text: 'Hello there!', integration_data: { messageId: '62397B58E3E0B', }, }; // Выберите нужный объект тела запроса const body = {}; makeIncomingMessageRequest(body); })(); ``` ### Возвращаемые ошибки В случае, если наш сервер не может обработать ваш запрос — он ответит ошибкой. Перечень ошибок и комментарии к ним. ``` 400 E_CONTACT_INFO_REQUIRED — необходимо передать контактную информацию по клиенту 400 E_CUSTOM_CONTACTS_REQUIRED — необходимы контактные данные с service == "custom" 400 E_CONTACTS_VALUE_REQUIRED — необходимо заполнять поля с контактными данными клиента 400 E_MALFORMED_CONTACT_ID — передан неправильный или несуществующий ID контакта 401 E_INVALID_TOKEN — недействительный токен, проверьте и замените на актуальный 403 E_CHANNEL_NOT_ENABLED — канал выключен, активируйте в настройках для продолжения 403 E_CHANNEL_DELETED — канал удалён и токен недействителен, создайте новый канал 404 E_CONTACT_NOT_FOUND — клиент не найден 404 E_CONTACT_DELETED — контакт удалён 404 E_DIALOG_NOT_FOUND — диалог не найден ```