Вебхуки
Вебхуки срабатывают при изменениях в диалогах и новых сообщениях — это позволит запустить процессы вне Еадеска, например, создать задачу в таск-менеджере при новом диалоге.
Для работы с вебхуками требуются навыки программирования.
Вебхуки — инструмент для оповещения об изменениях в системе, работают по протоколу HTTP. В Еадеске поддерживаются следующие события:
- Новый диалог — срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог.
- Обновление диалога — срабатывает при любом изменении ответственного или статуса.
- Новое сообщение — срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя.
Вебхуки POST-запросом передают данные на указанный вами сервер. В ответ необходимо ответить кодом 200, иначе хук считается не успешно отправленным и наш сервер отправляет запрос повторно. После пяти неудачных попыток, сервер перестаёт отправлять запросы.
Вебхуки отправляются в формате JSON, объекты body (тело запроса) из POST-запроса по каждому типу описаны ниже.
Вебхуки доступны только на старших тарифах и во время тестового периода. Смените тариф перед использованием.
Чтобы получать вебхуки, необходимо из интерфейса Еадеска задать серверы, на которые будут отправляться запросы. Для этого перейдите в Настройка → API и вебхуки и нажмите на «плюсик».
Заполните название, описание и выберите события, которые хотите отслеживать
Для добавления вебхука заполните поля:
- Название — поможет быстро различать добавленные сервера.
- URL — адрес вашего сервера, на который будут отправляться POST-запросы.
- События — отметьте галочками события, на которые будут отправляться вебхуки.
Когда все поля будут заполнены — нажмите «Сохранить», чтобы добавить новый сервер.
Все добавленные серверы будут отображаться списком в этом же окне
Событие «Новый диалог» срабатывает, когда в Еадеске создаётся новый входящий или исходящий диалог. Пример данных из вебхука при создании:
{
id: '5fbfa99474a5f6001dfd288f',
timestamp: 1606396308700,
type: 'dialog creation',
dialogId: '5fbfa994013de80128fcb985',
url: 'https://app.yeahdesk.ru/conversations/5fbfa994013de80128fcb985',
title: 'New dialog from mail',
contactsId: '7e7d8003c7ab78001d6c895d',
origin: 'mail',
channelId: '6ebd003bda988200311229c8',
channelName: '[email protected]',
contact: {
_id: '5e7d8902d7ab78001d6c895c',
name: 'V5',
description: 'Nothing special.',
contacts: [{
id: "7e7d8003c7ab78001d6c895d"
origin: "mail",
service: "mail",
type: "mail",
value: "[email protected]"
}]
}
Тело запроса содержит следующие параметры.
Параметр | Тип | Описание |
id | строка | уникальный идентификатор вебхука |
timestamp | число | количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь. |
type | строка | для идентификации типа хука, в данном случае - 'dialog creation'. |
dialogId | строка | идентификатор диалога в Еадеске. |
url | строка | ссылка на диалог в Еадеске. |
title | строка | тема диалога |
contactsId | строка | id контактных данных, связанных с диалогом (автор) |
origin | строка | источник диалога, типы:
|
channelId | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка. |
channelName | строка | не уникальное название канала, помогает быстро ориентироваться между всеми каналами Еадеска. |
contact | объект | объект контактных данных, состоит из _id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных) |
contact.contacts | массив | состоит из объектов, каждый из которых содержит:
|
Это событие срабатывает при любом изменении статуса диалога, тегов или ответственного.
{
id: '5fbfa8ed74a5f6001dfd288d',
timestamp: 1606396141142,
type: 'status closed',
responsibleId: '5e44f63b39cfc7002029e40c',
dialogId: '5efafe33b3e6f32f31e109ae',
url: 'https://app.yeahdesk.ru/conversations/5efafe33b3e6f32f31e109ae',
title: 'Important client',
contactsId: '5efafe444df0b602071f7111',
origin: 'telegram',
status: 'closed',
channelId: '5qe900fbac7e4005dfd8d655',
channelName: 'Personal Telegram Channel',
closedBy: '5e44f63b39cfc7002029e40c',
userId: '5e44f63b39cfc7002029e40c',
labels: [ '2', '3' ],
contact: {
_id: '6dfafe333de1c602071f7110',
name: 'John Smith',
description: 'My old friend.',
contacts: [{
chat_id: "000000007",
id: "5efafe444df0b602071f7111",
origin: "telegram",
service: "telegram",
telegramId: 000000700,
type: "id",
value: "JohnSmith007"
}]
}
}
{
id: '5fbfa92974a5f6001dfd288e',
timestamp: 1606396201652,
type: 'status waiting',
responsibleId: '5e44f63b39cfc7002029e40c',
dialogId: '5efafe33b3e6f32f31e109ae',
url: 'https://app.yeahdesk.ru/conversations/5efafe33b3e6f32f31e109ae',
title: 'Important client',
contactsId: '5efafe444df0b602071f7111',
origin: 'telegram',
status: 'waiting',
channelId: '5qe900fbac7e4005dfd8d655',
channelName: 'Personal Telegram Channel',
waitingTill: '2020-11-28T13:10:00.000Z',
userId: '5e44f63b39cfc7002029e40c',
labels: [ '2', '3' ],
contact: {
_id: '6dfafe333de1c602071f7110',
name: 'John Smith',
description: 'My old friend.',
contacts: [{
chat_id: "000000007",
id: "5efafe444df0b602071f7111",
origin: "telegram",
service: "telegram",
telegramId: 000000700,
type: "id",
value: "JohnSmith007"
}]
}
}
{
id: '5fbfa9cb74a5f6001dfd2892',
timestamp: 1606396363030,
type: 'responsible assignment',
responsibleId: '5e44f63b39cfc7002029e40c',
responsibleUserName: 'Super-user',
dialogId: '5fbfa994013de80128fcb985',
url: 'https://app.yeahdesk.ru/conversations/5fbfa994013de80128fcb985',
title: 'New dialog from mail',
contactsId: '7e7d8003c7ab78001d6c895d',
origin: 'mail',
status: 'opened',
channelId: '6ebd003bda988200311229c8',
channelName: '[email protected]',
userId: '5e44f63b39cfc7002029e40c',
labels: [],
contact: {
_id: '5e7d8902d7ab78001d6c895c',
name: 'V5',
description: 'Nothing special.',
contacts: [{
id: "7e7d8003c7ab78001d6c895d"
origin: "mail",
service: "mail",
type: "mail",
value: "[email protected]"
}]
}
}
{
id: '5fbfa88f74a5f6001dfd288c',
timestamp: 1606396047533,
type: 'label added',
responsibleId: '5e44f63b39cfc7002029e40c',
dialogId: '5efafe33b3e6f32f31e109ae',
url: 'https://app.yeahdesk.ru/conversations/5efafe33b3e6f32f31e109ae',
title: 'Important client',
contactsId: '5efafe444df0b602071f7111',
origin: 'telegram',
status: 'opened',
channelId: '5qe900fbac7e4005dfd8d655',
channelName: 'Personal Telegram Channel',
userId: '5e44f63b39cfc7002029e40c',
labels: [ '2', '3' ],
addedLabel: '3',
contact: {
_id: '6dfafe333de1c602071f7110',
name: 'John Smith',
description: 'My old friend.',
contacts: [{
chat_id: "000000007",
id: "5efafe444df0b602071f7111",
origin: "telegram",
service: "telegram",
telegramId: 000000700,
type: "id",
value: "JohnSmith007"
}]
}
}
{
id: '5fbfa82b74a5f6001dfd288b',
timestamp: 1606395947160,
type: 'label removed',
responsibleId: '5e44f63b39cfc7002029e40c',
dialogId: '5efafe33b3e6f32f31e109ae',
url: 'https://app.yeahdesk.ru/conversations/5efafe33b3e6f32f31e109ae',
title: 'Important client',
contactsId: '5efafe444df0b602071f7111',
origin: 'telegram',
status: 'opened',
channelId: '5qe900fbac7e4005dfd8d655',
channelName: 'Personal Telegram Channel',
userId: '5e44f63b39cfc7002029e40c',
labels: [ '2' ],
removedLabel: '3',
contact: {
_id: '6dfafe333de1c602071f7110',
name: 'John Smith',
description: 'My old friend.',
contacts: [{
chat_id: "000000007",
id: "5efafe444df0b602071f7111",
origin: "telegram",
service: "telegram",
telegramId: 000000700,
type: "id",
value: "JohnSmith007"
}]
}
}
Тело запроса содержит следующие параметры.
Параметр | Тип | Описание |
id | строка | уникальный идентификатор вебхука. |
timestamp | число | количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь. |
type | строка | для идентификации типа хука, в данном случае может принимать значения:
|
responsibleId | строка | id ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного. |
responsibleUserName | строка | имя ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного. |
dialogId | строка | идентификатор диалога в Еадеске. |
url | строка | ссылка на диалог в Еадеске. |
title | строка | тема диалога. |
contactsId | строка | id контактных данных, связанных с диалогом (автор). |
origin | строка | источник диалога, типы:
|
status | строка | статус диалога. Необязательное поле, присутствует в хуках, связанных со сменой статуса. |
channelId | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка. |
channelName | строка | не уникальное название канала, помогает быстро ориентироваться между все ми каналами Еадеска. |
labels | массив | перечень всех актуальных тегов в этом диалоге. |
addedLabel | строка | один добавленный тег. |
removedLabel | строка | один удалённый тег. |
waitingTill | строка | дата в формате ISO, при достижении которой статус диалога будет сменен на 'opened'. Необязательное поле, присутствует в хуках, связанных с переводом диалога в ожидание. |
closedBy | строка | id пользователя, закрывшего диалог, в Еадеске. Необязательное поле, присутствует в хуках, связанных с закрытием диалога. |
contact | объект | объект контактных данных, состоит из _id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных). |
contact.contacts | массив | состоит из объектов, каждый из которых содержит:
|
Событие «Новое сообщение» срабатывает, когда в существующем диалоге создаётся новое входящее или исходящее сообщение клиента или пользователя. Пример данных из вебхука при создании нового входящего сообщения:
{
id: '5fbfa99474a5f6001dfd2890',
timestamp: 1606396308704,
type: 'message creation',
dialogId: '5fbfa994013de80128fcb985',
url: 'https://app.yeahdesk.ru/conversations/5fbfa994013de80128fcb985',
title: 'New dialog from mail',
contactsId: '7e7d8003c7ab78001d6c895d',
origin: 'mail',
channelId: '6ebd003bda988200311229c8',
channelName: '[email protected]',
message: {
_id: '5fbfa994013de80128fcb986',
type: 'message',
text: 'Hello!\n\n',
html: '',
direction: 'in'
},
contact: {
_id: '5e7d8902d7ab78001d6c895c',
name: 'V5',
description: 'Nothing special.',
contacts: [{
id: "7e7d8003c7ab78001d6c895d"
origin: "mail",
service: "mail",
type: "mail",
value: "[email protected]"
}]
}
}
Пример для исходящего сообщения:
{
id: '5fbfa9ca74a5f6001dfd2891',
timestamp: 1606396362475,
type: 'message creation',
dialogId: '5fbfa994013de80128fcb985',
url: 'https://app.yeahdesk.ru/conversations/5fbfa994013de80128fcb985',
title: '',
contactsId: '7e7d8003c7ab78001d6c895d',
origin: 'mail',
channelId: '6ebd003bda988200311229c8',
channelName: '[email protected]',
message: {
_id: '5fbfa9ca013de80128fcb988',
type: 'message',
text: 'Answer \n',
html: '<p class="md-block-unstyled" style="margin: 0px !important;">Answer</p><br>'
},
messageAuthor: { id: '5e44f63b39cfc7002029e40c', type: 'user', name: 'Super-user' },
contact: {
_id: '5e7d8902d7ab78001d6c895c',
name: 'V5',
description: 'Nothing special.',
contacts: [{
id: "7e7d8003c7ab78001d6c895d"
origin: "mail",
service: "mail",
type: "mail",
value: "[email protected]"
}]
}
}
Тело запроса содержит следующие параметры.
Параметр | Тип | Описание |
id | строка | уникальный идентификатор вебхука. |
timestamp | число | количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC. Создается в момент конструирования данных перед их отправкой в очередь. |
type | строка | для идентификации типа хука, в дан ном случае message creation. |
dialogId | строка | идентификатор диалога в Еадеске. |
url | строка | ссылка на диалог в Еадеске. |
title | строка | тема диалога. |
contactsId | строка | id контактных данных, связанных с диалогом (автор). |
origin | строка | источник диалога, типы:
|
channelId | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка. |
channelName | строка | не уникальное название канала, помогает быстро ориентироваться между всеми каналами Еадеска. |
message | объект | объект сообщения, содержит в себе поля:
|
messageAuthor | объект | объект пользователя, который инициировал создание сообщения. Состоит из:
|
contact | объект | объект контактных данных, состоит из:
|
contact.contacts | массив | состоит из объектов, каждый из которых содержит:
|
Last modified 2yr ago