Запросы от UseDesk (Webhooks)

Внимание

Если вы используете коробочную версию Юздеска на собственном сервере, то URL методов у вас будет отличаться. Уточните URL для работы с API у поддержки — support@usedesk.ru.

Чтобы включить запросы, отметьте чекбоксы, запросы по которым должны приходить, на странице настройки API (Каналы → API).

Usedesk будет отправлять вам запросы на адрес указанный при настройке канала API в поле “Redirect url”.

Если включить настройку "JSON запрос" - запрос придет в формате json с соответствующими заголовками.

Настройка "отправлять в UTF-8" убирает преобразования символов, например, в комментарии.

Особенности отправки вебхуков сообщений в разных типах каналов

Канал запросов

Откуда отправляется сообщениеТип комментарияВебхук
Интерфейс запросаВнутреннийСоздание комментария, type = private
Интерфейс запросаВнешнийСоздание комментария, type = public

Чатовый канал

Откуда отправляется сообщениеТип комментарияВебхук
Интерфейс запросаВнутреннийСоздание комментария, type = private
Интерфейс запросаВнешний

Создание комментария, type = public

Вебхук нового сообщения чата

Интерфейс чатаВнутренний
Интерфейс чатаВнешнийВебхук нового сообщения чата

Виды запросов

  1. Создание запроса.
  2. Создания комментария.
  3. Изменение запроса.
  4. Оценка пользователя.

Создание запроса

При создании запроса система отправляет вебхук который содержит:

ПараметрЗначение

secret

Токен api канала

id

id запроса
status_id

id статуса запроса.

Перечень возможных статусов:

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
subject

Тема запроса

client_idid клиента
assignee_idid исполнителя (агента)
groupid группы исполнителя
last_updated_atДата последнего изменения запроса
channel_idid канала
emailПочта клиента с которой он написал
published_atДата создания запроса
company_idid компании (аккаунта) из которой пришел вебхук
additional_idДополнительный идентификатор запроса
messageТекст сообщения клиента
filesСсылка на файл, прикрепленный к сообщению или отправленный как сообщение
client

Информация о клиенте. Содержит параметры:

  • id 
  • name – имя 
  • avatar – аватар 
  • note – заметка
  • emails – почта
  • phones - телефон
  • additional_ids – дополнительный идентификатор
custom_fields

Список полей и их значения. Отправляется только при изменении хотя бы одного из доп. полей.

Содержит параметры:

  • id - id доп. поля
  • name - название доп. поля
  • value - значение доп. поля
custom_blocks

Список доп. блоков системы, который содержит параметры:

  • name - называние блока
  • url - url блока
  • secret_key - секретный токен блока
Пример ответа от сервера
{
	"secret": "0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"ticket": {
		"id": 2261907,
		"status_id": 1,
		"subject": "First msg",
		"client_id": 242630,
		"assignee_id": null,
		"group": "0",
		"last_updated_at": "2016-12-17 14:07:33",
		"channel_id": 1234,
		"email": "jon@bonjovi.com",
		"published_at": "2016-12-17 14:07:33",
		"company_id": 153561,
		"additional_id": 123Ca344,
		"message": "Test",
        "files": [
      "https://secure.usedesk.ru/v2/files/153712/68977353/249358488/get-file?key=RGh1WDRMNGRzSVQ0VzJVT0NTYW5kdz09Ojoh7gEtjMrY29NOBS8QyIHQ&filter_name=0"
    ]
	},
        "client": {
        "id": 32917577,
        "name": "Юля Шовгеня",
        "avatar": "/upload/avatars/123.jpg",
        "note": "есть кредит",
        "emails": [
          {
            "email": "shy@usedesk.ru",
            "client_id": 32917577
          },
          {
            "email": "ylia-8322247@mail.ru",
            "client_id": 32917577
          }
        ],
        "phones": [
          {
            "phone": "79254697403",
            "type": "home",
            "client_id": 32917577
          },
          {
            "phone": "",
            "type": "home",
            "client_id": 32917577
          }
         ],
         "additional_ids": [
          {
            "value": "99999",
            "client_id": 32917577
          }
         ]
    },
	"custom_fields":[
		{
			"id": 54,
			"name": "new item 2",
			"value": null
		}
	],
	"custom_blocks": [
		{
			"name": "Test",
			"url": "https://usedesk.ru/",
			"secret_key": "dsf4354f=-213sdfasdsa"
		}
	]
}

Изменение запроса

При изменении запроса система отправляет вебхук который содержит:

ПараметрЗначение

secret

Токен api канала

id

id события изменения запроса
trigger_id

id правило которое изменило запрос

Если "null" значит запрос изменил пользователь

user_id

id пользователя который изменил запрос

Если "null" значит запрос изменило правило

ticket_idid запроса
data

Массив изменений которые были применены к запросу, содержит параметры:

  • target - какое поле было изменено
  • value - на какое значение было изменено поле
  • old_value - с какого значения было изменено поле
changed_at

Дата изменения

old_statusid предыдущего статуса запроса
new_statusid нового статуса запроса
company_idid компании (аккаунта) из которой пришел вебхук
custom_fields

