使用 Webhook 接收消息和事件

当对话处于活动状态时，来自客户服务代表的事件和消息将发送到配置的 Webhook 终结点。 要在自定义消息通道中接收实时更新，必须设置 Webhook。

该服务重试三次，每次尝试时超时为 10 秒。

端点

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

位置

  • 是您在自定义渠道中配置的基础 URL。
  • 与活动对话的 GUID。

方法

POST

请求标头

Header Description
Authorization 从已注册 Microsoft Entra 应用获取的授权持有者令牌。

注释

确保配置联合标识凭据以启用此标头。

重试策略

  • Webhook 服务 最多重试三次。
  • 每次重试都允许 10 秒超时。
  • 三次尝试失败后，不会再重试。

请求有效负载

有效负载遵循 Bot Framework 活动架构。 该结构包括邮件内容、活动类型、发件人详细信息和可选附件。

请求正文字段

第 1 层密钥 第 2 层密钥 第 3 层密钥 Description 类型
类型 活动类型（消息、事件、键入） string （max 256）
频道ID 通道的标识符（例如，“MessagingApi”） string （max 256）
发件人 Sender 对象 对象
id 发件人 ID string （max 256）
姓名 发送方显示名称 string （max 256）
对话 id 对话 ID string （max 256）
textFormat 消息文本格式（Markdown） string （max 256）
附件 [ ] 附件列表（如果有） 数组
内容类型 附件的 MIME 类型 string （max 256）
contentUrl 文件 URL 字符串
内容 通常为 null —
姓名 文件的名称 string （max 256）
缩略图URL 通常为 null —

支持的活动类型

类型 Description
消息 标准文本或丰富消息
typing 指示客服代理或客户服务代表（客服专员或代表）正在输入
事件 联接/关闭等系统级事件

事件活动名称

以下值在事件活动 的名称 字段中发送：

  • AgentAccepted
  • AgentEndSession
  • 主要代理结束会话
  • 代理已断开连接
  • AgentStartSecondaryChannel
  • AgentRaiseSecondaryChannel
  • AgentEndSecondaryChannel
  • 关闭会话
  • SupervisorForceClosedConversation
  • ConsultAgentInitiated
  • ConsultAgentFailed
  • ConsultAgentAcceptSession
  • ConsultAgentEndSession
  • 咨询代理拒绝会话
  • ConsultAgentSessionTimedOut
  • 咨询代理已移除
  • TransferToAgentInitiated
  • TransferToAgentFailed
  • TransferAgentAcceptSession
  • TransferAgentRejectSession
  • TransferAgentTimedOutSession
  • 代理已结束咨询
  • 代理加入客户会话
  • ConsultAgentLeftPublicConversation
  • TransferToQueueInitiated
  • 队列转移失败
  • CustomerDisconnected
  • CustomerDisconnectedAgentWaiting
  • 代理已分配
  • OutOfOperatingHoursDueToNonWorkingHours
  • OutOfOperatingHoursDueToHoliday

示例负载

示例有效负载表示不同类型的实时活动，例如，应用程序在活动对话期间发送到 Webhook 的消息、键入指示器、代理事件和附件。

代理/代表已接受

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

响应

200 HTTP 代码。 将忽略在请求正文中发布的任何数据。

消息传送 API 概述

  • Last updated on