ZENAVA
Guides

三方智能体接口开发说明文档

三方智能体接口开发说明文档

本文说明三方智能体要接收的请求、要返回的 SSE 事件，以及挂机、转人工、按键指令的写法。平台侧绑定和语音导航变量见 三方智能体对接配置说明文档。

通话中的用户话术来自 RASR。这不是挂机后的 ASR。座席工作台实时转写事件是 transcript，不是本接口的 query。

快速阅读

外呼机器人使用 responseMode=streaming，按 SSE 返回。平台把各次 answer.content 按到达顺序拼接后做 TTS。智能体不要在后续片段里重复已经返回过的前文。

首 token 建议低于 350ms，最长建议不超过 500ms。这是交互建议，不是接口超时字段。

挂机指令是 #挂机#，转人工指令是 #转人工#。指令前后不要加标点或其他文字。TTS 只播报对话文本，不播报指令。

阅读地图

内容章节
URL、密钥和接入示例配置项
请求里各字段谁产生、何时出现请求
message、message_end、error、agent_thought返回
打断、攒句、沉默、挂机、转人工、按键通话轮次
怎样算对接成功生效、验收

配置项

开发完成后交给平台侧实施：

项必填说明
调用地址是由 protocol、host、path 组成
appKey是鉴权
secretKey是鉴权
stream是外呼机器人设为 true
user否接入示例中的用户名
{
  "chatHandleParams": {
    "protocol": "https",
    "host": "for.example.com",
    "path": "/path/example",
    "stream": true,
    "appKey": "ThisIsAppKey",
    "secretKey": "ThisIsSecretKey",
    "user": "UserName"
  }
}

鉴权使用平台约定的三方智能体签名规则，材料是 appKey 与 secretKey。请求验签通过后才处理正文。签名步骤沿用联调时给出的规则。

responseMode 有 streaming 和 blocking。外呼机器人使用 streaming。

请求

平台发到智能体的请求使用下列字段。

字段作用
requestUniqueId每一次请求一条。对账和排错用这个标识
conversationId会话标识。开场白那次由智能体创建并返回。同一通后续轮次都带它。平台不在请求里附带全部历史
userField自定义变量。用于个性化播报，或多场景路由
responseModestreaming 或 blocking
query当前轮用户内容。元素含 content、contentType
contentType文本轮次为 text
currentChatRound轮次序号。攒句并发时用它判断先后
playedContent上一轮已被打断时，实际已经播出去的文本。未打断时不靠这个字段
cancelRquestUniqueIds攒句时有值。智能体按该列表去掉对应历史请求。字段名保持这个拼写

个性化变量示例：

{
  "userField": {
    "name": "张三",
    "city": "上海",
    "car_model": "TR9"
  }
}

路由变量示例：

{
  "userField": {
    "arg": "{arg}"
  }
}

arg 的取值由语音导航变量决定，例如 car_marketing、after_sale、finance。它们不是平台枚举。

通话轮次

用户在播报结束后说话：

{
  "query": [
    {
      "content": "如何重置密码",
      "contentType": "text"
    }
  ],
  "currentChatRound": 10
}

播报过程中被有效打断。playedContent 是上一轮已经播出的内容：

{
  "query": [
    {
      "content": "如何重置密码",
      "contentType": "text"
    }
  ],
  "playedContent": "您好，我是上一轮播音被打断时已播放的内容",
  "currentChatRound": 10
}

用户连续说了两句、外呼机器人尚未回复，触发攒句。两句用中文句号 。 拼进 query.content。cancelRquestUniqueIds 有值。攒句时可能并发多个请求，用 currentChatRound 定顺序：

{
  "conversationId": "b1fcdc6123c62be261cf97b00b25be6a2af",
  "query": [
    {
      "content": "如何结算。使用现金结算",
      "contentType": "text"
    }
  ],
  "currentChatRound": 10
}

播报结束后，用户沉默超过设定时长。时长在业务流程里配置。请求内容为：

