在线客服 Onlineservice — ShopXO 商城在线客服插件

把专业在线客服，装进你的 ShopXO 商城。实时会话、表情 / 图片 / 视频 / 文件、商品卡片一键推送、消息撤回、自定义访客备注名——零核心代码改动，一个 zip 导入即用，替代官方 ¥1600 的付费客服应用。

项	说明
适用平台	ShopXO 6.9.2（ThinkPHP 8）
实现语言	PHP 8+ / 原生 JavaScript / MySQL
部署方式	后台「应用管理 → 导入应用」上传 zip
版本	v1.0
核心改动	0 处（纯标准插件体系）

详细展示页：ShopXO 在线客服插件

一、功能特性

1. 实时会话

访客进店自动建档，消息按 ID 游标增量拉取（3 秒短轮询）
未读角标、浏览器标题闪烁、「↓ 有新消息」提示
乐观上屏 + 消息 ID 幂等，轮询与发送回调竞争不重复
架构预留 SSE / Workerman 升级位，前端协议无需改动

2. 表情 / 图片 / 截图粘贴

微信同款表情面板（25px 行内显示）
图片支持上传与截图直接粘贴（Ctrl+V），发送前确认防误触
图片 ≤ 10MB，点击在窗口内浮动看大图

3. 视频 / 文件发送

视频（mp4 / webm / mov / m4v）在会话中直接播放
文件以卡片形式发送，点击即可打开 / 下载
发送前确认弹窗显示预览（图片 / 视频 / 文件卡片）

允许的文件类型（白名单从严控制，其它一律拒绝）：

类别	格式
Office	doc / docx / xls / xlsx / ppt / pptx
WPS	wps / et / dps
其他文档	pdf / txt
视频	mp4 / webm / mov / m4v（直接播放）；avi / mkv / flv / wmv / rmvb / ts / mpeg / mpg / 3gp（按文件下载）
压缩包	zip / rar

大小限制：图片 ≤ 10MB，视频 / 文件 ≤ 20MB
安全策略：上传目录独立、文件类型白名单、伪装可执行文件名（如 x.php.pdf）拦截、原始文件名清洗

4. 商品卡片一键推送

客服按关键词搜索商品，或直接粘贴商品链接 / 输入商品 ID 发送
访客在商品页打开会话时，自动带上当前商品上下文（服务端校验，不信任前端回传）
商品卡展示图片、标题、价格与已选规格

5. 1 分钟消息撤回

发送后 60 秒内可撤回本人消息，服务端二次校验时限与归属
历史记录保留（仅标记状态），双方同步显示「撤回了一条消息」

6. 自定义访客备注名

客服可给访客设置备忘名（如「张三-售后问题」），仅后台可见
三个入口：会话列表铅笔按钮、聊天头部铅笔按钮、访客信息栏铅笔按钮
留空保存恢复默认昵称；支持按昵称或备注名搜索

7. 主题色与头像

后台一键设置主题色（默认 ShopXO 橙 #ff5000），前台悬浮窗即时焕新
访客 / 客服默认头像可自行替换

8. 微信式交互细节

本人气泡微信绿（#95EC69）、URL 自动识别可点
翻查历史记录不会被轮询拽到底部，顶部显示「↓ 有新消息」
访客列表未读角标闪烁（数字 + 99+ 封顶）
PC / 移动端自适应

二、界面外观

访客端（桌面）

悬浮球默认右侧垂直居中，未读红点闪烁，点击展开会话面板
面板：主题色头部（在线状态点）+ 消息区 + 输入栏（表情 / 图片 / 文件图标 + 回车发送）

访客端（手机）

H5 自适应布局，悬浮球与面板自动缩放
截图粘贴、发送文件同样可用

客服工作台（后台）

三栏布局：会话列表（未读角标 + 状态标签）/ 聊天区 / 访客信息栏
聊天区支持商品卡、图片（点击看大图）、视频（内嵌播放）、文件卡、撤回
信息栏展示访客信息（备注名 + 原始昵称 + 来源 + 状态 + 来源页）与当前咨询商品
打开「等待接入」的会话即自动接入并开始接待

