在线客服访客消息管理接口

本接口的使用需要接口使用方有研发能力，本接口实现的业务场景是：针对访客消息，您这边有自己的业务逻辑（如有自己的机器人），只有需要使用人工在线客服的时候才接入到客服系统。原理解析：云客服厂商提供一个接收在线客服消息的地址，当有访客消息需要客服人员处理时，您调用云客服厂商提供的接口发起请求，把信息推送给客服。当客服回复消息后，云客服会把对应的消息再推送给您，从而实现会话交流的能力。

注：使用openapi接口前，首先需要参照接口鉴权说明完成鉴权

/openapi/im/newChat

POST

描述	字段	类型	必填	备注
访客ID	visitorId	String	Y	访客的唯一标识
访客名称	visitorName	String	N
渠道ID	channelId	String	Y	在云客服的OpenAPI渠道中获取，用于绑定会话流程
访客IP	visitorIP	String	N	IPv4地址
访客头像URL	visitorHeadImg	String	N
扩展参数	otherParams	json	N	json对象，传参内容将展示在座席端的会话框右侧，key和value均自定义
会话创建时间（毫秒时间戳）	createTimestamp	Long	N	创建会话时传递该参数，则以该字段作为会话创建时间，若未传递该参数，则默认以云客服创建时间作为会话创建，该时间点不可晚于当前时间

描述	字段	类型
是否成功	success	Boolean
响应码	code	String
响应信息	message	String
响应数据内容	data	object

描述	字段	类型
会话ID	sessionId	String
创建会话的时间戳	createTimestamp	long

{
  "requestId": "8b1a775e2a8a267173bfe7f1cace4723467",
  "async": true,
  "callBack": "https://callBack.domain.com/im/newMsg/callBack",
  "contentType": "text",
  "content": "您好，我想咨询一个问题。",
  "visitorId": "7f1cace47234673a425502670ab44c422",
  "visitorName": "张三",
  "channelId": "ioACBxXx36IlKn5c",
  "visitorIP": "171.211.101.9",
  "replyId": "c820d53d-98a3-4bc9-a676-0eb93649e89f",
  "visitorHeadImg": "https://oss.domain.cn/img/0NjczYTQyNTUwMjY3MGFiN.png",
  "historyMsgList": [
    {
      "contentType": "text",
      "content": "您好",
      "timestamp": 1744790189175,
      "type": "out",
      "showHtml": false
    },
    {
      "contentType": "text",
      "content": "有什么可以帮您的？",
      "timestamp": 1744790189289,
      "type": "out",
      "showHtml": false
    }
  ]
}

{
  "success": true,
  "code": "200",
  "message": "200 ok!",
  "data": {
    "request": {},
    "response": {
      "sessionId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
      "messageId": "",
      "createTimestamp": 1685092455601
    }
  }
}

/openapi/im/newMsg

POST

描述	字段	类型	必填	备注
请求唯一ID	requestId	String	Y	用于消息防抖、日志查询
是否异步请求	async	Boolean	N	异步请求：true 同步请求：false
异步回调	callBack	String	C	条件必传。若async为true时，callBack必传
消息内容类型	contentType		Y	文本/富文本：text 图片：image 文件：file 语音：voice 视频：video 商品卡片：goodsCard （卡片内容见5.4）
消息内容	content	String	Y	支持富文本格式，上限2000个字符
访客ID	visitorId	String	Y	访客的唯一标识
访客名称	visitorName	String	N
渠道ID	channelId	String	Y	在云客服的OpenAPI渠道中获取，用于绑定会话流程
访客IP	visitorIP	String	N	IPv4地址
引用消息ID	replyId	String	N	若有消息引用，传被引用的messageId
访客头像URL	visitorHeadImg	String	N
历史聊天记录	historyMsgList	List<HistoryMsg>	N	传此参数，可保存历史聊天记录。

HistoryMsg参数如下：

描述	字段	类型	必填	备注
消息内容类型	contentType	String	Y	文本/富文本：text 图片：image 文件：file 语言：voice 视频：video
消息内容	content	String	Y
消息时间戳	timestamp	Long	Y	消息列表按此字段升级排列
消息类型	type	String	Y	system 系统发送的消息 in 访客发送的消息 out 座席发送的消息 robot 机器人发送的消息
内容是否为HTML富文本	showHtml	Boolean	N	非必填、默认为false

描述	字段	类型
是否成功	success	Boolean
响应码	code	String
响应信息	message	String
响应数据内容	data	object	请求参数async为false时见2.5

描述	字段	类型
会话ID	sessionId	String
消息ID	messageId	String
创建消息的时间戳	createTimestamp	long

