文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>智能客服（Desk）>服务端配置>回调配置>会话事件回调

会话事件回调

最近更新时间：2025-07-28 17:07:11

我的收藏

本页目录：

功能说明

智能客服会话事件回调，包含了机器人阶段和人工阶段全部消息的回调，也包含了会话开始，转人工中，转人工成功，转人工失败（无客服在线），客服转接，会话关闭，用户应答超时等会话期间关键事件的回调。
注意：
此功能为高级功能，仅限智能客服高级版使用（高级版试用在有效期内也可使用）。版本差异详细参见 计费概述。

注意事项

要启用回调，必须在 智能客服管理端 单击设置 > 开发者设置页面配置回调 URL并打开回调开关。
回调的方向是即时通信 IM 后台向 App 后台发起 HTTP POST 请求。
收到事件通知后应异步处理内部逻辑，同步返回接收成功应答。
App 后台在收到回调请求之后，务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。
其他安全相关事宜请参见 第三方回调简介：安全考虑 文档。

接口说明

请求 URL 示例

以下示例中 App 配置的回调 URL 为 https://www.example.com。 示例：
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

请求参数说明

参数
说明
https
请求协议为 HTTPS，请求方式为 POST。
www.example.com
回调 URL。
SdkAppid
创建应用时在即时通信 IM 控制台分配的 SDKAppID。
CallbackCommand
固定为 Desk.SessionEventNotify。
contenttype
固定值为 json。
ClientIP
客户端 IP，格式例如：127.0.0.1。

请求包示例

{
    "CallbackCommand": "Desk.SessionEventNotify",
    "SessionId": "2baf4d84-beb4-4607-a1ea-6ebcaef3e0e6",
    "Event": "ChatBot.UserSendMsg",
    "EventTime": 1725540020017,
    "ChannelType": "SDK",
    "ClientUserId": "your_user_id",
    "CustomerServiceId": "@customer_service_account",
    "AgentId": "test@qq.com",
    "MsgKey": "152_1600012345_abcdefg",
    "MsgBody": [
        {
            "MsgType": "TIMTextElem",
            "MsgContent": {
               "Text": "请问如何申请退费？"
            }
        }
    ],
    "CloudCustomData": "your cloud custom data",
    "IsContactUser": false,
    "SatisfactionSelected": 5,
    "ForwardFromAgentId":""
}

请求包字段说明

字段
类型
说明
CallbackCommand
String
回调命令。
SessionId
String
会话的 SessionID。
Event
String
事件类型：详见事件类型列表及说明。
EventTime
Integer
事件触发的毫秒级别时间戳。
ChannelType
String
集成方式：
SDK：SDK 集成，对应智能客服管理端的“应用/客户端”集成。
Web(H5)：Web 集成，对应智能客服管理端的“网页（H5）”集成。
ClientUserId
String
用户的 UserID。
CustomerServiceId
String
客服号的 UserID。
AgentId
String
人工客服 ID。
MsgKey
String
消息回调的消息 Key。
MsgBody
Array
消息回调的消息体，具体请参见 消息格式描述。
CloudCustomData
String
消息自定义数据，具体请参见 消息格式描述。
IsContactUser
Bool
是否客服主动联系用户。
SatisfactionSelected
Integer
满意度评价星级（1 ~ 5），例如：5代表评价为五星。
ForwardFromAgentId
String
转接事件发起的人的客服 ID，仅 AgentForward 事件此字段有效。

事件类型列表及说明

事件类型
说明
SessionBegin
会话开始。
ChatBot.UserSendMsg
机器人阶段中用户发送的消息。
ChatBot.RobotSendMsg
机器人阶段中机器人回复的消息。
Human.UserSendMsg
人工阶段中用户发送的消息。
Human.AgentSendMsg
人工阶段中客服发送的消息。
TransferringToHuman
转人工中。
TransferringToHumanWait
转人工排队中。
TransferToHumanSuccess
转人工成功。
NoAgentOnline
无人工客服在线。
AgentForward
客服转接。
SatisfactionSelected
满意度评价。
SessionUserEnd
用户结束会话。
SessionAgentEnd
客服结束会话。
SessionUserTimeoutEnd
用户应答超时结束会话。
SessionAgentTimeoutEnd
客服应答超时结束会话。
SessionPendingAutoFinishEnd
排队中自动结束（用户离线）。
SessionEnd
会话结束。
MemberAccessTimeout
客服成员接入超时。

应答包示例

App 后台同步数据后，发送回调应答包。
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0
}

应答包字段说明

字段
类型
属性
说明
ActionStatus
String
必填
请求处理的结果，OK 表示处理成功，FAIL 表示失败。
ErrorCode
Integer
必填
错误码，此处填0表示忽略应答结果。
ErrorInfo
String
必填
错误信息。



中国站
目录