嵌入网页小组件

只需添加一个脚本标签，即可将语音智能体嵌入您的营销或支持网站——访客可直接在浏览器中与其对话，无需电话号码。

网页小组件让您的网站访客通过浏览器的麦克风，与 AI 智能体进行点击通话。它是一个独立的 JavaScript / React SDK，拥有自己的 SDK 参考 ——本指南重点介绍网页小组件所需的 ThunderPhone 端配置。

前提条件#

1. 创建智能体

   该智能体的提示词和语音将运行小组件会话。设置 widget_enabled: true（默认值）。

2. 确定路由模式
   • mode="agent" —— 每个密钥对应一个静态智能体。最简单。
   • mode="webhook" —— 您的服务器通过 web.incoming webhook 为每位访客选择智能体。适用于 已登录用户、A/B 测试或按页面路由。
3. 列出允许的域名

   列出将嵌入该小组件的所有主机名。浏览器会在每次会话请求中发送 页面来源，因此该列表可防止他人将您的密钥复制到其他网站后继续使用。这并非 身份验证：浏览器外的脚本可以发送任意 Origin 标头。生产环境不会自动允许 localhost；如需针对生产 API 进行本地测试，请将 localhost 添加到 列表中。

4. 选择浏览器覆盖设置

   确定您的页面可发送哪些会话设置。新密钥默认不接受任何设置；请参阅浏览器覆盖设置。

创建可发布密钥#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

响应中包含一个以 pk_live_... 开头的 key。可发布 密钥按设计即为公开——可安全地包含在您的前端包中。 有关所有字段，请参阅可发布密钥参考。

在您的网站上嵌入小组件#

小组件 SDK 文档涵盖三种集成方式：

三种方式都接受相同的 publishableKey，并渲染麦克风按钮 以及通话中音频元素。

浏览器覆盖设置#

小组件可以从页面发送四项会话级设置：

您的可发布密钥是公开的，因此任何拥有该密钥的人都可以发送这些 设置，包括通过伪造您域名的脚本发送。除非您在密钥上允许，否则每项设置 默认关闭：在控制台中创建或编辑小组件时，在 浏览器覆盖 下勾选相应选项，或者通过 可发布密钥 API 设置 allowed_overrides。仅允许您的页面实际发送的设置。

如果会话请求携带了该密钥不允许的设置，请求将以 400 失败，并指出该设置：

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

此检查适用于两种模式。在 webhook 模式下，允许的设置还会转发到您的 web.incoming webhook（context 会以 website_context 形式到达）。 在此设置推出前创建的密钥允许全部四项设置，因此现有嵌入仍可继续运行； 请关闭您未使用的设置。

小组件的 context 会被截断为 12,000 个字符（约为 3,400 个典型英文文本的 token），并计入提示词大小附加费。 系统会告知智能体将其视为页面内容，而非指令。

小组件模式 webhook#

当 mode="webhook" 时，ThunderPhone 会在每次会话开始时调用您的 webhook_url，并发送 web.incoming 载荷。返回您希望为该访客 运行的智能体配置——其遵循与电话呼叫相同的 响应架构：

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

您可以将自身会话中的上下文（例如浏览的是哪位客户、 他们所在的页面）混入提示词，并可针对不同发布阶段切换智能体。

查看会话#

小组件会话会显示在 GET /v1/calls 中，并带有 direction="widget" ——与电话通话一样，包含相同的转录、录音、评分和 计费。按 direction 筛选，以构建仅限小组件的 控制台。

后续步骤#