{
  "requestId": "8b1a775e2a8a267173bfe7f1cace4723467",
  "async": true,
  "callBack": "https://callBack.domain.com/im/newMsg/callBack",
  "contentType": "text",
  "content": "您好，我想咨询一个问题。",
  "visitorId": "7f1cace47234673a425502670ab44c422",
  "visitorName": "张三",
  "channelId": "ioACBxXx36IlKn5c",
  "visitorIP": "171.211.101.9",
  "replyId": "c820d53d-98a3-4bc9-a676-0eb93649e89f",
  "visitorHeadImg": "https://oss.domain.cn/img/0NjczYTQyNTUwMjY3MGFiN.png"
}

{
  "success": true,
  "code": "200",
  "message": "200 ok!",
  "data": {
      "sessionId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
      "messageId": "00dead4c-ef57-4929-948d-dd1fc39b2182",
      "createTimestamp": 1685092455601
  }
}

描述	字段	类型	备注
原请求体	request	object	见2.3 请求参数
异步响应内容	response	object	见2.5 表格

示例：

{
    "request": {
      "requestId": "8b1a775e2a8a267173bfe7f1cace4723467",
      "async": true,
      "callBack": "https://callBack.domain.com/im/newMsg/callBack",
      "contentType": "text",
      "content": "您好，我想咨询一个问题。",
      "visitorId": "7f1cace47234673a425502670ab44c422",
      "visitorName": "张三",
      "channelId": "ioACBxXx36IlKn5c",
      "visitorIP": "171.211.101.9",
      "replyId": "c820d53d-98a3-4bc9-a676-0eb93649e89f",
      "visitorHeadImg": "https://oss.domain.cn/img/0NjczYTQyNTUwMjY3MGFiN.png"
    },
    "response": {
      "sessionId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
      "messageId": "00dead4c-ef57-4929-948d-dd1fc39b2182",
      "createTimestamp": 1685092455601
    }
}

/openapi/im/queryMsg

POST

描述	字段	类型	必填	备注
访客ID	visitorId	String	Y	访客的唯一标识
查询页码	pageIndex	number	Y	默认1
每页查询数量	pageSize	number	Y	默认20

描述	字段	类型
是否成功	success	Boolean
响应码	code	String
响应信息	message	String
响应数据内容	data	object

描述	字段	类型	备注
消息列表	list	array	按消息时间逆序
分页数据	page	object

描述	字段	类型	备注
消息ID	messageId	String
消息时间	time	String	yyyy-MM-dd HH:mm:ss
消息类型	messageType	String	访客发送：in座席发送：out系统消息：system 机器人消息：robot
消息内容类型	contentType	String	见2.3
消息内容	content	String
引用消息内容	replyMsg	Object	结构与推送消息中的replyMsg一致，详情见3.8中的示例
座席名称	agentName	String
座席工号	agentNumber	String
座席头像URL	agentHeadImg	String
是否已读	read	Boolean

{
  "visitorId": "7f1cace47234673a425502670ab44c422",
  "pageIndex": 1,
  "pageSize": 20
}

{
  "success": true,
  "code": "200",
  "message": "200 ok!",
  "data": {
    "list": [
      {
        "messageId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
        "time": "2024-08-04 15:36:51",
        "messageType": "in",
        "contentType": "text",
        "content": "您好，我想咨询一个问题。",
        "replyMsg": {
            "messageId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
            "time": "2024-08-04 15:36:51",
            "messageType": "in",
            "contentType": "text",
            "content": "您好，我想咨询一个问题。",
            "replyMsg": "",
            "agentName": "客服A001",
            "agentNumber": "6001",
            "agentHeadImg": "https://oss.domain.cn/img/0NjczYTQyNTUwMjY3MGFiN.png",
            "read": true,
        },
        "agentName": "客服A001",
        "agentNumber": "6001",
        "agentHeadImg": "https://oss.domain.cn/img/0NjczYTQyNTUwMjY3MGFiN.png",
        "read": true,
      }
    ],
    "page": {
      "totalPage": 3,
      "total": 52,
      "pageIndex": 1,
      "pageSize": 20
    }
  }
}

/openapi/im/visitorStatus

POST

描述	字段	类型	必填	备注
访客ID	visitorId	String	Y	访客的唯一标识
状态	contentType	String	Y	访客在线：newConn访客离线：disConn
渠道ID	channelId	String	Y

描述	字段	类型
是否成功	success	Boolean
响应码	code	String
响应信息	message	String
响应数据内容	data	object

