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

Кастомный канал позволяет подключить к Еадеску любой сервис, для которого ещё нет готовой интеграции. Это может быть сторонняя площадка, ваше веб-приложение, мобильное приложение или любой другой источник сообщений от ваших клиентов.
Например, вам нужны личные сообщения из Авито и у вас есть парсер, тогда вы с помощью кастомного канала передаёте нам информацию о входящих личных сообщениях в Авито вместе с контактной информацией по клиенту. Кастомный канал создаст новый диалог или прикрепит сообщение к существующему, создаст клиента или обновит его данные, а Еадеск будет вести историю всех сообщений.
Когда ваш сотрудник ответит клиенту из интерфейса Еадеска — воспользуйтесь вебхуками, чтобы отследить событие и отправить ему ответ через ваш парсер/скрипт. 
Создание кастомного канала
Кастомные каналы доступны только на старших тарифах и во время тестового периода. Смените тариф перед использованием. 
Для начала работы создайте первый кастомный канал, перейдите в Настройка → Каналы и нажмите на плюс, выберите «Другой».
Перейдите в настройку и добавьте канал с типом «Другой»
Затем укажите название, оно ни на что не влияет и помогает вам узнать канал среди прочих. 
Заполните название канала и нажмите «Подключить»
После создания кастомного канала вы получаете эндпоинт, на который нужно отправлять POST-запросы для создания сообщений. Пример эндпоинта:
1
https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e
Copied!
Используйте полученный эндпоинт для отправки запросов
Создание диалогов
Когда канал создан и вы получили эндпоинт, можно отправлять на него запросы. В URL для авторизации необходимо добавить ключ API через параметр ?token=1234567890. Тогда URL запроса целиком будет выглядеть так:
1
https://api.yeahdesk.ru/api/custom-channel/message/5cc2f62000568c04afdc0c5e?token=1234567890
Copied!
​Подробнее об авторизации в документации. Тело запроса содержит следующие параметры:
Все параметры необязательные, если не указано обратное.
Если одновременно переданы оба параметра dialog_id и reference, то параметр reference игнорируется.
Параметр
Описание
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
(обязательный) — содержит всю структуру контакта, взаимоисключающий параметр с contact. 
При создании или продолжении диалога одновременно производится создание или обновление контактов.
Обновление контактных данных
Внутри каждого клиента существуют контактные данные, например, Вася Пупкин с номером +79876543210. В этом случае Вася Пупкин — это контакт (клиент), а его номер — контактные данные. При отправке запроса можно обновить эти контактные данные. Для этого передайте в запросе contacts_id.
contacts_id — это массив объектов, каждый из которых содержит:
id — уникальный идентификатор элемента контактных данных.
value — например, "[email protected]".
type — например "mail", необходимый для интерпретации value.
service — например "mail", сервис для которого используется данное value.
origin — например "chatra", сервис, который создал данный элемент контактных данных.
Пример контактных данных для кастомного канала:
1
"id" :  "5c52bf6f3e308a00367a7fae",
2
"value" : "phrw1oc544j18buxazs6tlg7q68vdfyin1emk06",
3
"type" : "id",
4
"service" : "custom",
5
"origin" : "custom"
Copied!
Примечания:
При передаче параметра contacts_id требуется, чтобы контактные данные с таким id существовали и service == "custom", иначе возвращается ошибка.
При передаче параметра contact_object (всей структуры контакта), так же требуется, чтобы в массиве контактных данных существовали данные с service == "custom".
Перед созданием нового контакта, алгоритм пытается найти существующий контакт с подходящими контактными данными и сделать их объединение.
Примеры кода на Node.js
Ниже приведены примеры на JavaScript для создания нового диалога и добавления новых сообщений в существующий в разных вариантах.
1
const rp = require('request-promise-native');
2
​
3
const requestUrl =
4
  'https://app.yeahdesk.ru/api/custom-channel/message/6034f9eff21d1a0011371e7c?token=abe629106c851';
5
​
6
const makeIncomingMessageRequest = (body) => {
7
  rp(requestUrl, {
8
    method: 'POST',
9
    headers: {
10
      'Content-Type': 'application/json',
11
    },
12
    body,
13
    json: true,
14
  });
15
};
16
​
17
(() => {
18
  // Создание нового диалога (передача контакта целиком)
19
  const newDialogWithContactBody = {
20
    dialog_title: `Dialog ${Date.now()}`,
21
    text: 'Hello there!',
22
    contact_object: {
23
      _id: '123strongid',
24
      name: 'Peter',
25
      description: 'New client',
26
      contacts: [{ value: '34666123456', service: 'custom' }],
27
    },
28
    integration_data: {
29
      messageId: '62397B58E3E0B',
30
    },
31
  };
32
​
33
  // Создание нового диалога (передача id контакта)
34
  const newDialogWithContactsIdBody = {
35
    dialog_title: `Dialog ${Date.now()}`,
36
    text: 'Hello there!',
37
    contacts_id: '6049ad4a75f4100012a682a9',
38
    integration_data: {
39
      messageId: '62397B58E3E0B',
40
    },
41
  };
42
​
43
  // Добавление новых сообщений в существующий диалог (передача контакта целиком)
44
  const newMessageIntoExistingDialogWithContactBody = {
45
    dialog_id: '6049adc740e3590012d3a193',
46
    text: 'Hello there!',
47
    contact_object: {
48
      _id: '123strongid',
49
      name: 'Peter',
50
      description: 'New client',
51
      contacts: [{ value: '34666123456', service: 'custom' }],
52
    },
53
    integration_data: {
54
      messageId: '62397B58E3E0B',
55
    },
56
  };
57
​
58
  // Добавление новых сообщений в существующий диалог (передача id контакта)
59
  const newMessageIntoExistingDialogWithContactsIdBody = {
60
    dialog_id: '6049adc740e3590012d3a193',
61
    contacts_id: '6049ad4a75f4100012a682a9',
62
    text: 'Hello there!',
63
    integration_data: {
64
      messageId: '62397B58E3E0B',
65
    },
66
  };
67
​
68
  // Выберите нужный объект тела запроса
69
  const body = {};
70
​
71
  makeIncomingMessageRequest(body);
72
})();
Copied!
Возвращаемые ошибки
В случае, если наш сервер не может обработать ваш запрос — он ответит ошибкой. Перечень ошибок и комментарии к ним. 
1
400 E_CONTACT_INFO_REQUIRED — необходимо передать контактную информацию по клиенту
2
400 E_CUSTOM_CONTACTS_REQUIRED — необходимы контактные данные с service == "custom"
3
400 E_CONTACTS_VALUE_REQUIRED — необходимо заполнять поля с контактными данными клиента
4
400 E_MALFORMED_CONTACT_ID — передан неправильный или несуществующий ID контакта
5
​
6
401 E_INVALID_TOKEN — недействительный токен, проверьте и замените на актуальный
7
​
8
403 E_CHANNEL_NOT_ENABLED — канал выключен, активируйте в настройках для продолжения
9
403 E_CHANNEL_DELETED — канал удалён и токен недействителен, создайте новый канал
10
​
11
404 E_CONTACT_NOT_FOUND — клиент не найден
12
404 E_CONTACT_DELETED — контакт удалён
13
404 E_DIALOG_NOT_FOUND — диалог не найден
Copied!
Разработчикам - Previous
Вебхуки
Next - Разработчикам
HTTP API
Last modified 7mo ago
Copy link
Contents
Создание кастомного канала
Создание диалогов
Обновление контактных данных
Примеры кода на Node.js
Возвращаемые ошибки