Список полей и их значения. Отправляется только при изменении хотя бы одного из доп полей.

Содержит параметры:

  • id - id доп. поля
  • name - название доп. поля
  • value - значение доп. поля
custom_blocks

Список доп. блоков системы, который содержит параметры:

  • name - называние блока
  • url - url блока
  • secret_key - секретный токен блока
assignee_idid исполнителя (агента)
 client

Информация о клиенте. Содержит параметры:

  • id 
  • name – имя 
  • avatar – аватар 
  • note – заметка
  • emails – почта
  • phones - телефон
  • additional_ids – дополнительный идентификатор
Пример ответа от сервера
{
	"secret": "0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"trigger": {
		"id": 204232 ,
		"trigger_id": null,
		"user_id": 2,
		"ticket_id": 2261907,
		"data":[
			{
				"target": "subject",
				"value": "POST UPDATE"
			},
			{
				"target": "status_id",
				"value": "2"
			},
			{
				"target": "priority",
				"value": "medium"
			},
			{
				"target": "type",
				"value": "task"
			}
		],
		"changed_at": "2016-12-17 14:11:53",
		"old_status": 1,
		"new_status": 2,
		"company_id": 153561
	},
	"custom_fields":[
		{
			"id": 54,
			"name": "new item 2",
			"value": null
		}
	],
	"custom_blocks":[
		{
			"name": "Test",
			"url": "https://usedesk.ru/",
			"secret_key": "dsf4354f=-213sdfasdsa"
		}
	],
    "client": {
        "id": 32917577,
        "name": "Юля Шовгеня",
        "avatar": "/upload/avatars/123.jpg",
        "note": "есть кредит",
        "emails": [
          {
            "email": "shy@usedesk.ru",
            "client_id": 32917577
          }
        ],
        "phones": [
          {
            "phone": "79254697403",
            "type": "home",
            "client_id": 32917577
          }
         ],
         "additional_ids": [
          {
            "value": "99999",
            "client_id": 32917577
          }
        ]
    }
}

Создание комментария

При написании комментария в запроса система отправляет вебхук который содержит:

ПараметрЗначение

secret

Токен api канала
idid комментария
messageТекст сообщения которое отправили
filesСсылка на файл, прикрепленный к сообщению или отправленный как сообщение
type

Тип сообщения

  • private - внутренний
  • public - публичный
from

От лица ого было написано сообщение

  • user - агент
  • client - клиент

Важно: если сообщение отправлено через правило (бота) - вебхук о новом сообщении отправлен не будет. Будет отправлен вебхук об изменении запроса.

user_id

id пользователя который написал сообщение

Если "null" значит комментарий написал клиент

client_id

id клиента который написал сообщение

Если "null" значит комментарий написал пользователь

ticket_idid запроса, в котором был написан комментрий
is_first

1 - если комментарий первый в запросе

0 - если комментарий не первый в запросе

deliveredДоставлено ли сообщение (пока не реализовано)
readedПрочитано ли сообщение (пока не реализовано)
published_atДата создания комментария
custom_fields

Список полей и их значения. Содержит параметры:

  • id - id доп. поля
  • name - название доп. поля
  • value - значение доп. поля
assignee_idid исполнителя (агента)
client

Информация о клиенте. Содержит параметры:

  • id 
  • name – имя 
  • avatar – аватар 
  • note – заметка
  • emails – почта
  • phones - телефон
  • additional_ids – дополнительный идентификатор
Пример ответа от сервера
{
	"secret":"0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"comment":{
		"id": 2652657,
		"message":"New message text",
		"type": "public",
		"from":"user",
		"user_id": 545,
		"client_id":null,
		"ticket_id": 2261907,
		"is_first": 0,
		"delivered": 0,
		"readed": 0,
		"published_at":"2016-12-17 14:14:37",
        "files": [
      "https://secure.usedesk.ru/v2/files/153712/68976191/249357540/get-file?key=SElTYjlZTjdYbmxXSUtxZnA3WncvZz09OjoPNc7adhZDzLDloMRpX%252BxC&filter_name=0"
    ]
	},
	"custom_fields":[
		{
			"id": 54,
			"name": "new item 2",
			"value": null
		}
	],
	"custom_blocks":[
		{
			"name": "Test",
			"url": "https://usedesk.ru/",
			"secret_key": "dsf4354f=-213sdfasdsa"
		}
	],
    "client": {
        "id": 32917577,
        "name": "Юля Шовгеня",
        "avatar": "/upload/avatars/123.jpg",
        "note": "есть кредит",
        "emails": [
          {
            "email": "shy@usedesk.ru",
            "client_id": 32917577
          },
          {
            "email": "ylia-8322247@mail.ru",
            "client_id": 32917577
          }
        ],
        "phones": [
          {
            "phone": "79254697403",
            "type": "home",
            "client_id": 32917577
          },
          {
            "phone": "",
            "type": "home",
            "client_id": 32917577
          }
         ],
         "additional_ids": [
          {
            "value": "99999",
            "client_id": 32917577
          }
         ]
     }
 }

Оценка