{
  "visitorId": "7f1cace47234673a425502670ab44c422",
  "contentType": "newConn",
  "channelId": "ioACBxXx36IlKn5c"
}

{
  "success": true,
  "code": "200",
  "message": "200 ok!",
  "data": null
}

当座席发消息后，会使用此消息发送给后台配置的消息接收接口。默认发送成功，无返回值格式要求

描述	字段	类型	备注
渠道ID	channelId	String
消息内容	content	String
消息内容类型	contentType	String	文本/富文本：text 图片：image 文件：file 语音：voice 视频：video 排队信息：queue 座席接入：claim 自动关闭：autoClose 结束会话：finish
消息ID	messageId	String
消息类型	msgType	String	访客发送：in座席发送：out系统消息：system
会话ID	sessionId	String
访客ID	visitorId	String
引用消息	replyMsg	Object	见5.2
文件名称	fileNameString	String
文件大小	fileSize	String
座席名称	agentName	String
座席头像	agentHead	String	url

描述	字段	类型
消息内容	content	String
消息内容类型	contentType	String
消息类型	msgType	String	访客发送：in座席发送：out
消息ID	messageId	String

{
  "channelId": "0h63QEMNzCPj8Ebp",
  "content": "座席发送的内容",
  "contentType": "text",
  "messageId": "00dead4c-ef57-4929-948d-dd1fc39b2182",
  "msgType": "out",
  "replyMsg": {
    "content": "被引用的内容",
    "contentType": "text",
    "messageId": "28548577-58d5-4063-8486-d8a05d3fbefe",
    "msgType": "in"
  },
  "sessionId": "47832881-f69a-4ca6-a0e4-fc68851af7cd",
  "visitorId": "jhgqkwhugvekhbckhvaskubdiuhasd"
}

描述	字段	类型
卡片类型	contentType	String	云客服内置商品卡片：goodsCard置换卡片：exchangeCard门店卡片：storeCard车型介绍链接卡片：carTypeCard
标题	title	String
描述	desc	String
图片	img	String
备注	remark	String
超链接	url	String
附加信息	data	Object

推送消息RequestBody如下：

{"agentHead":"","agentName":"lzj 的昵称","channelId":"EFKdKrDLD87aJ5Zv","content":"{\"contentType\":\"goodsCard\",\"title\":\"商品卡片标题Title\",\"desc\":\"商品卡片描述内容\",\"img\":\"https://yanxuan-item.nosdn.127.net/84a59ff9c58a77032564e61f716846d6.jpg\",\"remark\":\"商品卡片备注\",\"url\":\"https://www.baidu.com/\"}","contentType":"goodsCard","messageId":"4960727a-19d5-4363-b36a-0a7fb0600fb7","msgType":"out","sessionId":"34cca44c-2712-4666-a1dc-2ce751482f3b","visitorId":"7f1cacexxxxx2550267013233ab44c422"}

content是JSON字符串，对其反序列化如下：

{
  "contentType": "goodsCard",
  "title": "商品卡片标题Title",
  "desc": "商品卡片描述内容",
  "img": "https://yanxuan-item.nosdn.127.net/84a59ff9c58a77032564e61f716846d6.jpg",
  "remark": "商品卡片备注",
  "url": "https://www.baidu.com/",
  "data":{}
}

触发时机： 会话进入排队或排队顺位刷新时。

字段	类型	必填	说明
messageId	string	是	通知关联的消息 ID，具体含义见各通知类型
msgType	string	是	排队通知为 system
contentType	string	是	queue
content	string	是	展示提示文本
visitorId	string	是	目标访客 ID
sessionId	string	是	关联会话 ID
channelId	string	是	API 渠道 ID
createTimestamp	integer	是	本次通知发生时间，Unix 毫秒时间戳
queueNum	integer	是	当前访客的排队顺位，从 1 开始

{
  "messageId": "queue-event-001",
  "msgType": "system",
  "contentType": "queue",
  "content": "您当前排在第3位，请稍候。",
  "visitorId": "visitor-001",
  "sessionId": "session-001",
  "channelId": "channel-api-001",
  "createTimestamp": 1791763202000,
  "queueNum": 3
}

接收处理：

queueNum=3 表示当前访客排第 3 位，前方有 2 位；不是前方有 3 位。

每次排队通知有独立 messageId，按 sessionId 更新排队展示，按 createTimestamp 忽略更旧的通知。

content 为平台提供的提示文本，客户也可根据 queueNum 展示排队顺位。

会话进入接待或结束后清除对应排队展示；不将 queueNum=0 解释为取消排队通知。

触发时机： 客服撤回该 API 渠道的消息时。

