安装与启用

前提

• 网站已安装统计脚本，并能在统计里看到访问。没装的话先完成 网站统计快速接入。
• 你在该项目的角色是所有者或管理员。只有这两个角色能看到「聊天设置」。
• 访问网站用的域名在项目的允许域名里（含子域名）。客服沿用统计的这份列表，见 项目与数据源设置。

接入代码就是统计用的这一段，不需要再加别的脚本：

<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}"></script>

步骤

打开在线客服开关

进入 控制台客服聊天设置外观与品牌，打开「开启在线客服」，点「保存」。页面顶部的状态从「未开启」变成「已开启」。

按需调整外观

在同一页填写品牌名、主色和气泡位置。品牌名留空时使用站点名。各项说明见 外观与文案。

刷新网站页面

打开或刷新你的网站。w.js 发出第一条页面浏览后，服务端在响应里告诉脚本该站点已开启客服，脚本随后从同一目录懒加载 w-chat.js，气泡出现在页面角落。已经打开的页面需要刷新一次。

发一条测试消息

点开气泡发送一条消息。回到 控制台客服客服工作台，在「待接入」里能看到这个会话；如果开启了自动分配且你在线，它会直接进入「我的」。回复一条，确认访客窗口能收到。

独立聊天页与联调测试页

控制台客服聊天设置安装 提供三样东西：

• 接入代码：与统计相同的一段。开启客服后，已安装的页面在下次访问时加载气泡。
• 独立聊天页：地址形如 https://app.tapcub.com/c/SITE_KEY，全屏聊天，不需要在任何网站嵌码，可用于邮件签名、二维码或社交主页。
• 联调测试页：用本站点标识模拟真实访客，依次验证气泡出现、发送、工作台收到、回复。需要先把 localhost 加进允许的域名。

访客在网站气泡里也可以点「在新窗口打开」，把当前会话切到独立聊天页继续。

强制开关：data-chat 属性

默认由控制台开关决定是否加载气泡。在脚本标签上加 data-chat 属性可以覆盖这个判断：

<!-- 不等待服务端标志，直接加载客服脚本 -->
<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-chat="true"></script>

<!-- 这个页面不加载客服 -->
<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-chat="false"></script>

• data-chat="false"：该页面完全不加载 w-chat.js，适合结账页等不想打扰的页面，或临时下线。
• data-chat="true"：不等第一条页面浏览的响应，立即加载客服脚本。脚本仍会读取站点配置，「开启在线客服」关闭时气泡仍然不会出现。

关闭客服

• 全站关闭：在「外观与品牌」关闭「开启在线客服」并保存。气泡对所有页面隐藏，新访客连不上；已有会话和历史记录保留，仍可在工作台查看。
• 单页关闭：在该页脚本标签上加 data-chat="false"。
• 只在手机上隐藏：打开「移动端隐藏气泡」，见 外观与文案。

验证

• 网站页面角落出现气泡；坐席在线时气泡上有绿色在线点。
• 浏览器开发者工具的网络面板里能看到 w-chat.js 加载成功。
• 测试消息出现在工作台，回复能回到访客窗口。

常见失败

现象	处理
没有气泡，也没加载 w-chat.js	确认已保存开关，且页面已刷新；检查脚本标签上是否有 data-chat="false"；确认统计脚本本身在正常上报
加载了 w-chat.js 但没有气泡，或会话窗提示「来源域名不在允许列表」	把当前域名加入允许的域名，见 项目与数据源设置。域名不在列表里时，启动脚本拿不到配置，气泡不会出现
电脑上有气泡，手机上没有	开了「移动端隐藏气泡」。窗口宽度小于 640 像素或移动端浏览器即视为手机
访客发消息后变成留言表单	本月会话额度已用完，见 计费与配额
网站有严格的 CSP	需要放行 w-chat.js 所在域名、客服网关的连接和聊天窗口内嵌页面，见 CSP、拦截与网络限制

更多排查步骤见 客服常见问题。

下一步

调好外观后，到 工作时间与离线 设置工作时间和离线留言，再按 坐席与分配 邀请坐席并配置自动分配。要在代码里控制客服组件，见 客服组件 w-chat.js。

外观与文案

只有所有者或管理员能保存。网站已经装了统计脚本时，保存后刷新页面即可，不必再贴一段代码，接入步骤见 安装与启用。

控制台客服聊天设置外观与品牌

如何配置

项目	所在页	作用
品牌名、副标题、主色、品牌 logo	外观与品牌	气泡和会话窗的名字与颜色。品牌名留空时用站点名。logo 建议正方形，不超过 200 KB
气泡位置	外观与品牌	右下角或左下角
深色模式	外观与品牌	跟随系统、始终浅色或始终深色
移动端隐藏气泡	外观与品牌	窗口宽度小于 640 像素，或移动端浏览器，不显示气泡
欢迎语	问候语与翻译	「欢迎语（有坐席在线时）」和「欢迎语（无坐席在线时）」各一句。工作时间外用离线那一句
气泡打招呼文案	问候语与翻译	访客到达约 4 秒后在气泡上方弹出一次。已经有会话的访客不弹

气泡由同源脚本画出：w.js 确认站点已开启客服后，从同一目录加载 w-chat.js。Free 档在会话窗底部保留可点击的品牌标识；Pro 及以上可以打开「去除底部 Powered by」关掉它。

界面语言不是翻译

「界面语言」只决定按钮和提示是中文还是英文，不改写对话内容。规则见 访客端多语言，消息翻译见 双向翻译。打招呼卡片与主动邀请是两件事，见 主动消息与邀请。