开发者文档

把 Live Chat 接入你的网站和管理后台

聊天窗口只需一行 script 标签。另外还有给你自己按钮用的 JavaScript API、从管理后台直接进入的单点登录，以及能让 AI 助手帮你对接的 MCP 服务器。

添加聊天窗口

在每个要显示聊天的页面，把这段标签粘贴到 </body> 前面。工作区 ID 在“设置 › 常规”，也可以在“设置 › 聊天窗口”直接复制整段标签。

这个 script 很轻，访客打开聊天之前不会再加载任何东西。纯 HTML、WordPress、Shopify、Next.js 或单页应用都能用。

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..." async></script>

请在“设置 › 聊天窗口 › 允许使用聊天窗口的网站”添加每个网站的地址，其他网站无法启动聊天窗口。

聊天窗口选项

在 script 标签上设置以下属性。

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..."
        data-color="#0f766e"
        data-lang="ja"
        async></script>

属性	说明
`data-workspace`	必填。你的工作区 ID（ws_...）。
`data-color`	按钮和标题栏的颜色，用十六进制色值表示，例如 #0f766e。默认 #4f46e5。
`data-lang`	聊天窗口的语言：en、ja、ko、zh-TW、zh-CN、th 或 vi。默认跟随访客的浏览器语言。
`data-launcher="none"`	不显示圆形聊天按钮，由页面上你自己的按钮打开聊天（见 JavaScript API）。
`nonce`	在设置了严格 Content-Security-Policy 的页面上，聊天窗口会把 script 标签的 nonce 加到它添加的样式和 script 上。

JavaScript API

script 加载后，页面可以用 window.HibiraLiveChat 打开或关闭聊天。如果你的代码可能比聊天窗口更早运行，请监听 hibira-livechat:ready 事件。

<button type="button" id="talk-to-sales">Talk to sales</button>

<script src="https://chat.hibira.io/w/v1.js"
        data-workspace="ws_..." data-launcher="none" async></script>
<script>
  document.getElementById("talk-to-sales").addEventListener("click", function () {
    if (window.HibiraLiveChat) window.HibiraLiveChat.open({ topic: "sales" });
  });
  window.addEventListener("hibira-livechat:ready", function () {
    // The widget is loaded: HibiraLiveChat.open() and .close() work now.
  });
</script>

调用或事件	说明
`HibiraLiveChat.open()`	打开聊天面板。
`HibiraLiveChat.open({ topic: "sales" })`	打开聊天，并把新对话标记为销售咨询，团队在收件箱里也会看到这个标记。
`HibiraLiveChat.close()`	关闭聊天面板。
`hibira-livechat:ready`	聊天窗口加载完成时在 window 上触发的事件。
`hibira_chat_open, hibira_chat_start, hibira_chat_message, hibira_chat_rating`	在“设置 › 聊天窗口”开启分析后，会发送到你网站上已有 gtag 或 Tag Manager 的 Google Analytics 事件。不会发送任何个人信息。

Content-Security-Policy

如果你的网站设置了严格的 Content-Security-Policy，请允许下列主机，并在 script 标签上加上页面的 nonce。聊天窗口会把这个 nonce 带到它添加的所有内容上。

challenges.cloudflare.com 用于新访客第一条消息的防垃圾检查。

script-src  'nonce-R4nd0m' https://chat.hibira.io https://challenges.cloudflare.com;
style-src   'nonce-R4nd0m';
connect-src https://chat.hibira.io wss://*.hibira.io;
img-src     https://chat.hibira.io data:;
frame-src   https://challenges.cloudflare.com;

<script src="https://chat.hibira.io/w/v1.js" nonce="R4nd0m"
        data-workspace="ws_..." async></script>

客服单点登录（JWT） Starter 及以上

员工无需另一套密码，就能从你自己的管理后台直接进入 Live Chat 收件箱。你的服务器为已登录的员工签发一个短时效令牌，再把他们跳转到 Live Chat。

在“团队 › 单点登录”开启单点登录并复制密钥。
密钥只保存在服务器上，例如放在环境变量 HIBIRA_LIVECHAT_SSO_SECRET。绝对不要放进浏览器端代码。
在管理后台加一个链接，指向你自己的路由：确认用户是员工、签发下面的令牌，再跳转到 /sso/jwt。
首次登录的人，只要还有空余席位就会自动添加为客服。每次登录时，角色都会按令牌内容更新。