{
  "query": [
    {
      "content": "(沉默)",
      "contentType": "text"
    }
  ],
  "currentChatRound": 10
}

返回

流式响应用 SSE。一条回复由多条 message 组成，结束时发 message_end。异常发 error。工具调用发 agent_thought。

message：

event: message
data:{"event":"message","conversationId":"94154941-4c5e-4f40-a898-bef53a9e84a1","answer":{"content":"示例1","contentType":"text","createdAt":1728634543000,"messageId":"553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"}}

content 是当前片段。平台按顺序拼接。第一次返回「你好」，第二次返回「，张三」，播报为「你好，张三」。若第二次又返回完整句「你好，张三」，播报会变成「你好你好，张三」。

message_end。收到后平台结束本次流式读取：

event: message_end
data:{"event":"message_end","conversationId":"94154941-4c5e-4f40-a898-bef53a9e84a1","answer":{"createdAt":1728698606000,"messageId":"553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"}}

error：

event: error
data:{"event":"error","conversationId":"94154941-4c5e-4f40-a898-bef53a9e84a1"}

正常播报：

data:{"answer":{"content":"您好","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"很高兴为您服务。","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"请问有什么可以帮您的","contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800449},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

挂机。末尾指令为 #挂机#，TTS 不读该指令：

data:{"answer":{"content":"感谢您的来电","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"再见#挂机#","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

转人工。末尾指令为 #转人工#：

data:{"answer":{"content":"正在为您转接人工服务","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"请稍等#转人工#","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

按键采集，说话不能打断。指令为 DTMF{6|5|您没有按啊，可以再按一次吗|2|0}：

data:{"answer":{"content":"请按键输入您的pin码，按井号键结束。","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"DTMF{6|5|您没有按啊，可以再按一次吗|2|0}","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

按键采集，说话可以打断。指令为 DTMF_INTERRUPT{...}，花括号内字段与上例相同：

data:{"answer":{"content":"请按键输入您的pin码，按井号键结束。","contentType":"text","createdAt":1752800446},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"DTMF_INTERRUPT{6|5|您没有按啊，可以再按一次吗|2|0}","contentType":"text","createdAt":1752800447},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

工具调用。agent_thought 带 tool，随后仍用 message 播报，并以 message_end 结束：

data:{"tool":"current_time","conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"agent_thought"}
data:{"answer":{"content":"当前时间是","contentType":"text","createdAt":1752800448},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"content":"2025年1月1号1时1分","contentType":"text","createdAt":1752800449},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message"}
data:{"answer":{"contentType":"text","createdAt":1752800450},"conversationId":"b1fcdc6123c62be261cf97b00b25be6a2af","event":"message_end"}

生效

  1. 服务按同一鉴权规则验签。
  2. 平台已配置 URL、appKey、secretKey，且外呼机器人流程进入该智能体。
  3. 开场白响应里带上新的 conversationId，后续轮次沿用。
  4. streaming 时持续输出 message，本轮结束输出 message_end。
  5. 需要挂机、转人工或按键时，指令出现在拼接后的文本末尾，且没有多余标点。

blocking 可以返回整段结果，外呼机器人实时对话仍以 streaming 为准。

验收

  • 用 requestUniqueId 能在双方日志里对上同一轮。
  • 开场白之后的轮次，conversationId 不变；请求里没有全量历史。
  • 片段拼接与「不要重复前文」的例子一致。
  • 打断轮次能读到 playedContent。攒句轮次 query.content 含 。，且 cancelRquestUniqueIds 有值。
  • 沉默轮次的 content 为 (沉默)。
  • #挂机#、#转人工# 触发对应通话动作，电话里听不到这两个指令。
  • DTMF{...} 进入按键且说话不能打断；DTMF_INTERRUPT{...} 进入按键且说话可以打断。
  • 验签失败时智能体拒绝请求，通话没有正常播报。

Updated about 2 months ago

Did this page help you?