# Кастомный канал Кастомный канал позволяет подключить к Еадеску любой сервис, для которого ещё нет готовой интеграции. Это может быть сторонняя площадка, ваше веб-приложение, мобильное приложение или любой другой источник сообщений от ваших клиентов. Например, вам нужны личные сообщения из Авито и у вас есть парсер, тогда вы с помощью кастомного канала передаёте нам информацию о входящих личных сообщениях в Авито вместе с контактной информацией по клиенту. Кастомный канал создаст новый диалог или прикрепит сообщение к существующему, создаст клиента или обновит его данные, а Еадеск будет вести историю всех сообщений. Когда ваш сотрудник ответит клиенту из интерфейса Еадеска — воспользуйтесь [вебхуками](/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 — диалог не найден ``` --- # 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://help.yeahdesk.ru/docs/for-developers/custom-channels.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.