Skip to main content
网页小组件通过浏览器的麦克风，让您的网站访客能够与智能体进行点击通话对话。它是一个独立的 JavaScript / React SDK，并拥有自己的 SDK 参考——本指南重点介绍小组件所需的 ThunderPhone 端设置。
您无需使用 cURL 即可完成所有操作：网页小组件控制台页面 （/dashboard/web-widgets）可创建小组件、设置其模式和智能体、管理允许的域名，并向您提供嵌入代码片段。

​
前提条件

1

创建智能体

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

确定路由模式

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

列出允许的域名

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

​
创建可发布密钥

响应中包含一个以 pk_live_... 开头的 key。可发布密钥在设计上是公开的——可安全地包含在您的前端构建包中。 有关所有字段，请参阅可发布密钥参考。
allowed_domains 必须至少包含一个条目。*.example.com 匹配子域名（例如 api.example.com），但不匹配裸域名。 将拒绝 * 或 *.* 等裸通配符。

​
在您的网站中嵌入小组件

小组件 SDK 文档涵盖了三种集成选项：

React 组件

<ThunderPhoneWidget publishableKey="pk_live_..." />。

无头 Hook

用于自定义 UI 的 useThunderPhone()。

CDN 脚本标签

用于非构建工具网站的 ThunderPhone.mount({...})。
三种方式均接受相同的 publishableKey，并渲染麦克风按钮和通话中的音频元素。 小组件的 context 会被截断至 12,000 个字符（约为 3,400 个典型英文文本 token），并计入提示词大小附加费。

​
小组件模式 webhook

当 mode="webhook" 时，ThunderPhone 会在每次会话开始时使用 web.incoming 负载调用您的 webhook_url。返回您希望为该访客运行的智能体配置——其遵循与电话呼叫相同的响应架构：
您可以将自身会话中的上下文（正在浏览的客户、他们所在的页面）混入提示词，并在每次发布中切换智能体。

​
查看会话

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

​
后续步骤

小组件 SDK 参考

React / hook / CDN 集成详情。

动态的每通通话配置

端到端实现 mode="webhook" 流程。

可发布密钥参考

密钥资源上的所有字段。

麦克风会话 API

跳过小组件；直接驱动 LiveKit 以构建自定义 UI。