При получении оценки в запросе система отправляет вебхук который содержит:

ПараметрЗначение

secret

Токен api канала
idid оценки
client_idid клиента
ticket_idid запроса
rating

Оценка которую поставил клиент

1 - хорошо

2 - нормально

3 - плохо

company_idid компании (аккаунта) из которой пришел вебхук
ticket_comment_idid комментария к оценке
commentКомментарий к оценке
created_atДата создания оценки
updated_atДата обновления оценки
user_idid исполнителя запроса
Пример ответа от сервера
{
	"secret": "0e8f678d8327eb3292a28c8165957b282a1b2f8b",
	"csi":{
		"id": 2652657,
		"user_id": 545,
		"client_id": 123213,
		"ticket_id": 2261907,
		"rating": 3,
		"company_id": 456,
		"ticket_comment_id": 2321,
		"comment": "New message text",
		"created_at": "2016-12-17 14:14:37",
		"updated_at": "2016-12-17 14:14:37"
	}
}

Действия с чатом

Чтобы включить запросы, связанные с чатом, отметьте чекбоксы, запросы по которым должны приходить, на странице настройки API канала (Каналы → Канал API → Блок «Отслеживание чатов»). Это могут быть:

  1. Новый чат: запрос уведомляет о создании нового чата, то есть о первом сообщении в нем
  2. Все сообщения чата: запрос уведомляет о создании всех последующих сообщений в чате
  3. Возобновление чата: запрос уведомляет о том, что чат был переоткрыт новым сообщением, если чат был завершен до этого

Все запросы основаны на одном и том же теле запроса с опорным параметром "chat_id". Если "chat_id" уже был создан при одном из запросов, то новые сообщения и возобновление чата работают в нужном чате, ориентируясь на этот параметр.

При входящем/исходящем сообщении в чате система отправляет вебхук который содержит:

ПараметрЗначение

chat_id

id чата
textТекст сообщения
client_idid клиента
client

Информация о клиенте. Содержит параметры:

  • id 
  • name – имя 
  • avatar – аватар 
  • note – заметка
  • emails – почта
  • phones - телефон
  • additional_ids – дополнительный идентификатор
from

От лица ого было написано сообщение

  • user - агент
  • client - клиент

Важно: если сообщение отправлено через правило (бота) - вебхук о новом сообщении отправлен не будет. Будет отправлен вебхук об изменении запроса.

platform

Тип канала с которой был создан чат. Возможные типы:

  • usedesk_tg - телеграм
secretТокен api канала
idid запроса
status_id

id статуса запроса.

Перечень возможных статусов:

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
subject

Тема запроса

client_idid клиента
assignee_idid исполнителя (агента)
groupid группы исполнителя
last_updated_atДата последнего изменения запроса
channel_idid канала
emailПочта клиента, с которой он написал
published_atДата создания запроса
company_idid компании (аккаунта) из которой пришел вебхук
additional_idДополнительный идентификатор запроса
messageТекст первого сообщения запроса
filesСсылка на файл, прикрепленный к сообщению или отправленный как сообщение
custom_fields

Список полей и их значения. Отправляется только при изменении хотя бы одного из доп. полей.

Содержит параметры:

  • id - id доп. поля
  • name - название доп. поля
  • value - значение доп. поля
custom_blocks

Список доп. блоков системы, который содержит параметры:

  • name - называние блока
  • url - url блока
  • secret_key - секретный токен блока
state

Статус чата если изменился

  • new - новый
  • reopened - переоткрытый
  • closed - закрытый

Если статус чата не изменился - "null"

Пример ответа от сервера
{
	"chat_id": 1962066, 
	"text": "привет", 
	"client_id": 4476034, 
    "client": {
      "id": 4476034,
      "name": "Юля Шовгеня",
      "avatar": "/upload/avatars/123.jpg",
      "note": "есть кредит",
      "emails": [
         {
           "email": "shy@usedesk.ru",
           "client_id": 4476034
         },
         {
           "email": "ylia-8322247@mail.ru",
           "client_id": 4476034
         }
       ],
      "phones": [
         {
           "phone": "79254697403",
           "type": "home",
          "client_id": 4476034
         }
       ],
      "additional_ids": [
         {
           "value": "99999",
           "client_id": 4476034
         }
       ]
     },
	"from": "client", 
	"platform": "usedesk_tg",
	"secret": "***", 
	"ticket": 
	{
		"id": 10264808,
		"status_id": 8,
		"subject": "Арахис — это орех",
		"client_id": 4476034,
		"assignee_id": null,
		"group": null,
		"last_updated_at": "2018-05-11 14:17:12",
		"channel_id": 4242,
		"email": null,
		"published_at": "2018-05-11 14:17:12",
		"company_id": 155568,
		"additional_id": 23,
		"message": "Необъяснимо, но факт.",
        "files": [
      "https://secure.usedesk.ru/v2/files/153712/68977353/249358488/get-file?key=RGh1WDRMNGRzSVQ0VzJVT0NTYW5kdz09Ojoh7gEtjMrY29NOBS8QyIHQ&filter_name=0"
	},
	"state": null
}