Developer cookbook

嵌入网页小组件

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

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

前提条件#

1. 创建智能体

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

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

   可发布密钥受源站锁定。您必须列出将嵌入小组件的每个主机名。 在本地开发期间，始终允许使用 localhost / 127.0.0.1。

创建可发布密钥#

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"]
  }'

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，并渲染麦克风按钮 以及通话中音频元素。

小组件的 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 筛选，以构建仅限小组件的 控制台。

后续步骤#