# Вебхуки

{% hint style="info" %}
Для работы с вебхуками требуются навыки программирования.
{% endhint %}

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

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

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

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

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

{% hint style="warning" %}
Вебхуки доступны только на [старших тарифах](https://yeahdesk.ru/pricing) и во время тестового периода. Смените тариф перед использованием. 
{% endhint %}

Чтобы получать вебхуки, необходимо из интерфейса Еадеска задать серверы, на которые будут отправляться запросы. Для этого перейдите в [*Настройка* → *API и вебхуки*](https://develop.yeahdesk.ru/settings/api/webhooks) и нажмите на «плюсик».

![Заполните название, описание и выберите события, которые хотите отслеживать](/files/-LgF-nl403P7Dgy1GryU)

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

* Название — поможет быстро различать добавленные сервера.
* URL — адрес вашего сервера, на который будут отправляться POST-запросы.
* События — отметьте галочками события, на которые будут отправляться вебхуки.

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

![Все добавленные серверы будут отображаться списком в этом же окне](/files/-LgF1E6VVuipyoenVP6h)

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

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

```javascript
{
  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**           | строка | <p></p><p>источник диалога, типы:</p><ul><li>mail для диалога из электронной очты, </li><li>chatra — Чатра, </li><li>pbx — телефония, </li><li>skype — Скайп, </li><li>fb — Фейсбук,</li><li>ig — Инстаграм, </li><li>telegram — Телеграм,</li><li>whatsapp — Вотсап,</li><li>vk — ВКонтакте,</li><li>custom — кастомный канал,</li><li>demo — служебный канал Еадеска.</li></ul>                                                           |
| **channelId**        | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка.                                                                                                                                                                                                                                                                                                                                          |
| **channelName**      | строка | не уникальное название канала, помогает быстро ориентироваться между всеми каналами Еадеска.                                                                                                                                                                                                                                                                                                                                                |
| **contact**          | объект | объект контактных данных, состоит из \_id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных)                                                                                                                                                                                                                                                                                           |
| **contact.contacts** | массив | <p></p><p>состоит из объектов, каждый из которых содержит:</p><ul><li>id — уникальный идентификатор элемента контактных данных.</li><li>value — например, "<hello@yandex.ru>".</li><li>type — например "mail", необходимый для интерпретации value.</li><li>service — например "mail", сервис для которого используется данное value.</li><li>origin — например "chatra", сервис, который создал данный элемент контактных данных</li></ul> |

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

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

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

```javascript
{
  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 При изменении статуса на «Отложено» придёт такой вебхук:

```javascript
{
  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 При изменении ответственного пользователя внутри диалога:

```javascript
{
  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 Добавление тега:

```javascript
{
  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 Удаление тега:

```javascript
{
  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**                | строка | <p></p><p>для идентификации типа хука, в данном случае может принимать значения:</p><ul><li>'status opened': true.</li><li>'status closed': true.</li><li>'status waiting': true.</li><li>'dialog reopening': true.</li><li>'responsible assignment': 'Установлен ответственный'.</li><li>'responsible reset': 'Сброшен ответственный'.</li><li>'responsible change': 'Сменен ответственный'.</li></ul>                                      |
| **responsibleId**       | строка | id ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного.                                                                                                                                                                                                                                                                                                                                 |
| **responsibleUserName** | строка | имя ответственного. Необязательное поле, присутствует в хуках, связанных с назначением/сменой ответственного.                                                                                                                                                                                                                                                                                                                                |
| **dialogId**            | строка | идентификатор диалога в Еадеске.                                                                                                                                                                                                                                                                                                                                                                                                             |
| **url**                 | строка | ссылка на диалог в Еадеске.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **title**               | строка | тема диалога.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **contactsId**          | строка | id контактных данных, связанных с диалогом (автор).                                                                                                                                                                                                                                                                                                                                                                                          |
| **origin**              | строка | <p></p><p>источник диалога, типы:</p><ul><li>mail для диалога из электронной очты, </li><li>chatra — Чатра, </li><li>pbx — телефония, </li><li>skype — Скайп, </li><li>fb — Фейсбук,</li><li>ig — Инстаграм, </li><li>telegram — Телеграм,</li><li>whatsapp — Вотсап,</li><li>vk — ВКонтакте,</li><li>custom — кастомный канал,</li><li>demo — служебный канал Еадеска.</li></ul>                                                            |
| **status**              | строка | статус диалога. Необязательное поле, присутствует в хуках, связанных со сменой статуса.                                                                                                                                                                                                                                                                                                                                                      |
| **channelId**           | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка.                                                                                                                                                                                                                                                                                                                                           |
| **channelName**         | строка | не уникальное название канала, помогает быстро ориентироваться между всеми каналами Еадеска.                                                                                                                                                                                                                                                                                                                                                 |
| **labels**              | массив | перечень всех актуальных тегов в этом диалоге.                                                                                                                                                                                                                                                                                                                                                                                               |
| **addedLabel**          | строка | один добавленный тег.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **removedLabel**        | строка | один удалённый тег.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **waitingTill**         | строка | дата в формате ISO, при достижении которой статус диалога будет сменен на 'opened'. Необязательное поле, присутствует в хуках, связанных с переводом диалога в ожидание.                                                                                                                                                                                                                                                                     |
| **closedBy**            | строка | id пользователя, закрывшего диалог, в Еадеске. Необязательное поле, присутствует в хуках, связанных с закрытием диалога.                                                                                                                                                                                                                                                                                                                     |
| **contact**             | объект | объект контактных данных, состоит из \_id (строка), name (строка), description (строка, необязательное поле), contacts (массив контактных данных).                                                                                                                                                                                                                                                                                           |
| **contact.contacts**    | массив | <p></p><p>состоит из объектов, каждый из которых содержит:</p><ul><li>id — уникальный идентификатор элемента контактных данных.</li><li>value — например, "<hello@yandex.ru>".</li><li>type — например "mail", необходимый для интерпретации value.</li><li>service — например "mail", сервис для которого используется данное value.</li><li>origin — например "chatra", сервис, который создал данный элемент контактных данных.</li></ul> |

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

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

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

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

```javascript
{
  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**           | строка | <p></p><p>источник диалога, типы:</p><ul><li>mail для диалога из электронной очты, </li><li>chatra — Чатра, </li><li>pbx — телефония, </li><li>skype — Скайп, </li><li>fb — Фейсбук,</li><li>ig — Инстаграм, </li><li>telegram — Телеграм,</li><li>whatsapp — Вотсап,</li><li>vk — ВКонтакте,</li><li>custom — кастомный канал,</li><li>demo — служебный канал Еадеска.</li></ul>                                                                                                                                                                                                                               |
| **channelId**        | строка | id канала из Еадеска, помогает определить через какой-канал был создан диалог и ведётся переписка.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **channelName**      | строка | не уникальное название канала, помогает быстро ориентироваться между всеми каналами Еадеска.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **message**          | объект | <p></p><p>объект сообщения, содержит в себе поля:</p><ul><li>\_id (строка) — id сообщения в Еадеске,</li><li>text (строка) — сообщение в текстовой форме. Необязательное поле (пример - в некоторых мессенджерах вложение передается как отдельное сообщение).</li><li>html (строка) — сообщение с форматированием. Необязательное поле (практически все мессенджеры не позволяют применять форматирование).</li><li>direction (строка) — направление сообщения (in/out). Необязательное поле, его отсутствие означает direction: 'out'.</li><li>attachments (число) — количество приложенных файлов.</li></ul> |
| **messageAuthor**    | объект | <p>объект пользователя, который инициировал создание сообщения. Состоит из:</p><ul><li><p>id (строка) — id пользователя в системе,</p><p>type (строка) — пока передаёт единственное значение 'user', пользователь системы. Будет расширяться по мере обновления,</p><p>name (строка) — имя этого пользователя в Еадеске.</p></li></ul>                                                                                                                                                                                                                                                                          |
| **contact**          | объект | <p>объект контактных данных, состоит из:</p><ul><li>\_id (строка)</li><li>name (строка)</li><li>description (строка, необязательное поле)</li><li>contacts (массив контактных данных)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **contact.contacts** | массив | <p></p><p>состоит из объектов, каждый из которых содержит:</p><ul><li>id — уникальный идентификатор элемента контактных данных.</li><li>value — например, "<hello@yandex.ru>".</li><li>type — например "mail", необходимый для интерпретации value.</li><li>service — например "mail", сервис для которого используется данное value.</li><li>origin — например "chatra", сервис, который создал данный элемент контактных данных.</li></ul>                                                                                                                                                                    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.yeahdesk.ru/docs/for-developers/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.