字段	类型	必填	说明
messageId	string	是	表示被撤回的原消息 ID
msgType	string	是	撤回通知为 system
contentType	string	是	revoke
content	string	是	展示提示文本
visitorId	string	是	目标访客 ID
sessionId	string	是	关联会话 ID
channelId	string	是	API 渠道 ID
createTimestamp	integer	是	本次通知发生时间，Unix 毫秒时间戳。表示撤回通知时间。

{
  "messageId": "agent-message-001",
  "msgType": "system",
  "contentType": "revoke",
  "content": "消息已撤回",
  "visitorId": "visitor-001",
  "sessionId": "session-001",
  "channelId": "channel-api-001",
  "createTimestamp": 1791763203000
}

接收处理：

根据 messageId 更新原消息为撤回状态，停止展示原消息内容。

去重时区分 contentType，不能因为该 ID 已用于原消息而忽略撤回通知。

撤回通知先到达时保留撤回标记，后续收到原消息也保持撤回状态；重复撤回不新增展示记录。

触发时机： 客服主动邀请、客服结束会话邀请或系统结束会话邀请，具体由租户满意度配置决定。

字段	类型	必填	说明
messageId	string	是	表示满意度邀请消息 ID，客户须保存并在结果上报时原样传入。
msgType	string	是	满意度邀请为 csrInvite
contentType	string	是	csrInvite
content	string	是	展示提示文本
visitorId	string	是	目标访客 ID
sessionId	string	是	关联会话 ID
channelId	string	是	API 渠道 ID
createTimestamp	integer	是	本次通知发生时间，Unix 毫秒时间戳
satisfactionConfig	object	是	调查展示配置，字段定义见第 2 节，不含 channelSatisfaction

{
  "messageId": "invite-message-001",
  "msgType": "csrInvite",
  "contentType": "csrInvite",
  "content": "请评价本次服务。",
  "visitorId": "visitor-001",
  "sessionId": "session-001",
  "channelId": "channel-api-001",
  "createTimestamp": 1791763204000,
  "satisfactionConfig": {
    "type": "radioTagText",
    "satisfyTitle": "请评价客服001本次的服务。",
    "satisfyThank": "感谢您的评价。",
    "aging": true,
    "agingTimeout": 24,
    "systemClosePushCsr": true,
    "agentClosePushCsr": true,
    "customerClosePushCsr": false,
    "agentPushCsr": true,
    "customerPushCsr": false,
    "radioTagText": [
      {
        "key": "satisfied",
        "name": "满意",
        "icon": "https://assets.example.com/satisfaction/satisfied.png",
        "reason": ["解答清晰", "处理及时"],
        "proposalStatus": "unRequired",
        "defaultIndex": 1,
        "use": true
      },
      {
        "key": "unsatisfied",
        "name": "不满意",
        "icon": "https://assets.example.com/satisfaction/unsatisfied.png",
        "reason": ["未解决问题", "等待时间长"],
        "proposalStatus": "required",
        "defaultIndex": 1,
        "use": true
      }
    ]
  }
}

接收处理：

保存 channelId、sessionId 和邀请 messageId，作为上报关联标识。

使用推送中的调查配置展示邀请及感谢文案，仅展示 use=true 的选项。

选项 key 由租户配置决定，示例中的 satisfied、unsatisfied 不是固定枚举。

客户收到邀请后自行展示调查，访客选择后调用第 3 节结果上报接口。

2026-10-14

在线客服访客消息管理接口

一、创建会话

1.1 请求路径

1.2 请求方法

1.3 请求参数

1.4 响应参数

1.5 请求示例

1.6 响应示例

二、访客发送新消息

2.1 请求路径

2.2 请求方法

2.3 请求参数

2.4 响应参数

2.5 同步请求后响应的data数据字段

2.6 请求示例

2.7 响应示例

2.8 异步请求推送的消息结果

三、查询聊天记录

3.1 请求路径

3.2 请求方法

3.3 请求参数

3.4 响应参数

3.5 响应的data数据字段

3.6 响应的消息字段

3.7 请求示例

3.8 响应示例

四、访客在线状态

4.1 请求路径

4.2 请求方法

4.3 请求参数

4.4 响应参数

4.5 请求示例

4.6 响应示例

五、座席消息推送

5.1 推送消息字段

5.2 引用消息replyMsg结构

5.3 推送数据示例：

5.4 商品卡片推送消息content内容

六、排队提示推送

6.1 推送字段

6.2 推送示例

七、消息撤回推送

7.1 推送字段

7.2 推送示例

八、满意度调查推送

8.1 推送字段

8.2 推送示例

本页目录