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