帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>智能客服（Desk）>服务端 API>回调配置>任务流执行详情回调

任务流执行详情回调

最近更新时间：2026-09-04 16:13:53
我的收藏

本页目录：

功能说明

任务流执行详情回调，用于向业务后台实时同步任务流的执行过程，包括任务流开始、每个节点的执行流转、任务流结束等。
业务方可据此实时跟踪任务流执行进度、留存节点执行数据、构建执行链路分析等。
注意：任务流执行详情回调按任务流执行实例（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
必填
错误信息。

联系我们

如果您在接入过程中有任何疑问，请用微信或企业微信扫码加入智能客服交流群进行咨询。


中国站