把 DeskClerk AI 客服接到 WordPress 网站

1. 这一页适合谁

你用 WordPress 建的网站，想在每个页面右下角放一个 AI 客服气泡。

2. 你能得到什么 / 你得不到什么

你能得到

你 WordPress 网站的每个页面右下角都有一个客服气泡，按你在 DeskClerk 里发布的知识回答。
回答用你给这个站点配的语言；答不上的时候，访客可以走人工。
不用去任何应用市场装东西：就一行 HTML，我们升级产品你也不用跟着动。

你得不到

我们没有一个 WordPress 的插件或应用。我们在任何应用市场都没有上架扩展，也不需要谁来审核。
我们不改你的主题、商品、订单、价格、结账流程。气泡只跟 DeskClerk 通信。
气泡不读你的店铺数据。访客要问订单相关的事，就写一篇讲清楚政策的文章发布上去。
用量按你套餐的月度额度算，不够了随时在工作台加购。

3. 开始之前要准备什么

一个至少发布过一次的 DeskClerk 站点。 气泡是按你发布的知识回答的，所以先发布。
你站点的那段挂件代码。 工作台会给你生成一行 HTML，原样复制就好。
对 WordPress 网站的编辑权限（视平台而定，可能是主题文件、自定义代码、或者脚本管理）。
一分钟的测试时间，保存之后用无痕窗口看一眼。

4. 分步操作

登录 WordPress 后台，进入 外观 → 主题文件编辑器。
在右侧文件列表里打开子主题的 footer.php（改父主题的话，主题一更新这段就被覆盖）。
把第 5 节那段代码粘贴到 </body> 标签前面。
点 更新文件。
用无痕窗口打开网站，看右下角。

如果你的主题没开文件编辑器，也可以用你们自己的代码片段工具，或者子主题的 functions.php，只要最终输出在 </body> 之前就行。

每一步都把点哪里写出来了，因为 WordPress 不同版本、不同套餐的菜单名不一样。如果找不到菜单，可能是你的套餐不含自定义代码——这是建站平台的限制，不是 DeskClerk 的设置。

5. 可复制的完整示例

这就是完整的一段代码，只有一个 <script> 标签，没有别的要加。

<script async src="https://chat.example.com/widget.js" data-aichat-config="eyJzaXRlSWQiOiI3YjBjOWY1ZS0yYThkLTRmMzEtOGU2Yi0xYzJkM2U0ZjVhNmIiLCJwdWJsaWNLZXkiOiIzZDlmOGMyYTFiNGU2ZjcwODE5MmEzYjRjNWQ2ZTdmOCIsImFwaUJhc2VVcmwiOiJodHRwczovL2NoYXQuZXhhbXBsZS5jb20iLCJsb2NhbGUiOiJhdXRvIn0"></script>

data-aichat-config 那串是编码过的站点配置。别手改：直接复制工作台给你生成的那一行，因为里面带着你的站点 ID 和公钥。

要确认它生效了，就打开页面查看源代码，搜 widget.js。标签在、网络请求返回 200，气泡一般一两秒就出来了。

6. 常见问题

报 403 Forbidden / code 40301。 钥匙没带、被停用，或者这把钥匙没有这个接口要的权限。先确认请求头名字就是 X-Integration-Api-Key（或者 Authorization: Bearer <key>）、钥匙状态是 ACTIVE、这把钥匙的站点列表里有这个 Site ID。
报 429 Too Many Requests / code 42901。 请求太快，超过这个站点的频率上限。读响应里的 Retry-After，等够秒数再退避重试，别在循环里死磕。
网页右下角没有出现客服气泡。 在浏览器里查看页面源代码，搜 widget.js：搜不到说明这段代码没进最终页面（缓存插件或主题设置把它丢了）；搜得到就打开浏览器控制台看有没有 Content-Security-Policy 报错，需要把 https://chat.example.com 加进 script-src 和 connect-src。广告拦截插件也会把气泡藏掉，换一个干净浏览器配置再试。
气泡出来了，但回答老是说不知道。 知识是空的、还在处理中，或者知识的语言标签跟访客提问的语言对不上。到工作台「站点 → 知识」里看：总条数要大于 0、待处理条数要是 0、语言标签要和访客提问一致。
建会话报 400，提示 Locale must be enabled for this site's Help Center。 locale 必须填你这个站点已经开启的语言代码（例如 en、zh），不能填 en-US、zh-CN 这种带地区的写法。到站点设置里看一眼语言列表，照那里显示的代码原样传。
会不会拖慢我的网站？ 这段脚本是 async 加载的，不挡页面渲染。就算是 DeskClerk 那台服务器连不上，你的页面也照常打开。
能不能只在部分页面显示？ 可以——把这段代码放到只有那些页面用的模板里，或者用你建站平台的页面判断包起来。WordPress 可以用 is_page() 判断，Shopify 可以用 {% if template contains ... %}。

7. 出问题找谁

产品和配置问题： [email protected]
每次联系都请带上： 你的 Site ID、气泡没出现的页面地址、你粘的那段代码、以及有报错时的浏览器控制台截图。
安全提醒： 别把 API 钥匙明文发给我们。给我们钥匙的前几位（前缀）就够了。