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

会话事件回调

最近更新时间：2026-01-20 16:03:12

我的收藏

本页目录：

功能说明

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

注意事项

要启用回调，必须在 智能客服管理端 单击设置 > 开发者设置页面配置回调 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&
RequestID=$RequestID

请求参数说明

参数
说明
https
请求协议为 HTTPS，请求方式为 POST。
www.example.com
回调 URL。
SdkAppid
创建应用时在即时通信 IM 控制台分配的 SDKAppID。
CallbackCommand
固定为 Desk.SessionEventNotify。
contenttype
固定值为 json。
ClientIP
客户端 IP，格式例如：127.0.0.1。
RequestID
请求的 RequestID，用于唯一标识回调请求，当发生回调重试时，业务后台可以使用此字段进行去重处理。

请求包示例

请求包示例

机器人阶段用户消息回调。
{
    "CallbackCommand": "Desk.SessionEventNotify",
    "SessionId": "2baf4d84-beb4-4607-a1ea-6ebcaef3e0e6",
    "SubSessionId": "2baf4d84-beb4-4607-a1ea-6ebcaef3e0e6-1",
    "SubSessionNumber": 1,
    "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": "Desk.SessionEventNotify",
    "Event": "RobotMessageFeedback",
    "EventTime": 1725540020017,
    "ChannelType": "SDK",
    "ClientUserId": "your_user_id",
    "MsgKey": "152_1600012345_abcdefg",
    "MsgBody": [
        {
            "MsgType": "TIMTextElem",
            "MsgContent": {
               "Text": "你好啊"
            }
        }
    ],
    "CloudCustomData": "your cloud custom data",
    "FeedbackDetail": {
        "Type": 2,
        "MenuSelected": [
            {
                "Id": "101",
                "Content": "答非所问"
            }
        ],
        "OtherContent": "other feedback content"
    }
}

请求包字段说明

字段
类型
说明
CallbackCommand
String
回调命令。
SessionId
String
会话的 SessionID。
SubSessionId
String
子会话 ID。
SubSessionNumber
Integer
子会话序列。
Event
String
事件类型：详见事件类型列表及说明。
EventTime
Integer
事件触发的毫秒级别时间戳。
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 集成。
ClientUserId
String
用户的 UserID。
CustomerServiceId
String
客服号的 UserID。
AgentId
String
人工客服 ID。
AgentGroupId
Integer
人工客服所属的技能组 ID。
MsgKey
String
消息回调的消息 Key。
MsgBody
Array
消息回调的消息体，具体请参见 消息格式描述。
CloudCustomData
String
消息自定义数据，具体请参见 消息格式描述。
IsContactUser
Boolean
是否客服主动联系用户。
SatisfactionSelected
Integer
满意度评价星级（1 ~ 5），例如：5代表评价为五星。
ForwardFromAgentId
String
转接事件发起人的客服 ID，仅 AgentForward 事件此字段有效。
FeedbackDetail
Struct
机器人反馈的详情。仅 RobotMessageFeedback 事件此字段有效。
FeedbackDetail.Type
Integer
1：点赞。
2：点踩。
FeedbackDetail.MenuSelected
Array
反馈选择的固定问题选项列表。
FeedbackDetail.MenuSelected.Id
String
固定问题选项 ID。
FeedbackDetail.MenuSelected.Content
String
固定问题选项的内容。
FeedbackDetail.OtherContent
String
其他反馈内容。

事件类型列表及说明

事件类型
说明
SessionBegin
会话开始。
ChatBot.UserSendMsg
机器人阶段中用户发送消息。
ChatBot.RobotSendMsg
机器人阶段中机器人回复消息。
Human.UserSendMsg
人工阶段中用户发送消息。
Human.AgentSendMsg
人工阶段中客服发送消息。
TransferringToHuman
转人工中。
TransferringToHumanWait
转人工排队中。
TransferToHumanSuccess
转人工成功。
NoAgentOnline
无人工客服在线。
AgentForward
客服转接。
SatisfactionSelected
满意度评价。
SessionUserEnd
用户结束会话。
SessionAgentEnd
客服结束会话。
SessionUserTimeoutEnd
用户应答超时结束会话。
SessionAgentTimeoutEnd
客服应答超时结束会话。
SendReminderToUserBeforeTimeout
会话超时结束前向用户发出提醒。
SendReminderToAgentBeforeTimeout
会话超时结束前向客服发送提醒。
AgentResponseTimeoutAlertForStaff
客服超时未响应时提醒客服。
AgentResponseTimeoutAppeaseUser
客服超时未响应时安抚用户。
SessionPendingAutoFinishEnd
排队中自动结束（用户离线）。
SessionEnd
会话结束。
MemberAccessTimeout
客服成员接入会话超时。该事件会在以下两种情况出现：
接待方式设置为“手动接待”时，客服超过设定时间未接入会话。
客服登录微信小程序工作台后，将小程序切后台。有新会话时客服超过设定时间仍未打开小程序进行接待。
RobotMessageFeedback
机器人消息反馈。

应答包示例

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

应答包字段说明

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