UE Chat Agent SDK 对接文档
一、场景说明
使用 ue-chatagent-sdk 可以将在线客服(WebChat)能力集成到业务系统中,支持:
- 在线 SDK 初始化与登录
- 事件监听(消息、系统事件、互踢)
- 座席状态获取与切换
- 会话列表、历史消息、消息收发
- 会话操作(结束、稍后处理、置顶、拉黑、撤回)
- 批量操作(批量稍后处理、批量取消稍后处理)
- 可选语音/视频通话能力(WebRTC)
二、对接步骤
1、在线 SDK 初始化
const ueChatAgent = new UEChatAgent()
UEChatAgent.init({
debug: true,
accountName: '账号名@租户',
password: 'xxx',
server: 'https://dev1.useasy.cn/api',
loginType: 'WEBRTC', // WEBRTC / PSTN / SIP
success: function () {
console.log('SDK initialized successfully');
},
error: function (e) {
console.error(e, 'Failed to initialize SDK');
}
});
2、监听在线事件信息
ueChatAgent.listenWebchatEvent({
success(res) {
console.log(res, '监听成功');
},
message: (res) => {
console.log(res, '接收事件成功');
},
event: (res) => {
console.log(res, 'socket互踢');
}
})
3、事件回调基础结构
message 回调参数结构:
{
"subtype": "事件类型",
"data": {}
}
三、座席与会话能力(当前 SDK 已开放)
1、获取在线状态列表
/**
* getAgentStatus:获取在线状态列表
* @return Promise<ResponseResult>
*/
const res = await ueChatAgent.getAgentStatus()
响应结果示例:
{
"success": true,
"message": "200 ok!",
"code": "200",
"data": [
{
"_id": "4cfec9fc-960a-4f91-bbba-f76b45fa0ec1",
"status": "open",
"name": "空闲",
"type": "system",
"label": "online",
"loginDefault": false
}
],
"traceId": "xxx"
}
2、切换座席在线状态
/**
* switchStatus:切换座席在线状态
* @return Promise<ResponseResult>
*/
ueChatAgent.switchStatus(socketId, statusId)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| socketId | string | 是 | 当前 socketId |
| statusId | string | 是 | 切换后的状态Id |
3、获取消息列表(会话列表)
支持筛选维度:
- 会话分组:处理中、排队中、全部、稍后处理
- 排序:最新消息、接入顺序、访客等待时长
- 访客名输入筛选
const requestParams = {
submenu: 'webchat_todo',
sort: 'latest',
visitorName: '',
limit: 10,
page: 1,
simpleField: true,
agentIds: [],
sessionType: 'all',
finishKey: [],
channelIds: [],
satisfactionName: [],
createTime: ['2025-11-06 00:00:00', '2025-11-12 23:59:59'],
endTime: []
}
const res = await ueChatAgent.getSessionList(requestParams)
4、开始会话
/**
* reNewChat:开始会话(重新发起会话)
* @params config { fromSessionId: string, visitorId: string}
* @return Promise<ResponseResult>
*/
ueChatAgent.reNewChat(config)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| fromSessionId | string | 是 | 需要重新发起的会话id |
| visitorId | string | 是 | 访客id |
5、获取历史消息
/**
* getHistoryMessage:获取历史消息(分页)
* @params queryConfig { visitorId: string, limit: number, dateTime: number }
* @return Promise<ResponseResult>
*/
ueChatAgent.getHistoryMessage(queryConfig)
参数说明:
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| visitorId | string | 是 | 无 | 访客id |
| limit | number | 否 | 20 | 请求的消息数量 |
| dateTime | number | 否 | new Date().getTime() | 上一页最后一条消息时间 |
响应结果示例(节选):
{
"success": true,
"message": "200 ok!",
"code": "200",
"data": [
{
"type": "system",
"createTimestamp": 1751353280452,
"contentType": "disConn",
"_id": "xxx",
"visitorId": "xxx",
"channelId": "xxx",
"beFrom": "wap",
"sessionId": "xxx",
"createTime": "2025-07-01 15:01:20"
}
],
"traceId": "xxxx"
}
6、关闭会话(批量结束会话)
/**
* batchFinishWebchatSession:关闭会话(可批量)
* @params finishData { visitorId: string, _id: string }[]
* @return Promise<ResponseResult>
*/
ueChatAgent.batchFinishWebchatSession(finishData)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| finishData | array | 是 | 关闭的会话数据 |
| finishData[].visitorId | string | 是 | 访客id |
| finishData[]._id | string | 是 | 会话id |
响应结果:
{
"success": true,
"message": "200 ok!",
"code": "200",
"data": "结束全部会话1条",
"traceId": "xxx"
}
7、发送消息
支持 contentType:text、image、video、file。
/**
* reply:发送消息
* @params ReplyDto
* @return Promise<ResponseResult>
*/
ueChatAgent.reply(ReplyDto)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| beFrom | string | 是 | 来源 |
| channelId | string | 是 | 渠道id |
| content | string | 是 | 发送消息内容 |
| contentType | string | 是 | text / image / video / file |
| replyId | string | 否 | 引用消息id |
| replyMsg | object | 否 | 引用消息详情 |
| sessionId | string | 是 | 会话id |
| timeStamp | number | 是 | 时间戳 |
| visitorId | string | 是 | 访客id |
| visitorName | string | 否 | 访客名称 |
响应结果示例(节选):
{
"success": true,
"message": "200 ok!",
"code": "200",
"data": {
"messageId": "c49ee568-217f-485b-ba16-7fe1b0c3791c",
"createTimestamp": 1763347580355,
"data": {
"_id": "c49ee568-217f-485b-ba16-7fe1b0c3791c",
"contentType": "text",
"content": "<p>of</p>",
"sessionId": "78437a9d-1f24-4c67-b763-726fb4a77c58",
"visitorId": "1090@V2T58dWlSFkmjKnN@mpugkasu@web",
"sensitive": true,
"sensitiveWords": ["of"]
}
}
}
8、座席已读消息提示
/**
* readMessage:座席已读消息
* @params params { visitorId: string; channelId: string; sessionId: string; messageIdList: string[]; beFrom: string; }
* @return Promise<ResponseResult>
*/
ueChatAgent.readMessage(params)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| visitorId | string | 是 | 访客id |
| channelId | string | 是 | 渠道id |
| sessionId | string | 是 | 会话id |
| messageIdList | string[] | 是 | 未读消息id列表 |
| beFrom | string | 是 | 渠道来源 |
9、座席输入提示
/**
* typeNotice:座席输入提示
* @params params { sessionId: string }
* @return Promise<ResponseResult>
*/
ueChatAgent.typeNotice(params)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| sessionId | string | 是 | 会话id |
10、稍后处理
/**
* laterProcess:稍后处理
* @params sessionId string 会话id
* @return Promise<ResponseResult>
*/
ueChatAgent.laterProcess(sessionId)
11、批量稍后处理
/**
* batchLaterProcess:批量稍后处理
* @params ids [string] 会话id数组
* @return Promise<ResponseResult>
*/
ueChatAgent.batchLaterProcess(ids)
12、批量取消稍后处理
/**
* batchLaterCancel:批量取消稍后处理
* @params ids [string] 会话id数组
* @return Promise<ResponseResult>
*/
ueChatAgent.batchLaterCancel(ids)
13、会话置顶
/**
* setTop:会话置顶
* @params sessionId string 会话id
* @return Promise<ResponseResult>
*/
ueChatAgent.setTop(sessionId)
14、取消置顶
/**
* cancelTop:取消置顶
* @params sessionId string 会话id
* @return Promise<ResponseResult>
*/
ueChatAgent.cancelTop(sessionId)
15、拉黑访客
/**
* blockVisitors:拉黑访客
* @params params { blackType: string; visitorName: string; visitorId: string; sessionId: string; ip: string; blackReason: string; }
* @return Promise<ResponseResult>
*/
ueChatAgent.blockVisitors(params)
参数说明:
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| blackType | 'ip' | 'visitorId' | 是 | 拉黑类型 |
| blackReason | string | 是 | 拉黑原因 |
| ip | string | 是 | ip地址 |
| sessionId | string | 是 | 会话id |
| visitorId | string | 是 | 访客id |
| visitorName | string | 是 | 访客名称 |
16、撤回消息
/**
* revoke:撤回消息
* @params messageId string 消息id
* @return Promise<ResponseResult>
*/
ueChatAgent.revoke(messageId)
四、语音视频能力(当前 SDK 已开放)
1、发起语音会话 / 视频会话
// 语音
await ueChatAgent.call({ _id: sessionId, visitorId }, false)
// 视频
await ueChatAgent.call({ _id: sessionId, visitorId }, true)
2、通过 callService 控制通话
const callService = ueChatAgent.getCallService()
// 发起呼叫
await callService.call({ _id: sessionId, visitorId }, false, {
onEvent: (type, data) => console.log(type, data)
})
// 接受来电(语音/视频)
callService.answer(false) // 语音接听
callService.answer(true) // 视频接听
// 拒绝/挂断
callService.hangup()
说明:当前 SDK 没有单独 reject 方法,拒绝可通过 hangup() 处理。
五、事件说明
建议优先接入以下事件类型:
imAgentStatusSync:座席状态同步IM_ASSIGN_EVENT:排队数更新、新会话分配NewWebchat:新消息、访客上线/离线、访客消息NewNotify:自动结束、关闭提醒、通话时长提示typeNotice:访客输入提醒agentOperateEvent:App 端操作同步(发消息、撤回、结束会话、转接等)realTimeQualityEvent:实时质检(敏感词)imImageSensitive:图片敏感检测结果
六、事件样例(31~66)
31. 座席状态(imAgentStatusSync)
{
"data": {
"_id": "2a69a425-f35e-4fe3-87f4-5b6a26e88d34",
"socketId": "system",
"changeStatus": false
},
"eventId": "c79de4f8-439f-40a9-8c9c-d6dbe9176465",
"eventTime": 1762846917558,
"eventType": "im",
"subType": "imAgentStatusSync"
}
32. 排队中会话个数(IM_ASSIGN_EVENT)
{
"data": {
"unDealNum": 3,
"eventType": "refreshAgentUnDealNum"
},
"eventId": "648010bb-8e5b-45b9-9ebd-77412bef4194",
"eventTime": 1762858254349,
"eventType": "im",
"subType": "IM_ASSIGN_EVENT"
}
33. 新会话接入(IM_ASSIGN_EVENT)
{
"data": {
"eventType": "newChat",
"newChatList": [
{
"_id": "16257c95-e7c1-4684-a5b0-6fdd894daa6f",
"visitorId": "1090@hZC9c2LzYhrBfnbC@312j72vo@web",
"visitorName": "mdo6gu9rdwug",
"status": "deal",
"channelId": "hZC9c2LzYhrBfnbC",
"lastMessage": {
"contentType": "goodsCard",
"lastMessageFrom": "customer"
}
}
]
},
"eventType": "im",
"subType": "IM_ASSIGN_EVENT"
}
34. 访客上线(NewWebchat)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"visitorName": "\"宇宙无敌的探索家6058\"",
"beFrom": "pc",
"channelId": "hZC9c2LzYhrBfnbC",
"visitorId": "Syy1930510276829036544",
"eventType": "newConn",
"status": "deal"
},
"eventType": "im",
"subType": "NewWebchat"
}
35. 访客离线(NewWebchat)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"visitorId": "Syy1930510276829036544",
"contentType": "disConn",
"content": "",
"type": "system",
"eventType": "disConn",
"status": "deal"
},
"eventType": "im",
"subType": "NewWebchat"
}
36. 访客关闭会话(NewWebchat)
{
"data": {
"_id": "d0686c9c-4579-4565-972d-9e5c7b2c9919",
"visitorId": "Syy1930510276829036544",
"contentType": "disConn",
"content": "",
"type": "system",
"eventType": "disConn"
},
"eventType": "im",
"subType": "NewWebchat"
}
37. 会话即将关闭提醒(NewNotify)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"messageId": "f924967a-37ba-41ef-8a22-4c9cdf847baf",
"contentType": "autoClose",
"content": "会话即将关闭\n",
"eventType": "newMsg",
"showTip": true
},
"eventType": "im",
"subType": "NewNotify"
}
38. 自动结束会话(NewNotify)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"eventType": "autoClose",
"showTip": true
},
"eventType": "im",
"subType": "NewNotify"
}
39. 收到访客消息(NewWebchat)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"messageId": "a10932a0-a4ab-42e4-bf58-c7f4f426fd38",
"contentType": "text",
"content": "fda",
"type": "in",
"eventType": "newMsg",
"status": "deal"
},
"eventType": "im",
"subType": "NewWebchat"
}
40. 访客输入提醒(typeNotice)
{
"data": {
"accountId": "1090",
"channelId": "hZC9c2LzYhrBfnbC",
"visitorId": "Syy1930510276829036544",
"sessionId": "80b9381b-857e-4101-b7c5-55292c6f368f",
"content": "访客输入"
},
"eventType": "im",
"subType": "typeNotice"
}
41. 访客阅读会话提醒(visitor_deal_msg)
{
"data": {
"_id": "80b9381b-857e-4101-b7c5-55292c6f368f",
"agentReplyMessageCount": 0,
"lastMessageTimestamp": 0,
"visitorMessageCount": 0
},
"eventType": "im",
"subType": "visitor_deal_msg"
}
42. 访客评价座席(NewWebchat)
{
"data": {
"_id": "fbbe35c8-47b0-4570-9f7c-ba04f3591f0e",
"messageId": "71e02534-5f7a-44ec-8658-271568488eea",
"contentType": "csrSubmit",
"content": "用户已评价很满意/满意、还可以/没有",
"satisfactionData": {
"satisfactionName": "很满意",
"satisfactionReason": ["满意", "还可以"],
"satisfactionProposal": "没有"
}
},
"eventType": "im",
"subType": "NewWebchat"
}
43. 会话首次响应时间同步(agentFirstReplyTime)
{
"data": {
"agentFirstReplyTime": "2025-11-12 11:09:20",
"sessionId": "c6a24b6b-6cb0-4427-a64d-74e853b2e278"
},
"eventType": "im",
"subType": "agentFirstReplyTime"
}
44. 消息同步提醒(app 端)
{
"data": {
"data": {
"_id": "72f68824-db10-48e8-bb06-698b9760f245",
"contentType": "text",
"content": "app发送信息",
"type": "out",
"sessionId": "c6a24b6b-6cb0-4427-a64d-74e853b2e278"
},
"operateEvent": "IM_SEND_MSG"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
45. app 端撤回消息提醒
{
"data": {
"data": {
"_id": "9ddd1c74-cb12-4f39-9103-f5e02e8a2ecc",
"contentType": "text",
"content": "撤回消息",
"sessionId": "c6a24b6b-6cb0-4427-a64d-74e853b2e278"
},
"operateEvent": "IM_REVOKE_MSG"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
46. app 端主动结束会话
{
"data": {
"data": ["c6a24b6b-6cb0-4427-a64d-74e853b2e278"],
"operateEvent": "IM_FINISH_SESSION"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
47. app 端转接会话
{
"data": {
"data": "b8bf8753-3a59-4142-97f1-e47421ea5030",
"operateEvent": "IM_REDIRECT_SESSION"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
48. app 端重新发起会话
{
"data": {
"operateEvent": "IM_RESTART_CHAT"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
49. 被邀请座席接受操作同步(IM_AGENT_INVITE_ACCEPT_SYNC)
事件名已记录,数据结构以联调实际回包为准。
50. app 端插入会话同步信息
事件名已记录,数据结构以联调实际回包为准。
51. app 端修改会话数上限消息同步(消息未推送)
{
"data": {
"data": "{\"imEmailDealCount\":1,\"emailMaxLimit\":4,\"maxLimit\":5,\"minLimit\":1,\"emailMinLimit\":1,\"imDealCount\":5}",
"operateEvent": "IM_UPDATE_DEAL_LIMIT"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
52. 被叫方收到会话邀请提醒
{
"data": {
"data": {
"sessionId": "893a7dbc-a7df-42a6-ad93-3dc820e034f6",
"visitorName": "c7kp5z0daz3n",
"createAgent": "693212311909249024"
},
"operateEvent": "IM_AGENT_INVITE"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
53. 邀请座席收到同意
{
"data": {
"data": {
"visitorName": "\"宇宙无敌的探索家6058\"",
"agentId": "693212311909249024",
"sessionId": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac"
},
"operateEvent": "IM_AGENT_INVITE_ACCEPT"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
54. 被邀请座席收到邀请结束
{
"data": {
"data": {
"sessionId": "893a7dbc-a7df-42a6-ad93-3dc820e034f6",
"visitorName": "c7kp5z0daz3n",
"createAgent": "693212311909249024"
},
"operateEvent": "IM_AGENT_INVITE_OVER"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
55. 发起座席收到有座席拒绝
{
"data": {
"data": {
"visitorName": "c7kp5z0daz3n",
"agentId": "673696089139068928",
"sessionId": "893a7dbc-a7df-42a6-ad93-3dc820e034f6"
},
"operateEvent": "IM_AGENT_INVITE_REJECT"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
56. 座席发送消息触发敏感词(实时质检结果)
{
"data": {
"imWords": "<p>什么</p>"
},
"eventType": "im",
"subType": "realTimeQualityEvent"
}
57. 图片是否触发敏感词(imImageSensitive)
{
"data": {
"illegal": true,
"sensitive": true,
"sensitiveWords": [],
"sessionId": "e87503a6-1345-499f-b14a-5b7efbd71361",
"messageId": "6d8070c7-2366-47a2-a6e8-389e3f46076e",
"imageUrl": "https://xxx.obs.cn-southxxxx.xxxx.com/违禁词.png"
},
"eventType": "im",
"subType": "imImageSensitive"
}
{
"data": {
"illegal": false,
"sensitive": true,
"sensitiveWords": [],
"sessionId": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac",
"messageId": "fb8fc6b0-a5a9-4d73-b9b1-124dd5bd46d6"
},
"eventType": "im",
"subType": "imImageSensitive"
}
58. 会话抢接
原座席收到:
{
"data": {
"data": {
"visitorName": "\"宇宙无敌的探索家6058\"",
"sessionId": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac"
},
"operateEvent": "IM_REDIRECT_FORCE_SESSION_OLD"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
新座席收到:
{
"data": {
"data": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac",
"operateEvent": "IM_REDIRECT_FORCE_SESSION_NEW"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
59. 插入会话归属座席收到信息
{
"data": {
"data": {
"visitorName": "\"宇宙无敌的探索家6058\"",
"agentId": "693212311909249024",
"sessionId": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac"
},
"operateEvent": "IM_AGENT_FORCE_JOIN"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
60. 辅助座席退出会话
{
"data": {
"data": {
"visitorName": "\"宇宙无敌的探索家6058\"",
"agentId": "693212311909249024",
"sessionId": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac"
},
"operateEvent": "IM_MEMBERS_AGENT_EXIT"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
61. 转接、抢接时辅助座席收到事件
{
"data": {
"data": {
"_id": "751a3f6c-d56c-4fed-b731-ae3bd5f483ac",
"status": "deal",
"redirect": true,
"members": ["693212311909249024"],
"adminAndMembers": ["693212311909249024"]
},
"operateEvent": "IM_REDIRECT_SESSION_NOTIFY_MEMBERS"
},
"eventType": "event",
"subType": "agentOperateEvent"
}
62. 访客发起视频通话
{
"data": {
"_id": "e87503a6-1345-499f-b14a-5b7efbd71361",
"messageId": "02d02643-72eb-42ad-9a08-58b8a10d0767",
"contentType": "callVideo",
"content": "访客发起通话...",
"eventType": "newMsg"
},
"eventType": "im",
"subType": "NewWebchat"
}
63. 视频通话时长消息推送
{
"data": {
"_id": "969d719d-8a9f-46c7-93f8-d0cb2f993b66",
"messageId": "a704bda7-3efa-44b4-b1a0-e5a6aedc69b3",
"contentType": "callVideo",
"content": "通话时长 00:18",
"eventType": "newMsg",
"showTip": false
},
"eventType": "im",
"subType": "NewNotify"
}
64. 语音通话时长消息推送
{
"data": {
"_id": "969d719d-8a9f-46c7-93f8-d0cb2f993b66",
"messageId": "169c0099-8bd4-4be0-80ec-e13dd1a33708",
"contentType": "callVoice",
"content": "通话时长 00:10",
"eventType": "newMsg",
"showTip": false
},
"eventType": "im",
"subType": "NewNotify"
}
65. 访客发起语音通话
{
"data": {
"_id": "e87503a6-1345-499f-b14a-5b7efbd71361",
"messageId": "7306396c-7265-48f8-a96a-b57986843ec3",
"contentType": "callVoice",
"content": "访客发起通话...",
"eventType": "newMsg"
},
"eventType": "im",
"subType": "NewWebchat"
}
66. 座席主动发起满意度评价消息同步
事件名已记录,数据结构以联调实际回包为准。
七、注意事项
- 图片发送需关注
imImageSensitive与reply返回中的sensitive/sensitiveWords。 - 互踢事件(KICK_OFF)必须处理,避免多端登录导致通话/事件异常。
- 通话能力仅在
callService: true且 WebRTC 注册成功后可用。