可嵌入式语音组件

只需几行代码，即可将语音智能体添加到任何网站

ThunderPhone 可嵌入式语音小组件让您的网站访客能够直接通过浏览器与 AI 智能体交谈。无需拨打电话——用户只需点击按钮，即可开始由 ThunderPhone 提供支持的实时语音对话。

该小组件以玻璃拟态栏的形式呈现，可适配浅色和深色主题，并支持自定义强调色和位置。它以 @thunderphone/widget npm 包的形式分发，也可通过 CDN 用于非打包工具环境。

前提条件#

在嵌入小组件之前，请在 ThunderPhone 控制台中完成以下三个步骤：

1. 创建网页小组件

   在控制台中前往 网页小组件 并创建一个小组件。选择您要公开的智能体。每个小组件都有自己的可发布密钥（pk_live_...），可安全地包含在客户端代码中；系统会根据该密钥解析智能体。

2. 配置允许的域名

   在同一小组件中，添加其将被嵌入的网站域名。支持通配符（例如 *.example.com）。当他人将您的密钥复制到其他网站时，该列表会阻止小组件运行；这不是身份验证，因为浏览器外的脚本可以发送任意 Origin 标头。生产环境不会自动允许 localhost：请将其添加到列表中，以便针对生产 API 进行本地测试。

3. 选择浏览器覆盖设置

   如果您的页面设置了 language、voice 或 context，请在 浏览器覆盖设置 下分别启用它们。新建小组件默认均不允许，携带已关闭设置的会话请求会以 400 override_not_allowed 失败。请参阅浏览器覆盖设置。

快速开始#

安装该软件包：

npm install @thunderphone/widget

将小组件添加到您的应用中：

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}

就是这样。您的用户将看到一个玻璃拟态通话栏，只需点击一下即可连接到您的 AI 智能体。

自定义#

该小组件提供四个外观属性：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>

另外三个属性用于自定义会话而非外观——通话开始时，它们都会转发到会话请求中。仅当组件的可发布密钥在 浏览器覆盖设置 中允许使用时，这些属性才会生效；否则，会话请求将因 400 override_not_allowed 而失败：

有关完整的属性表，请参阅 React 组件参考。

如需完全自定义的 UI，请使用 无头 Hook 管理语音会话，同时构建您自己的界面。该 Hook 提供实时音频电平，可用于构建音频响应式可视化效果。

每次组件对话都算作一次通话。它会计入您组织的并发通话上限（默认同时进行 20 通通话，与电话及其他通话共享）以及组件 25 个活跃会话的上限（如果您的并发通话上限更高，则采用该上限）。达到任一上限后，必须等待一通通话结束才能开始新的对话。

集成选项#

选择适合您技术栈的集成方式：

样式#

该小组件内置浅色和深色主题，由 theme prop 控制；强调色由 primaryColor prop 控制。如需更深入的自定义，您可以覆盖 CSS 自定义属性和类。详情请参阅样式指南。