在线座席端界面自定义

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、发送消息

支持 contentTypetextimagevideofile

/**
 * 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. 座席主动发起满意度评价消息同步

事件名已记录,数据结构以联调实际回包为准。

七、注意事项

  • 图片发送需关注 imImageSensitivereply 返回中的 sensitive/sensitiveWords
  • 互踢事件(KICK_OFF)必须处理,避免多端登录导致通话/事件异常。
  • 通话能力仅在 callService: true 且 WebRTC 注册成功后可用。
2026-03-23