Вебхуки

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

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

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

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

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

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

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

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

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

Вебхуки доступны только на старших тарифах и во время тестового периода. Смените тариф перед использованием.

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

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

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

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

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

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

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

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

{
  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: 'vasyapupkin007@yandex.ru',
  contact: {
    _id: '5e7d8902d7ab78001d6c895c',
    name: 'V5',
    description: 'Nothing special.',
    contacts: [{
      id: "7e7d8003c7ab78001d6c895d"
      origin: "mail",
      service: "mail",
      type: "mail",
      value: "v5@yandex.ru"
    }]
  }

Тело запроса содержит следующие параметры.

Параметр

Тип

Описание

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 — например, "hello@yandex.ru".

  • type — например "mail", необходимый для интерпретации value.

  • service — например "mail", сервис для которого используется данное value.

  • origin — например "chatra", сервис, который создал данный элемент контактных данных

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

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

2.1 Пример вебхука при закрытии диалога — смена статуса на «Закрыто»:

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

2.2 При изменении статуса на «Отложено» придёт такой вебхук:

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

2.3 При изменении ответственного пользователя внутри диалога:

{
  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: 'vasyapupkin007@yandex.ru',
  userId: '5e44f63b39cfc7002029e40c',
  labels: [],
  contact: {
    _id: '5e7d8902d7ab78001d6c895c',
    name: 'V5',
    description: 'Nothing special.',
    contacts: [{
      id: "7e7d8003c7ab78001d6c895d"
      origin: "mail",
      service: "mail",
      type: "mail",
      value: "v5@yandex.ru"
    }]
  }
}

2.4 Добавление тега:

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

2.5 Удаление тега:

{
  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

строка

для идентификации типа хука, в данном случае может принимать значения:

  • '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 (массив контактных данных).

contact.contacts

массив

состоит из объектов, каждый из которых содержит:

  • id — уникальный идентификатор элемента контактных данных.

  • value — например, "hello@yandex.ru".

  • type — например "mail", необходимый для интерпретации value.

  • service — например "mail", сервис для которого используется данное value.

  • origin — например "chatra", сервис, который создал данный элемент контактных данных.

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

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

{
  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: 'vasyapupkin007@yandex.ru',
  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: "v5@yandex.ru"
    }]
  }
}

Пример для исходящего сообщения:

{
  id: '5fbfa9ca74a5f6001dfd2891',
  timestamp: 1606396362475,
  type: 'message creation',
  dialogId: '5fbfa994013de80128fcb985',
  url: 'https://app.yeahdesk.ru/conversations/5fbfa994013de80128fcb985',
  title: '',
  contactsId: '7e7d8003c7ab78001d6c895d',
  origin: 'mail',
  channelId: '6ebd003bda988200311229c8',
  channelName: 'vasyapupkin007@yandex.ru',
  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: "v5@yandex.ru"
    }]
  }
}

Тело запроса содержит следующие параметры.

Параметр

Тип

Описание

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 — например, "hello@yandex.ru".

  • type — например "mail", необходимый для интерпретации value.

  • service — например "mail", сервис для которого используется данное value.

  • origin — например "chatra", сервис, который создал данный элемент контактных данных.

PreviousДашбордNextКастомный канал

Last updated