网页挂件

代码中的 window.SingChat 等是挂件与 API 的技术名称，请原样保留。

网站聊天窗口就是一个脚本 widget.js，由 askais.com 提供。它会在你的页面上加一个聊天按钮，并在 Shadow DOM 里绘制聊天窗口，所以你网站的样式和聊天窗口的样式互不影响。

加到你的网站

把这段代码贴到每个需要显示聊天的页面的 </body> 之前。App ID 在设置 → 收件箱与聊天框外观里。

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

在你自己的网站上，data-base-url 是必填的：没有它，聊天窗口会到你的域名上找它的服务器，而不是到 askais.com。

⚠️ 从 askais.com 加载 widget.js

不要下载 widget.js，也不要把它打包进你自己的代码。从 askais.com 加载，它始终运行当前版本；复制下来的副本会停在当时的版本，之后的每一个修复和新功能都用不到。

脚本属性

所有设置都通过 script 标签上的 data- 属性完成：

• data-app-id — 必填。你的收件箱的 App ID。
• data-base-url — 在你的网站上必填。固定为 https://askais.com。
• data-locale — 可选。强制指定聊天窗口的语言，例如 ja 或 zh-Hant。不填时，聊天窗口会跟随访客设备的语言，其次是你页面的 lang。
• data-external-id — 已登录用户在你系统里的 ID。
• data-email — 用户的邮箱，会显示给你的团队。
• data-name — 用户的名字，会显示给你的团队。
• data-avatar-url — 用户头像的链接。
• data-hmac — 身份签名，见下文。
• data-attrs — 以 JSON 表示的额外信息，例如 {"plan":"Pro"}，会显示在访客资料里给你的团队看。无效的 JSON 会被忽略。

data-embed、data-platform、data-app-version 和 data-device-model 由 App 内聊天页面设置。 参见「App 内聊天（WebView）」。

已登录访客

对于已登录的用户，把他们的资料加到 script 标签上。你的团队能看到在和谁对话，对话也会跟着用户到其他设备上：

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

没有 data-external-id 时，聊天窗口会给每个浏览器分配一个自己的匿名 ID，保存在浏览器的本地存储里，所以在这个浏览器里刷新页面后，聊天记录仍然保留。如果收件箱设置了 Pre-chat 表单，匿名访客要先填写表单才能开始聊天。

身份验证（HMAC）

• hmac 是以收件箱密钥为 key、对 externalId 计算出的 HMAC-SHA256，用小写十六进制表示。
• 在你的服务器上计算。密钥绝不能放进网页或 App。
• 密钥在创建收件箱时显示一次，在设置 → 收件箱与聊天框外观里轮换时会再显示一次。轮换后，所有旧签名都会失效。
• data-external-id 一定要和 data-hmac 一起发送。签名是对照 external ID 检查的，所以只对邮箱签名会被拒绝。
• 签名错误时，聊天窗口无法连接。没有 data-hmac 时，资料会按页面给出的内容直接采用，所以任何能修改页面的人都可以冒充别人。

Node.js 示例：

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

用 JavaScript 启动聊天窗口

如果要自己启动聊天窗口，例如等页面确认用户是谁之后再启动，就在加载脚本时不带 data-app-id，并在脚本加载完成后调用 window.SingChat.start()：

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() 是脚本提供的唯一方法。没有用来打开、关闭或监听聊天窗口的方法；访客通过聊天按钮打开它。

外观与行为

• 设置 → 收件箱与聊天框外观，再展开某个收件箱：主色和文字颜色、位置（右下或左下）、气泡大小、浅色或深色背景、窗口标题和副标题，并有实时预览。
• Pre-chat 表单（同一处）：在开始聊天前，请匿名访客填写邮箱、姓名、电话或公司。
• 允许的域名（同一处）：可以加载这个收件箱聊天窗口的网站。列表为空时允许任何网站。
• 品牌署名（同一处）：聊天窗口底部的「Powered by」字样。能否隐藏它，或在那里显示你自己的名称，取决于你的方案。
• AI 欢迎语在 AI 助手里设置，可点击的 FAQ 气泡在设置 → 常见问题里设置，文章在帮助中心里设置。

安全

• App ID 是公开的，放在 HTML 里是安全的。
• 收件箱密钥只能放在你的服务器上。
• 只要页面知道用户是谁，就使用身份验证（HMAC）。
• 在「允许的域名」里只填你自己的域名，这样聊天窗口就无法在其他网站上加载。