跳到主要内容

Agent Hooks 回调

Agent Hooks 功能支持通过 Webhook 的方式将拦截事件回调至应用服务器（App Server）。当 Hook 条件触发时，系统会向配置的 Webhook URL 发送回调请求，便于业务方进行自定义处理，如付费检测、用户限制、数据统计等。

本文档将介绍 Hooks 回调的数据结构、触发条件、签名校验机制以及接入示例，帮助您快速完成 Agent Hooks Webhook 的接入与处理。

回调方法​

请求方法：POST

数据格式：application/json

超时时间：5 秒

即时通讯服务端会在 POST 请求 URL 中添加签名参数，您可通过签名验证调用者身份和数据有效性，详细参见 服务端回调签名。

触发条件​

Hooks Webhook 回调在以下情况下触发：

  1. 对话前拦截（beforeChat）：用户发送消息时，Hook 条件匹配成功
  2. 动作执行：Hook 配置中包含 webhook 类型的动作

回调参数说明​

参数路径类型说明
基础字段
phaseStringHook 执行阶段，当前支持：beforeChat（对话前）
nameStringHook 名称，用于标识具体的 Hook 配置
timestampNumber触发时间（Unix 毫秒时间戳）
conditionObject触发条件配置对象，详细结构请参见 Hooks 配置指南
条件匹配结果
conditionOutcomeObject条件匹配结果对象
conditionOutcome.matchBoolean条件是否匹配成功
conditionOutcome.detailsObject匹配详情对象，具体结构见下方说明
对话请求信息
requestObject对话请求信息对象
request.agentIdStringAgent 唯一标识
request.queryString用户输入内容
request.variablesObject系统变量对象

匹配详情结构​

意图检测匹配详情​

当条件类型为 intentDetection 时：

参数路径类型说明
detectedIntentsArray<Object>检测到的意图列表
detectedIntents[].intentString意图名称
detectedIntents[].confidenceDouble检测置信度
detectedIntents[].confidenceThresholdDouble配置的置信度阈值

回调请求示例​

对话轮数检测示例​

当对话轮数达到阈值时触发的回调：

HTTP
POST /webhook?appKey=someappKey&timestamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "phase": "beforeChat",
  "name": "detectPaymentIntent",
  "timestamp": 1758522854785,
  "condition": {
    "type": "comparison",
    "conditions": [
      {
        "property": "conversationTurns",
        "operator": ">=",
        "value": 3
      }
    ]
  },
  "conditionOutcome": {
    "match": true,
    "details": {}
  },
  "request": {
    "agentId": "hook_v5",
    "query": "你好",
    "variables": {
      "conversationDays": 0,
      "conversationTurns": 3
    }
  }
}

意图检测示例​

当检测到付费意图时触发的回调：

HTTP
POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
App-Key: your-app-key
Nonce: random-string
Timestamp: 1730890800
Signature: generated-signature

{
  "phase": "beforeChat",
  "name": "detectPaymentIntent",
  "timestamp": 1758523519856,
  "condition": {
    "type": "intentDetection",
    "intents": [
      {
        "intent": "付费意愿",
        "confidenceThreshold": 0.5
      },
      {
        "intent": "升级会员",
        "confidenceThreshold": 0.5
      },
      {
        "intent": "充值",
        "confidenceThreshold": 0.5
      }
    ]
  },
  "conditionOutcome": {
    "match": true,
    "details": {
      "detectedIntents": [
        {
          "intent": "付费意愿",
          "confidence": 0.9,
          "confidenceThreshold": 0.5
        }
      ]
    }
  },
  "request": {
    "agentId": "hook_v6",
    "query": "我能付费买菜吗",
    "variables": {
      "conversationDays": 0,
      "conversationTurns": 1
    }
  }
}

应答说明​

  • 服务端需返回 HTTP 200 状态码表示处理成功
  • 如在 5 秒内未收到响应，服务端将最多 重试 2 次；连续失败将终止本次推送
  • 若短时间内出现大规模推送失败，系统将暂停推送 1 分钟后自动恢复尝试
最后于 更新