在线客服咨询接口

/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均自定义

描述	字段	类型
是否成功	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":{}
}

2025-04-23

在线客服咨询接口

一、创建会话

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内容

本页目录