Использовать webhook для получения сообщений и событий

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

Сервис повторяется три раза, при каждой попытке с 10-секундным тайм-аутом.

Endpoint

{webhook_url}/v3/conversations/{conversationId}/activities

Where

  • {webhook_url} — это базовый URL-адрес, настроенный в пользовательском канале.
  • {conversationId} с уникальным идентификатором GUID активного разговора.

Метод

POST

Заголовки запросов

Заголовок Description
Authorization Маркер носителя авторизации, полученный из зарегистрированного приложения Microsoft Entra.

Замечание

Убедитесь, что вы настроили учетные данные федеративного удостоверения, чтобы этот заголовок был активен.

Политика повторных попыток

  • Служба веб-перехватчика пытается выполнить задачу до трех раз.
  • Каждая повторная попытка позволяет 10-секундный тайм-аут.
  • После трех неудачных попыток дальнейшие повторные попытки не выполняются.

Полезные данные запроса

Нагрузки следуют схеме действий Bot Framework. Структура содержит содержимое сообщения, тип действия, сведения о отправителе и необязательные вложения.

Поля текста запроса

Ключ уровня 1 Ключ уровня 2 Ключ уровня 3 Description Тип
Тип Тип действия (сообщение, событие, ввод) строка (максимум 256)
channelId Идентификатор канала (например, "MessagingApi") строка (максимум 256)
от Объект Sender object
ид Идентификатор отправителя строка (максимум 256)
имя Отображаемое имя отправителя строка (максимум 256)
разговор ид ИД разговора строка (максимум 256)
textFormat Формат текста сообщения (Markdown) строка (максимум 256)
attachments [ ] Список вложений (если таковые есть) массив
Тип контента Тип MIME вложения строка (максимум 256)
contentUrl URL-адрес файла string
содержимое Обычно NULL —
имя Имя файла строка (максимум 256)
thumbnailUrl Обычно NULL —

Поддерживаемые типы действий

Тип Description
message Стандартное текстовое или обогащенное сообщение
набор текста Указывает, что агент или представитель службы поддержки (представитель службы или представитель) набирает текст.
событие События уровня системы, такие как присоединение или закрытие

Имена действия события

Следующие значения отправляются в поле названия активности событий:

  • АгентПринят
  • AgentEndSession
  • ЗавершениеРазговораОсновнымАгентом
  • Агент отключен
  • AgentStartSecondaryChannel
  • AgentRaiseSecondaryChannel
  • AgentEndSecondaryChannel
  • ЗавершениеРазговора
  • SupervisorForceClosedConversation
  • ConsultAgentInitiated
  • Ошибка консалтингового агента
  • ConsultAgentAcceptSession
  • ConsultAgentEndSession
  • ConsultAgentRejectSession
  • Сеанс консультации с агентом истек
  • ConsultAgentRemoved
  • TransferToAgentInitiated
  • TransferToAgentFailed
  • TransferAgentAcceptSession
  • TransferAgentRejectSession
  • TransferAgentTimedOutSession
  • AgentEndedConsult
  • Агент присоединился к разговору с клиентом
  • ConsultAgentLeftPublicConversation
  • TransferToQueueInitiated
  • TransferToQueueFailed
  • CustomerDisconnected
  • Клиент отключился, агент ожидает
  • АгентНазначен
  • Вне рабочего времени из-за нерабочих часов
  • Вне рабочих часов из-за праздника

Примеры полезной нагрузки

Примеры полезных данных представляют различные типы действий в реальном времени, такие как сообщения, индикаторы ввода текста, события агентов и вложения, которые приложение отправляет в веб-перехватчик во время активного разговора.

Агент или представитель принят

{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_AgentAccepted_**",
  "name": "AgentAccepted"
}

Ввод данных агентом или представителем


{
  "type": "typing",
  "channelId": "MessagingApi",
  "conversation": {
    "id": "{conversation_id}"
  },
  "recipient": {
    "id": "{recipient_id}"
  }
}

Сообщение агента или представителя


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}",
    "name": "{sender_name}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "textFormat": "markdown",
  "text": "hello"
}

Агент/представитель отправляет вложение


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}",
    "name": "{sender_name}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "textFormat": "markdown",
  "attachments": [
    {
      "contentType": "image/jpeg",
      "contentUrl": "{attachment_url}",
      "content": null,
      "name": "issue (1).jpg",
      "thumbnailUrl": null
    }
  ]
}

Агент/представитель закрыт


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_AgentClosed_**",
  "name": "AgentClosed"
}

Беседа закрыта


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_ConversationClosed_**",
  "name": "ConversationClosed"
}

Ответ

Код HTTP 200. Все данные, размещенные в тексте запроса, игнорируются.

Общие сведения об API обмена сообщениями

  • Last updated on