Вебхуки

Вебхуки срабатывают при изменениях в диалогах и новых сообщениях — это позволит запустить процессы вне Еадеска, например, создать задачу в таск-менеджере при новом диалоге.

Для работы с вебхуками требуются навыки программирования.
Вебхуки — инструмент для оповещения об изменениях в системе, работают по протоколу HTTP. В Еадеске поддерживаются следующие события:
Новый диалог — срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог.
Обновление диалога — срабатывает при любом изменении ответственного или статуса. 
Новое сообщение — срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя. 
Вебхуки POST-запросом передают данные на указанный вами сервер. В ответ необходимо ответить кодом 200, иначе хук считается не успешно отправленным и наш сервер отправляет запрос повторно. После пяти неудачных попыток, сервер перестаёт отправлять запросы.
Вебхуки отправляются в формате JSON, объекты body (тело запроса) из POST-запроса по каждому типу описаны ниже.
Управление вебхуками
Вебхуки доступны только на тарифе «Бизнес» и во время тестового периода. Смените тариф перед использованием. 
Чтобы получать вебхуки, необходимо из интерфейса Еадеска задать серверы, на которые будут отправляться запросы. Для этого перейдите в Настройка → API и вебхуки и нажмите на «плюсик».
Заполните название, описание и выберите события, которые хотите отслеживать
Для добавления вебхука заполните поля:
Название — поможет быстро различать добавленные сервера.
URL — адрес вашего сервера, на который будут отправляться POST-запросы.
События — отметьте галочками события, на которые будут отправляться вебхуки.
Когда все поля будут заполнены — нажмите «Сохранить», чтобы добавить новый сервер.
Все добавленные серверы будут отображаться списком в этом же окне
1. Новый диалог
Событие «Новый диалог» срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог. Пример данных из вебхука при создании:
{
 id: "5cf28243c24fc501e3cd7812",
 timestamp: 1559396931454,
 type: "dialog creation",
 dialogId: "5cf282438794321c3f86720b",
 url: "http://app.yeahdesk.ru/conversations/5cf282438794321c3f86720b",
 title: "Harr",
 contactsId: "5cc6d33a48cd60001d8055cc",
 origin: "mail",
 contact: {
   _id: "5cc6d33a48cd60001d8055cb",
   name: "Victor",
   description: "",
   contacts: [
     {
       id: "5cc6d33a48cd60001d8055cc",
       value: "vic******onos@gmail.com",
       type: "mail",
       service: "mail",
       origin: "mail"
     }
   ]
 }
}
Тело запроса содержит следующие параметры.
Параметр
Тип
Описание
id
строка
уникальный идентификатор вебхука
timestamp 
число
количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.
type 
строка
для идентификации типа хука, в данном случае - 'dialog creation'.
dialogId 
строка
идентификатор диалога в Еадеске.
url 
строка
ссылка на диалог в Еадеске.
title 
строка
тема диалога
contactsId 
строка
id контактных данных, связанных с диалогом (автор)
origin 
строка
​
источник диалога, типы:
mail для диалога из электронной очты, 
chatra — Чатра, 
pbx — телефония, 
skype — Скайп, 
fb — Фейсбук,
ig — Инстаграм, 
telegram — Телеграм,
whatsapp — Вотсап,
vk — ВКонтакте,
custom — кастомный канал,
demo — служебный канал Еадеска.
contact 
объект
объект контактных данных, состоит из _id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных)
contact.contacts
массив
​
состоит из объектов, каждый из которых содержит:
id — уникальный идентификатор элемента контактных данных.
value — например, "hello@yandex.ru".
type — например "mail", необходимый для интерпретации value.
service — например "mail", сервис для которого используется данное value.
origin — например "chatra", сервис, который создал данный элемент контактных данных
2. Обновление диалога
Это событие срабатывает при любом изменении ответственного или статуса. Пример данных из вебхука:
{
 id: "5cf28223c24fc501e3cd7811",
 timestamp: 1559396899008,
 type: "status closed",
 dialogId: "5cf281028794321c3f867204",
 url: "http://app.yeahdesk.ru/conversations/5cf281028794321c3f867204",
 title: "New Dialog Hook",
 contactsId: "5cc6d33a48cd60001d8055cc",
 origin: "mail",
 status: "closed",
 closedBy: "5cc6c4cd4a9285001ef15f5b",
 contact: {
   _id: "5cc6d33a48cd60001d8055cb",
   name: "Victor",
   description: "",
   contacts: [
     {
       id: "5cc6d33a48cd60001d8055cc",
       value: "vic******onos@gmail.com",
       type: "mail",
       service: "mail",
       origin: "mail"
     }
   ]
 }
}
Тело запроса содержит следующие параметры.
Параметр
Тип
Описание
id
строка
уникальный идентификатор вебхука.
timestamp
число
количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.
type
строка
​
для идентификации типа хука, в данном случае может принимать значения:
'status opened': true.
'status closed': true.
'status waiting': true.
'dialog reopening': true.
'responsible assignment': 'Установлен ответственный'.
'responsible reset': 'Сброшен ответственный'.
'responsible change': 'Сменен ответственный'.
responsibleId
строка
id ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного.
responsibleUserName
строка
имя ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного.
dialogId
строка
идентификатор диалога в Еадеске.
url 
строка
ссылка на диалог в Еадеске.
title 
строка
тема диалога.
contactsId
строка
id контактных данных, связанных с диалогом (автор).
origin
строка
​
источник диалога, типы:
mail для диалога из электронной очты, 
chatra — Чатра, 
pbx — телефония, 
skype — Скайп, 
fb — Фейсбук,
ig — Инстаграм, 
telegram — Телеграм,
whatsapp — Вотсап,
vk — ВКонтакте,
custom — кастомный канал,
demo — служебный канал Еадеска.
status 
строка
статус диалога. Необязательное поле, присутствует в хуках, связанных со сменой статуса.
waitingTill 
строка
дата в формате ISO, при достижении которой статус диалога будет сменен на 'opened'. Необязательное поле, присутствует в хуках, связанных с переводом диалога в ожидание.
closedBy 
строка
id пользователя, закрывшего диалог, в Еадеске. Необязательное поле, присутствует в хуках, связанных с закрытием диалога.
contact 
объект
объект контактных данных, состоит из _id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных).
contact.contacts
массив
​
состоит из объектов, каждый из которых содержит:
id — уникальный идентификатор элемента контактных данных.
value — например, "hello@yandex.ru".
type — например "mail", необходимый для интерпретации value.
service — например "mail", сервис для которого используется данное value.
origin — например "chatra", сервис, который создал данный элемент контактных данных.
3. Новое сообщение
Событие «Новое сообщение» срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя. Пример данных из вебхука при создании нового сообщения:
{
 id: "5cf28249c24fc501e3cd7814",
 timestamp: 1559396937232,
 type: "message creation",
 dialogId: "5cf282438794321c3f86720b",
 url: "http://app.yeahdesk.ru/conversations/5cf282438794321c3f86720b",
 title: "",
 contactsId: "5cc6d33a48cd60001d8055cc",
 origin: "mail",
 message: {
   _id: "5cf282498794321c3f86720e",
   text: "kk \n ",
   html: "
kk
​
"
 },
 contact: {
   _id: "5cc6d33a48cd60001d8055cb",
   name: "Victor",
   description: "",
   contacts: [
     {
       id: "5cc6d33a48cd60001d8055cc",
       value: "vic******onos@gmail.com",
       type: "mail",
       service: "mail",
       origin: "mail"
     }
   ]
 }
}
Тело запроса содержит следующие параметры.
Параметр
Тип
Описание
id 
строка
уникальный идентификатор вебхука.
timestamp 
число
количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.
type 
строка
для идентификации типа хука, в данном случае message creation.
dialogId 
строка
идентификатор диалога в Еадеске.
url 
строка
ссылка на диалог в Еадеске.
title 
строка
тема диалога.
contactsId 
строка
id контактных данных, связанных с диалогом (автор).
origin 
строка
​
источник диалога, типы:
mail для диалога из электронной очты, 
chatra — Чатра, 
pbx — телефония, 
skype — Скайп, 
fb — Фейсбук,
ig — Инстаграм, 
telegram — Телеграм,
whatsapp — Вотсап,
vk — ВКонтакте,
custom — кастомный канал,
demo — служебный канал Еадеска.
message 
объект 
​
объект сообщения, содержит в себе поля:
_id (строка) — id сообщения в Еадеске,
text (строка) — сообщение в текстовой форме. Необязательное поле (пример - в некоторых мессенджерах вложение передается как отдельное сообщение).
html (строка) — сообщение с форматированием. Необязательное поле (практически все мессенджеры не позволяют применять форматирование).
direction (строка) — направление сообщения (in/out). Необязательное поле, его отсутствие означает direction: 'out'.
attachments (число) — количество приложенных файлов.
contact 
объект 
объект контактных данных, состоит из:
_id (строка)
name (строка)
description (строка, необязательное поле)
contacts (массив контактных данных)
contact.contacts
массив
​
состоит из объектов, каждый из которых содержит:
id — уникальный идентификатор элемента контактных данных.
value — например, "hello@yandex.ru".
type — например "mail", необходимый для интерпретации value.
service — например "mail", сервис для которого используется данное value.
origin — например "chatra", сервис, который создал данный элемент контактных данных.

Руководство по обработке обращений

Next - Разработчикам

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

Last updated 6 months ago

Параметр	Тип	Описание
id	строка	уникальный идентификатор вебхука
timestamp	число	количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.
type	строка	для идентификации типа хука, в данном случае - 'dialog creation'.
dialogId	строка	идентификатор диалога в Еадеске.
url	строка	ссылка на диалог в Еадеске.
title	строка	тема диалога
contactsId	строка	id контактных данных, связанных с диалогом (автор)
origin	строка	источник диалога, типы: mail для диалога из электронной очты, chatra — Чатра, pbx — телефония, skype — Скайп, fb — Фейсбук, ig — Инстаграм, telegram — Телеграм, whatsapp — Вотсап, vk — ВКонтакте, custom — кастомный канал, demo — служебный канал Еадеска.
contact	объект	объект контактных данных, состоит из _id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных)
contact.contacts	массив	состоит из объектов, каждый из которых содержит: id — уникальный идентификатор элемента контактных данных. value — например, "hello@yandex.ru". type — например "mail", необходимый для интерпретации value. service — например "mail", сервис для которого используется данное value. origin — например "chatra", сервис, который создал данный элемент контактных данных