智能客服系统多端接入实战

做独立开发这几年，我接过不少客服系统的私活。客户最常提的需求就是：一套客服后台，要同时服务 Web、小程序、App、H5 四个入口。听起来简单，真做起来坑不少。这篇文章把我的实战方案整理出来，重点讲多端接入的架构设计和代码落地。

为什么多端接入是个真问题

很多团队一开始只做 Web 客服，后来业务扩张，小程序要接、App 要接、H5 活动页也要接。如果每个端单独写一套逻辑，会面临三个问题：

• 会话状态不同步：用户在 App 发了一半消息，切到小程序看不到历史。
• 消息通道重复造轮子：WebSocket、轮询、SSE 各写一遍，维护成本爆炸。
• 客服端要对接 N 套协议：客服坐席面对不同来源的用户，体验割裂。

核心思路是：把「接入层」和「业务层」彻底解耦。所有端只负责采集用户输入、渲染消息，统一走一个网关协议。

整体架构设计

我的方案分三层：

1. 接入层：各端 SDK，负责协议适配、心跳、重连。
2. 网关层：统一 WebSocket 网关，做鉴权、路由、消息广播。
3. 业务层：会话管理、机器人问答、人工坐席分配。

关键点是：接入层只认一种消息格式，不管来自哪个端，进网关后都是统一结构。

{
  "msgId": "uuid",
  "sessionId": "sess_xxx",
  "from": "user",
  "channel": "miniprogram",
  "type": "text",
  "content": "你好",
  "ts": 1700000000000
}

channel 字段标记来源端，业务层按需处理，但消息体本身完全一致。

各端接入的差异点

Web 端

最省事，直接用原生 WebSocket。注意要做断线重连和心跳，浏览器切后台会挂连接。

const ws = new WebSocket('wss://api.example.com/chat');
let timer = null;
function connect() {
  ws.onopen = () => {
    timer = setInterval(() => ws.send(JSON.stringify({ type: 'ping' })), 30000);
  };
  ws.onclose = () => {
    clearInterval(timer);
    setTimeout(connect, 2000);
  };
}
connect();

小程序端

微信小程序的 wx.connectSocket 有连接数限制，页面隐藏时要主动断开，避免占用。另外小程序不支持自定义 header 传 token，得放在 URL query 或首帧消息里。

const socket = wx.connectSocket({
  url: `wss://api.example.com/chat?token=${token}&channel=miniprogram`
});
socket.onMessage((res) => {
  const msg = JSON.parse(res.data);
  renderMessage(msg);
});

App 端

App 要考虑前后台切换。iOS 后台会冻结连接，建议切后台时降级为长轮询，回前台再恢复 WebSocket。Android 相对宽松，但也要处理厂商杀进程。

H5 端

H5 场景最杂，可能嵌在公众号、浏览器、App WebView 里。建议做能力探测：支持 WebSocket 就用，不支持则降级 SSE 或轮询。

function createChannel() {
  if ('WebSocket' in window) return new WsChannel();
  if ('EventSource' in window) return new SseChannel();
  return new PollChannel();
}

统一身份与会话同步

多端最大的价值是会话跨端同步。我的做法是：用户登录后拿到全局 userId，会话以 userId 为维度存储，而不是以连接为维度。

• 用户在 App 发的消息，写入 session:{userId}。
• 切到小程序后，拉取历史消息，续接同一会话。
• 客服坐席看到的也是同一个会话，不会出现「两个用户」。

存储层用 Redis 存活跃会话，MySQL 存归档消息，冷热分离。

踩过的坑

• 消息乱序：多端并发发消息时，靠时间戳排序不可靠，必须用服务端生成的递增 seq。
• 重复消息：断线重连后要带 lastSeq 拉增量，服务端做幂等去重。
• 小程序码登录：H5 里扫码登录 App，token 传递要走一次性票据，别直接放 URL。

多端接入的本质不是「多写几套代码」，而是「把差异收敛到接入层，业务层只处理一种消息」。

小结

智能客服系统的多端接入，核心就三件事：统一消息协议、统一身份会话、各端做能力降级。把这三点做好，Web、小程序、App、H5 的接入成本会大幅下降。后续我会再写一篇讲机器人问答和人工坐席分配的实现，感兴趣可以关注。