import crypto from "node:crypto";

const b64 = (v) => Buffer.from(JSON.stringify(v)).toString("base64url");

// Build a new URL on every click, behind your admin panel's own login.
export function liveChatSsoUrl(user) {
  const now = Math.floor(Date.now() / 1000);
  const head = b64({ alg: "HS256", typ: "JWT" });
  const body = b64({
    iss: "ws_...",                 // your Workspace ID
    sub: String(user.id),          // the user's ID in your system
    email: user.email,
    name: user.name,
    role: user.isAdmin ? "admin" : "agent",
    jti: crypto.randomUUID(),      // single use
    iat: now,
    exp: now + 120,                // 5 minutes at most
  });
  const sig = crypto
    .createHmac("sha256", process.env.HIBIRA_LIVECHAT_SSO_SECRET)
    .update(head + "." + body)
    .digest("base64url");
  return "https://chat.hibira.io/sso/jwt?" + new URLSearchParams({
    jwt: head + "." + body + "." + sig,
    return_to: "/inbox",
  });
}

Claim	含义
`iss`	必填。你的工作区 ID。
`sub`	必填。用户在你系统中的 ID（最多 200 个字符）。即使邮箱变了，也会对应到同一位客服。
`email`	必填。用户的邮箱。
`name`	选填。访客和同事看到的名字。
`role`	选填。agent（默认）或 admin。
`jti`	必填。这个令牌的唯一 ID（最多 128 个字符），每个令牌只能用一次。
`iat`	选填。签发时间（Unix 秒）。
`exp`	必填。过期时间（Unix 秒），最多为现在起 5 分钟。

用 HS256 签名，把令牌以 ?jwt= 发送到 /sso/jwt。加上 return_to（例如 /inbox）可以指定登录后的页面。
允许最多 30 秒的时钟误差。
更换密钥后，旧密钥还能用 24 小时，部署新密钥时不会中断。
确认能正常登录后，开启“只允许单点登录”：客服只能从你的管理后台登录，所有者仍可用邮箱登录。

Node.js、Laravel、PHP、Python、Django、Rails、Go、Java 和 .NET 的现成代码，可以通过下面的 MCP 服务器获取。

AI 助手（MCP）

通过 Live Chat 的 MCP 服务器，Claude、Cursor、VS Code 等 AI 助手可以在你自己的代码里接好单点登录。AI 助手会在浏览器里用你的 Live Chat 账号登录，只有工作区所有者和管理员可以批准。

SSO 密钥永远不会经过 MCP。AI 助手会读取配置、按你的技术栈写出代码，并在不让任何人登录的情况下检查它签发的令牌。

# Claude Code
claude mcp add --transport http hibira-live-chat https://chat.hibira.io/mcp

# Any client with remote MCP servers (Cursor, VS Code, ...)
{ "mcpServers": { "hibira-live-chat": { "url": "https://chat.hibira.io/mcp" } } }

工具	说明
`get_sso_setup`	单点登录是否开启、工作区 ID、登录地址、令牌的 claim 与限制，以及空余席位。
`get_sso_snippet`	按你的技术栈生成签发令牌并跳转员工的服务端代码，已填好你的工作区 ID。
`check_sso_token`	用和正式登录完全相同的方式检查令牌，列出所有问题，且不会用掉这个令牌。
`list_agents`	工作区的客服、角色、添加方式和最后在线时间。
`set_sso_only`	开启或关闭“只允许单点登录”，仅限所有者。

适用于 Claude Code、Cursor、Codex 和 Gemini CLI 的 Hibira 插件已内置这个服务器。要一次断开所有 AI 应用，请到“团队 › 单点登录 › 断开 AI 应用”。

REST API 与 Webhook 即将推出

Team 及以上方案即将提供对话、消息和评分的 REST API，以及新对话、新消息和新评分的 Webhook。上线后会在本页说明。

在此之前，你可以从收件箱把对话导出为 CSV 或 JSON，或在“设置 › 数据与隐私”导出整个工作区。

给 AI 工具

供 AI 助手和问答引擎读取的 Live Chat 纯文本摘要：/llms.txt 是精简版，/llms-full.txt 收录本文档和每个功能页的完整内容。

curl https://chat.hibira.io/llms.txt
curl https://chat.hibira.io/llms-full.txt

抢先加入候补

留下邮箱，轮到你时我们会第一时间发出邀请。

加入候补名单