快速开始

im.io 是一款嵌入式多语言在线客服系统。只需在网站页面引入 widget.js 并设置 window.CHAT_WIDGET_CONFIG 配置，即可拥有实时聊天能力。

<!-- 第 1 步：设置站点配置（必须在引入 SDK 之前） -->
<script>
  window.CHAT_WIDGET_CONFIG = {
    siteId: 'your-site-id',       // 站点 ID（管理后台创建站点后获取）
    autoOpen: false,                  // 是否自动打开聊天窗口
    position: 'right',                // 悬浮按钮位置 left | right
    themeColor: '#6366f1',             // 主题色（可选，默认 #667eea）
    openTrigger: '.btn-chat',         // CSS 选择器触发打开（可选）
    defaultLang: 'zh-CN',             // 默认语言（可选）
  };
</script>

<!-- 第 2 步：引入 SDK（自动读取上方配置并初始化） -->
<script src="/widget/widget.js"></script>

<!-- 第 3 步：在按钮上添加触发标签（可选） -->
<button data-chat-open="立即购买">立即购买</button>

环境要求

安装部署

# 1. 克隆项目
git clone <repo-url> im.io
cd im.io

# 2. 安装 PHP 依赖
composer install

# 3. 导入数据库（按顺序执行）
mysql -uroot -p im.io < sql/01_init.sql
mysql -uroot -p im.io < sql/11_site_translate_enabled.sql
mysql -uroot -p im.io < sql/12_trigger_reply.sql

# 4. 配置 .env（数据库、Redis、翻译 API）
cp .env.example .env
# 编辑 .env 设置 DB_*, REDIS_*, BAIDU_TRANSLATE_*

# 5. 启动服务
php start.php start          # HTTP 服务
php start.php start gateway  # WebSocket 服务（新终端）

嵌入 Widget

Widget 是零依赖的原生 JS 组件。通过 window.CHAT_WIDGET_CONFIG 配置后，SDK 自动初始化：

<!-- 最简配置：只需 siteId -->
<script>
  window.CHAT_WIDGET_CONFIG = { siteId: 'your-site-id' };
</script>
<script src="https://your-domain.com/widget/widget.js"></script>

SDK 在 DOMContentLoaded 时自动读取 window.CHAT_WIDGET_CONFIG 并创建聊天组件，悬浮按钮和聊天窗口自动渲染，无需额外 HTML。

配置参数

在 window.CHAT_WIDGET_CONFIG 中可设置以下字段：

Widget API

SDK 初始化后自动注册 window.CHAT_WIDGET 全局对象，可在任何地方调用：

// 普通打开
window.CHAT_WIDGET.open();

// 带触发标签打开（触发自动回复 + 通知客服意图）
window.CHAT_WIDGET.open('立即购买');

// 关闭
window.CHAT_WIDGET.close();

触发标签功能

触发标签让访客的进入意图一目了然。访客通过特定按钮（如「立即购买」「在线咨询」）打开聊天时，系统自动：

• 向客服发送系统消息：🔔 访客通过「立即购买」按钮进入咨询
• 根据管理后台配置的触发回复，自动向访客发送预设内容（文字+链接）
• 客服在会话列表立即看到未读提示和访客意图摘要

使用方式

<!-- 方式 1：data-chat-open 属性（推荐） -->
<button data-chat-open="立即购买">立即购买</button>
<button data-chat-open="在线咨询">在线客服</button>

<!-- 方式 2：无值，取元素文本作为标签 -->
<button data-chat-open>联系客服</button>

<!-- 方式 3：JS 编程调用 -->
<button onclick="window.CHAT_WIDGET.open('立即购买')">购买</button>

多语言翻译

im.io 支持访客与客服跨语言沟通时自动翻译，基于百度翻译 API。

三层翻译控制

登录管理

访问 /admin/auth/login.html 进入管理后台登录页。

• 超级管理员（role=1）：可管理所有站点、客服、配置
• 普通客服（role=2）：只能查看分配给自己的会话和工作台

站点配置

在「站点设置」页面可配置：

• 基本信息：站点名称、域名、状态
• 外观设置：主题色、位置、按钮样式
• 语言设置：默认语言、支持语言列表
• 文案设置：欢迎语（多语言）、快捷问题
• 翻译设置：翻译开关、翻译服务状态
• 邀请对话：邀请弹窗、延迟时间、重复间隔
• 触发标签：触发标签自动回复管理

客服管理

在「客服与绑定」页面管理客服账号：

• 新增/编辑/删除客服（用户名、昵称、密码、角色）
• 客服与站点绑定（一个客服可绑定多个站点）
• 客服状态管理：在线(1) / 离线(0) / 忙碌(2)
• 客服离线时自动将其名下会话重分配给其他在线客服

触发回复管理

在「站点设置 → 触发标签自动回复」区块管理触发标签与回复内容：

• 点击「+ 添加触发标签」新建触发回复
• 填写触发标签名（如「立即购买」）
• 填写中文回复内容（支持 URL，自动转为可点击链接）
• 可选填写英文回复（点击 EN 按钮展开）
• 点击「保存」生效

快捷话术

在客服工作台「⚡ 快捷话术」面板中，可预设常用回复话术（支持多语言），客服一键发送，提升响应效率。

访客端 API

管理端 API

常见问题

Q: Widget 不显示？

检查：1) CHAT_WIDGET_CONFIG.siteId 是否正确；2) 站点是否已启用；3) 浏览器控制台是否有报错；4) widget.js 路径是否正确；5) 配置必须在 SDK 引入之前设置。

Q: 消息收不到？

检查：1) GatewayWorker 服务是否启动；2) WebSocket 连接是否成功（检查 ws:// 地址）；3) 站点是否绑定了在线客服。

Q: 翻译不工作？

检查：1) .env 中 BAIDU_TRANSLATE_APPID 和 BAIDU_TRANSLATE_SECRET 是否配置；2) 站点翻译开关是否开启；3) 访客语言是否为中文（中文不翻译）。

Q: 客服刷新页面后会话丢失？

系统已内置 3 秒延迟检查机制：客服刷新页面时旧连接断开，3 秒内重连则不触发离线逻辑，会话保持不变。

Q: 客服结束会话后访客怎么办？

会话状态变为 waiting，admin_id 清空，访客回到等待接入池。历史消息完整保留，访客可继续发消息，系统自动分配新客服。

更新日志