三、系统架构

访客浏览器 ──┐
             ├─► Hook（ViewFetchEnd 注入悬浮窗）
后台工作台 ──┘        │
                      ▼
            Api / Admin 控制器（参数校验与调度）
                      │
                      ▼
            OnlineService 业务层（会话 / 消息 / 话术 / 状态）
                      │
                      ▼
            MySQL（4 张独立表）

访客端悬浮窗：widget.js 原生 JS 实现，3 秒短轮询按消息 ID 游标增量拉取
Hook 注入：ViewFetchEnd 钩子把悬浮窗 HTML / 配置注入每个页面输出，无需改模板
控制器分层：访客端 Api 与后台 Index 控制器只做参数校验，业务全部下沉 Service
数据层：会话、消息、话术、客服状态 4 张表，游标索引支撑高效分页

四、技术栈

层	技术
服务端语言	PHP 8+（PSR-4 自动加载）
框架	ThinkPHP 8（ShopXO 6.9.2 同款）
前端	原生 JavaScript（零框架零构建，ES5 兼容）
数据库	MySQL / InnoDB
插件体系	ShopXO 标准插件：config.json / Hook / install.sql
实时方案	3 秒短轮询 + 游标增量（可升级 SSE / Workerman）
上传	Fetch + FormData，90 秒超时保护
消息协议	JSON：text / image / video / file / goods / context / recalled
主题	CSS 变量，后台改色前台即时生效
游客识别	localStorage 临时标识，刷新不丢会话

五、部署（三步）

导入插件包：后台「应用管理 → 导入应用」上传 onlineservice.zip，系统自动建表（老版本自动补充新增字段，数据不丢）
设置与清缓存：「在线客服 → 设置」配置主题色等选项 → 保存 → 清除 ShopXO 后台缓存
开始接待：前台每个页面右侧出现客服悬浮球；后台「客服工作台」实时收到访客消息

注意事项：

不修改 ShopXO 任何核心文件，官方升级后插件照常工作；卸载时数据表一并清理
上传目录独立于插件静态目录，覆盖升级不丢文件
发送文件需确保服务器 upload_max_filesize 与 post_max_size ≥ 20MB
手动复制目录部署时，插件首次被访问会自动补齐数据表与字段

六、FAQ

Q：和官方付费客服应用相比，有什么区别？ 功能覆盖商城客服核心场景，且源码完全自主可控，可继续二次开发；官方应用 ¥1600 元比较贵，本插件一次部署、永久使用，无授权费。

Q：支持多个客服同时接待吗？ 当前版本为「全员可见 + 手动接入」模式：所有后台用户都能看到会话列表，点击「等待接入」的会话即开始接待，系统自动记录接待人。数据库已预留 service_id 与客服状态表，多客服自动分配（按在线状态 / 负载）已做好数据准备，可按需升级。

Q：消息是实时的吗？ 采用 3 秒短轮询 + 消息 ID 游标增量拉取，实测延迟 1～3 秒；同时具备未读角标、浏览器标题闪烁、新消息提示。若未来需要更低延迟，架构上已预留 SSE / Workerman 升级位。

Q：游客没有登录也能收到回复吗？ 可以。游客通过 localStorage 生成临时标识关联会话，刷新、返回页面不丢失；登录用户自动关联商城账号。

Q：可以发送哪些文件？大了会怎样？ 仅支持 Office（doc/docx/xls/xlsx/ppt/pptx）、WPS（wps/et/dps）、PDF、TXT、视频与 ZIP/RAR，单个 ≤ 20MB；超出限制或类型不符会明确提示，不会发出。

七、路线图（规划中）

多客服自动分配（按在线状态 / 负载，数据层已就绪）
常用话术快捷发送（数据表已就绪）
SSE / Workerman 长连接升级（更低延迟）
客服工作量统计与会话评价

基于 ShopXO 6.9.2 · ThinkPHP 8 · PHP 8+ / MySQL 构建 · 版本 v1.0 · 自研插件，替代官方付费应用

ShopXO 在线客服插件

📖 详情说明