Кастомный канал

Кастомный канал позволяет подключить к Еадеску любой сервис, для которого ещё нет готовой интеграции. Это может быть сторонняя площадка, ваше веб-приложение, мобильное приложение или любой другой источник сообщений от ваших клиентов.

Например, вам нужны личные сообщения из Авито и у вас есть парсер, тогда вы с помощью кастомного канала передаёте нам информацию о входящих личных сообщениях в Авито вместе с контактной информацией по клиенту. Кастомный канал создаст новый диалог или прикрепит сообщение к существующему, создаст клиента или обновит его данные, а Еадеск будет вести историю всех сообщений.

Когда ваш сотрудник ответит клиенту из интерфейса Еадеска — воспользуйтесь вебхуками, чтобы отследить событие и отправить ему ответ через ваш парсер/скрипт.

Создание кастомного канала

Для начала работы создайте первый кастомный канал, перейдите в Настройка → Каналы и нажмите на плюс, выберите «Другой».

Затем укажите название, оно ни на что не влияет и помогает вам узнать канал среди прочих.

После создания кастомного канала вы получаете эндпоинт, на который нужно отправлять POST-запросы для создания сообщений. Пример эндпоинта:

https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e

Создание диалогов

Когда канал создан и вы получили эндпоинт, можно отправлять на него запросы. В URL для авторизации необходимо добавить ключ API через параметр ?token=1234567890. Тогда URL запроса целиком будет выглядеть так:

https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e?token=1234567890

​Подробнее об авторизации в документации. Тело запроса содержит следующие параметры:

При создании или продолжении диалога одновременно производится создание или обновление контактов.

Обновление контактных данных

Внутри каждого клиента существуют контактные данные, например, Вася Пупкин с номером +79876543210. В этом случае Вася Пупкин — это контакт (клиент), а его номер — контактные данные. При отправке запроса можно обновить эти контактные данные. Для этого передайте в запросе contacts_id.

contacts_id — это массив объектов, каждый из которых содержит:

• id — уникальный идентификатор элемента контактных данных.

• value — например, "[email protected]".

• 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 для создания нового диалога и добавления новых сообщений в существующий в разных вариантах.

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 — диалог не найден