Вебхуки

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

Вебхуки — инструмент для оповещения об изменениях в системе, работают по протоколу HTTP. В Еадеске поддерживаются следующие события:

  • Новый диалог — срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог.

  • Обновление диалога — срабатывает при любом изменении ответственного или статуса.

  • Новое сообщение — срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя.

Для работы с вебхуками требуются навыки программирования!

Вебхуки POST-запросом передают данные на указанный вами сервер. В ответ необходимо ответить кодом 200, иначе хук считается не успешно отправленным и наш сервер отправляет запрос повторно. После пяти неудачных попыток, сервер перестаёт отправлять запросы.

Кастомные каналы доступны только на тарифе «Бизнес» и во время тестового периода. Смените тариф перед использованием.

Управление вебхуками

Чтобы получать вебхуки, необходимо из интерфейса Еадеска задать серверы, на которые будут отправляться запросы. Для этого перейдите в Настройка API и вебхуки и нажмите на «плюсик».

Заполните название, описание и выберите события, которые хотите отслеживать

Для добавления вебхука заполните поля:

  • Название — поможет быстро различать добавленные сервера.

  • URL — адрес вашего сервера, на который будут отправляться POST-запросы.

  • События — отметьте галочками события, на которые будут отправляться вебхуки.

Когда все поля будут заполнены — нажмите «Сохранить», чтобы добавить новый сервер.

Все добавленные серверы будут отображаться списком в этом же окне

Поддерживаемые типы событий и формат хуков

Вебхуки отправляются в формате JSON, объекты body (тело запроса) из POST-запроса по каждому типу описаны ниже.

1. Новый диалог

Событие «Новый диалог» срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог. Тело запроса:

id (строка) — уникальный идентификатор вебхука.

timestamp (число) — количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.

type (строка) — для идентификации типа хука, в данном случае - 'dialog creation'.

dialogId (строка) — id диалога в Еадеске.

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", сервис, который создал данный элемент контактных данных.

Пример данных из вебхука при создании нового сообщения:

{
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"
}
]
}
}

2. Обновление диалога

Это событие срабатывает при любом изменении ответственного или статуса. Тело запроса:

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 (строка) — id диалога в Еадеске.

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", сервис, который создал данный элемент контактных данных.

Пример данных из вебхука при создании нового сообщения:

{
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"
}
]
}
}

3. Новое сообщение

Событие «Новое сообщение» срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя. Тело запроса:

id (строка) — уникальный идентификатор вебхука.

timestamp (число) — количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь.

type (строка) — для идентификации типа хука, в данном случае message creation.

dialogId (строка) — id диалога в Еадеске.

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", сервис, который создал данный элемент контактных данных.

Пример данных из вебхука при создании нового сообщения:

{
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"
}
]
}
}