功能说明
任务流执行详情回调，用于向业务后台实时同步任务流的执行过程，包括任务流开始、每个节点的执行流转、任务流结束等。
业务方可据此实时跟踪任务流执行进度、留存节点执行数据、构建执行链路分析等。
注意：任务流执行详情回调按任务流执行实例（ExecutionId）组织，事件在同一 ExecutionId 内按 Seq 单调递增。业务方应按 ExecutionId + Seq 去重与排序。
注意事项
要启用回调，必须在 智能客服管理端 单击设置 > 开发者设置页面配置回调 URL 并打开任务流执行详情回调开关。
回调的方向是即时通信 IM 后台向 App 后台发起 HTTPS POST 请求。
收到事件通知后应异步处理内部逻辑，同步返回接收成功的应答。
App 后台在收到回调请求之后，务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。
同一任务流实例的事件按
ExecutionId + Seq 唯一标识，Seq 从 1 开始单调递增，业务方应据此去重与排序。其他安全相关事宜请参见 第三方回调简介：安全考虑 文档。
接口说明
请求 URL 示例
以下示例中 App 配置的回调 URL 为
https://www.example.com。示例：
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform&RequestID=$RequestID
请求参数说明
参数 | 说明 |
https | 请求协议为 HTTPS，请求方式为 POST。 |
www.example.com | 回调 URL。 |
SdkAppid | 创建应用时在即时通信 IM 控制台分配的 SDKAppID。 |
CallbackCommand | 固定为 Chatbot.TaskFlowEventNotify。 |
contenttype | 固定值为 json。 |
ClientIP | 客户端 IP，格式例如： 127.0.0.1。 |
RequestID | 请求的 RequestID，用于唯一标识回调请求，当发生回调重试时，业务后台可以使用此字段进行去重处理。 |
请求包示例
任务流开始事件。
{"CallbackCommand": "Chatbot.TaskFlowEventNotify","Event": "TaskBegin","EventTime": 1754280000000,"Seq": 1,"ExecutionId": "cf634425-a0ba-49d5-b205-86ba2441de96","TaskId": 3474,"TaskName": "售后咨询","Env": "production","SessionId": "554d4e07-76cf-4a9c-82ad-f1878de93d13","RobotId": "@RBT#DeskDefaultRobot","ClientUserId": "your_user_id","CustomerServiceId": "@customer_service_account","ChannelType": "SDK","NodeId": "node-start-1","NodeName": "开始","NextNodeId": "node-reply-1","ExecutionDetail": {"TriggerType": "IntentRecognition","InitialVariables": {"userLevel": "vip"}}}
信息收集节点等待用户填写。
{"CallbackCommand": "Chatbot.TaskFlowEventNotify","Event": "InformationCollectionWaiting","EventTime": 1754280001000,"Seq": 2,"ExecutionId": "cf634425-a0ba-49d5-b205-86ba2441de96","TaskId": 3474,"TaskName": "售后咨询","Env": "production","SessionId": "554d4e07-76cf-4a9c-82ad-f1878de93d13","RobotId": "@RBT#DeskDefaultRobot","ClientUserId": "your_user_id","CustomerServiceId": "@customer_service_account","ChannelType": "SDK","NodeId": "node-collect-1","NodeName": "信息收集1","ExecutionDetail": {"GuidingScript": "请填写订单号和用户id","Fields": [{"Name": "订单id","CollectionMethod": 0,"IsRequired": 1,"PlaceHolder": "请输入订单id"},{"Name": "用户id","CollectionMethod": 0,"IsRequired": 0,"PlaceHolder": "请输入用户id"}],"SkippedByPrefill": false,"Submitted": false}}
信息收集节点完成。
{"CallbackCommand": "Chatbot.TaskFlowEventNotify","Event": "InformationCollectionCompleted","EventTime": 1754280015000,"Seq": 3,"ExecutionId": "cf634425-a0ba-49d5-b205-86ba2441de96","TaskId": 3474,"TaskName": "售后咨询","Env": "production","SessionId": "554d4e07-76cf-4a9c-82ad-f1878de93d13","RobotId": "@RBT#DeskDefaultRobot","ClientUserId": "your_user_id","CustomerServiceId": "@customer_service_account","ChannelType": "SDK","NodeId": "node-collect-1","NodeName": "信息收集1","NextNodeId": "node-api-1","ExecutionDetail": {"GuidingScript": "请填写订单号和用户id","Fields": [{ "Name": "订单id", "CollectionMethod": 0, "IsRequired": 1, "PlaceHolder": "请输入订单id" },{ "Name": "用户id", "CollectionMethod": 0, "IsRequired": 0, "PlaceHolder": "请输入用户id" }],"Collected": [{ "Name": "订单id", "VariableKey": "order_id", "Value": "ORD123" },{ "Name": "用户id", "VariableKey": "user_id", "Value": "U998" }],"SkippedByPrefill": false,"Submitted": true}}
任务流结束事件，含完整节点执行路径。
{"CallbackCommand": "Chatbot.TaskFlowEventNotify","Event": "TaskEnd","EventTime": 1754280030000,"Seq": 8,"ExecutionId": "cf634425-a0ba-49d5-b205-86ba2441de96","TaskId": 3474,"TaskName": "售后咨询","Env": "production","SessionId": "554d4e07-76cf-4a9c-82ad-f1878de93d13","RobotId": "@RBT#DeskDefaultRobot","ClientUserId": "your_user_id","CustomerServiceId": "@customer_service_account","ChannelType": "SDK","ExecutionDetail": {"EndReason": "Completed","BeginTime": 1754280000000,"EndTime": 1754280030000,"DurationMs": 30000,"TotalSteps": 8,"LastNodeId": "node-human-1","LastNodeName": "转人工1","LastNodeType": "TransferToHuman","NodePath": [{"NodeId": "node-start-1","NodeName": "开始","NodeType": "Start","EnterTime": 1754280000000,"NextNodeId": "node-reply-1","Detail": { "TriggerType": "IntentRecognition", "InitialVariables": { "userLevel": "vip" } }},{"NodeId": "node-collect-1","NodeName": "信息收集1","NodeType": "InformationCollection","EnterTime": 1754280001000,"NextNodeId": "node-api-1","Detail": {"GuidingScript": "请填写订单号和用户id","Fields": [ { "Name": "订单id", "CollectionMethod": 0, "IsRequired": 1 } ],"Collected": [ { "Name": "订单id", "VariableKey": "order_id", "Value": "ORD123" } ],"SkippedByPrefill": false,"Submitted": true}}]}}
请求包公共字段说明
字段 | 类型 | 说明 |
CallbackCommand | String | 固定为 Chatbot.TaskFlowEventNotify。 |
Event | String | 事件类型，详见事件类型列表及说明。 |
EventTime | Integer | 事件触发的毫秒级别时间戳。 |
ExecutionId | String | 任务流执行实例 ID，同一会话内每次触发任务流生成一个新实例 ID。 |
Seq | Integer | 事件序号，同一 ExecutionId 内从 1 开始单调递增，业务方可用于去重与排序。 |
TaskId | Integer | 任务流 ID。 |
TaskName | String | 任务流名称。 |
Env | String | 任务流运行环境： production：已发布版本。 pre-production：未发布版本。 |
SessionId | String | 会话的 SessionId。 |
RobotId | String | 机器人 ID。 |
ClientUserId | String | 用户的 UserID。 |
CustomerServiceId | String | 客服号的 UserID。 |
ChannelType | String | 集成方式： SDK：SDK 集成，对应智能客服管理端的“应用/客户端”集成。 Web(H5)：Web 集成，对应智能客服管理端的“网页（H5）”集成。 WeChat Customer Service：微信客服集成，对应智能客服管理端的“微信客服”集成。 WeChat Official Account：微信公众号集成，对应智能客服管理端的“微信公众号”集成。 WeChat Mini Program：微信小程序集成，对应智能客服管理端的“微信小程序”集成。 WhatsApp：WhatsApp 集成。 Messenger：Messenger 集成。 Viber：Viber 集成。 Telegram：Telegram 集成。 |
NodeId | String | 当前事件所属节点 ID。 |
NodeName | String | 当前事件所属节点名称。 |
NextNodeId | String | 节点流转的下一目标节点 ID： 节点完成事件（ XxxCompleted）会填充此字段。节点等待事件（ XxxWaiting）尚未确定后继节点，此字段为空。任务流因异常终止时此字段为 exception。 |
ExecutionDetail | Object | 事件执行详情，类型由 Event 决定。详见下方各事件详情说明。 |
事件类型列表
事件类型 | 说明 | 详情结构 |
TaskBegin | 任务流开始。 | BeginDetail |
ReplyMessageCompleted | 回复消息节点完成。 | ReplyMessageDetail |
BranchOptionWaiting | 分支选项消息节点等待用户选择。 | BranchOptionDetail |
BranchOptionCompleted | 分支选项消息节点完成。 | BranchOptionDetail |
ConditionCompleted | 条件判断节点完成。 | ConditionDetail |
InformationCollectionWaiting | 信息收集节点等待用户填写。 | InformationCollectionDetail |
InformationCollectionCompleted | 信息收集节点完成。 | InformationCollectionDetail |
APICallCompleted | 接口调用节点完成。 | APICallDetail |
TransferToHumanCompleted | 转人工节点完成。 | TransferToHumanDetail |
TransferToTaskCompleted | 转任务流节点完成。 | TransferToTaskDetail |
TaskEnd | 任务流结束，含结束原因和完整节点执行路径。 | EndDetail |
BeginDetail：任务流开始详情
字段 | 类型 | 说明 |
TriggerType | String | 任务流触发类型： IntentRecognition：用户消息命中任务流问法触发。 Event：事件触发，如打开会话事件。 Signaling：信令直接触发。 FixedBranch：用户点击固定分支按钮触发。 TransferFromTask：由上游任务流的转任务流节点跳转而来。 |
InitialVariables | Object | 任务流开始时的初始变量池，key 为变量名，value 为字符串形式的变量值。 |
节点类型列表
节点类型 | 说明 |
Start | 起始节点。 |
ReplyMessage | 回复消息节点。 |
BranchOption | 分支选项消息节点。 |
Condition | 条件判断节点。 |
InformationCollection | 信息收集节点。 |
APICall | 接口调用节点。 |
TransferToHuman | 转人工节点。 |
TransferToTask | 转任务流节点。 |
ReplyMessageDetail：回复消息节点详情
字段 | 类型 | 说明 |
MsgType | Integer | 消息类型： 1：文本消息。 2：富文本消息。 |
Content | String | 变量替换后实际发出的消息内容。 |
BranchOptionDetail：分支选项节点详情
字段 | 类型 | 说明 |
GuidingScript | String | 变量替换后的菜单提示语。 |
OptionType | Integer | 分支类型： 0：一次性分支。 1：固定分支。 |
Options | Array | 全部选项列表，元素结构见 BranchOption。 |
Selected | Object | 用户选中的选项，未选择或未命中时为空。 |
Matched | Boolean | 用户输入是否命中某个选项。 |
BranchOption 结构：
字段 | 类型 | 说明 |
Id | String | 选项 ID。 |
Content | String | 选项文本。 |
Url | String | 选项跳转链接，仅当选项配置为跳转链接类型时有值。 |
ConditionDetail：条件判断节点详情
字段 | 类型 | 说明 |
Hit | Boolean | 是否命中某个条件判断分支。 |
HitBranchId | String | 命中的分支 ID，全不命中时为空。 |
Branches | Array | 全部条件组列表，业务方可据此了解完整判定逻辑，元素结构见 ConditionBranch。 |
Variables | Object | 参与条件判定的变量快照，仅含条件表达式实际引用到的变量。 |
ConditionBranch 结构：
字段 | 类型 | 说明 |
Id | String | 条件组 ID。 |
Content | String | 条件组描述。 |
Condition | Object | 条件表达式的原始 JSON。 |
InformationCollectionDetail：信息收集节点详情
字段 | 类型 | 说明 |
GuidingScript | String | 变量替换后的引导提示语。 |
Fields | Array | 表单字段定义，元素结构见 FormField。 |
Collected | Array | 实际收集到的字段值列表，仅 InformationCollectionCompleted 事件有值。元素结构见 CollectedField。 |
SkippedByPrefill | Boolean | 变量已全部存在而自动跳过收集时为 true。 |
Submitted | Boolean | 用户是否已提交表单。 Waiting 时为 false，Completed 时若为自动跳过则为 false，用户实际提交则为 true。 |
FormField 结构：
字段 | 类型 | 说明 |
Name | String | 字段名称。 |
CollectionMethod | Integer | 字段收集方式： 0：输入。 1：选择。 |
IsRequired | Integer | 0：非必填。 1：必填。 |
PlaceHolder | String | 字段输入提示。 |
ChooseItemList | Array | 可选项列表，仅 CollectionMethod 为 1（选择）时有值。 |
CollectedField 结构：
字段 | 类型 | 说明 |
Name | String | 字段名称。 |
VariableKey | String | 存入的变量名，为空表示该字段不保存到变量池。 |
Value | String | 实际收集到的值。 |
APICallDetail：接口调用节点详情
字段 | 类型 | 说明 |
Url | String | 被调用的接口 URL。 |
Success | Boolean | 接口调用是否成功。 |
ErrorMsg | String | 接口调用失败时的错误信息。 |
RspVariables | Object | 从接口响应中解析出并写入变量池的变量。 |
TransferToHumanDetail：转人工节点详情
字段 | 类型 | 说明 |
TransferMethod | Integer | 转人工路由方式： 0：默认策略。 1：指定技能组。 |
MemberGroupId | Integer | 目标技能组 ID。 |
NeedConfirm | Boolean | 是否需要用户二次确认转人工。 |
Result | String | 转人工执行结果： Success：转人工成功。 Fail：转人工失败。 WaitConfirm：已发出转人工二次确认消息，等待用户确认。 |
TransferToTaskDetail：转任务流节点详情
字段 | 类型 | 说明 |
NewTaskId | Integer | 目标任务流 ID。 |
BeginOk | Boolean | 目标任务流是否启动成功。 |
EndDetail：任务流结束详情
字段 | 类型 | 说明 |
EndReason | String | 任务流结束原因： Completed：正常走完流程到达结束节点（含转人工、转任务流等正常收尾）。 Exception：异常终止。 Timeout：任务流在等待用户交互的节点超时。 RobotStageEnd：会话的机器人阶段结束任务流被动终止。 |
BeginTime | Integer | 任务流开始时间（毫秒时间戳）。 |
EndTime | Integer | 任务流结束时间（毫秒时间戳）。 |
DurationMs | Integer | 任务流耗时（毫秒）。 |
TotalSteps | Integer | 任务流总事件数（等于最后一个事件的 Seq）。 |
LastNodeId | String | 最后停留节点的 ID。 |
LastNodeName | String | 最后停留节点的名称。 |
LastNodeType | String | 最后停留节点的类型，见节点类型列表。 |
NodePath | Array | 任务流完整节点执行路径，元素结构见 任务流执行路径项详情。 |
PathTruncated | Boolean | 节点执行路径是否因超过上限被截断。为 true 时 NodePath 只保留最近的记录。 |
任务流执行路径项详情
字段 | 类型 | 说明 |
NodeId | String | 节点 ID。 |
NodeName | String | 节点名称。 |
NodeType | String | 节点类型，见节点类型列表。 |
EnterTime | Integer | 执行进入节点的毫秒时间戳。 |
NextNodeId | String | 节点流转的下一目标节点 ID。异常时为 exception |
Detail | Object | 节点执行详情，结构由 NodeType 决定，与对应节点事件的 ExecutionDetail 一致。 |
应答包示例
App 后台同步数据后，发送回调应答包。
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0}
应答包字段说明
字段 | 类型 | 属性 | 说明 |
ActionStatus | String | 必填 | 请求处理的结果，OK 表示处理成功，FAIL 表示失败。 |
ErrorCode | Integer | 必填 | 错误码，此处填 0 表示忽略应答结果。 |
ErrorInfo | String | 必填 | 错误信息。 |
联系我们
如果您在接入过程中有任何疑问，请用微信或企业微信扫码加入智能客服交流群进行咨询。
