---
title: "可嵌入式语音组件"
description: "只需几行代码，即可将语音智能体添加到任何网站"
---

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

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

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## 前提条件

在嵌入小组件之前，请在 [ThunderPhone 控制台](https://app.thunderphone.com)中完成以下三个步骤：

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

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

<Step title="选择浏览器覆盖设置">
  如果您的页面设置了 `language`、`voice` 或 `context`，请在 **浏览器覆盖设置** 下分别启用它们。新建小组件默认均不允许，携带已关闭设置的会话请求会以 `400 override_not_allowed` 失败。请参阅[浏览器覆盖设置](/zh/guides/embed-web-widget)。
</Step>
</Steps>

<Warning>
  可发布密钥（`pk_live_...`）与您的私密 API 令牌**不同**。可发布密钥专为客户端使用而设计，并且其作用域限定为允许域名上的小组件会话。切勿在客户端代码中使用您的私密 API 令牌。
</Warning>

<Note>
  小组件会话默认在 30 分钟后结束；如果智能体自身的最大通话时长更短，则会更早结束。可在[可发布密钥](/api-reference/publishable-keys)上通过 `max_call_duration_seconds` 为每个密钥更改限制（最长 6 小时），或将其设为 `null` 以使用智能体自身的限制。
</Note>

---

## 快速开始

安装该软件包：

```bash
npm install @thunderphone/widget
```

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

```tsx
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 智能体。

---

## 自定义

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

| 属性 | 默认值 | 说明 |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` 表示白色玻璃效果，`'dark'` 表示深色玻璃效果 |
| `primaryColor` | `'#000000'`（浅色）/ `'#ffffff'`（深色） | 开始按钮、波形和连接指示器的强调色 |
| `title` | `'Voice assistant'` | 小组件中显示的文本 |
| `position` | `'bottom-right'` | 视口角落：`'bottom-right'`、`'bottom-left'`、`'top-right'`、`'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

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

| 属性 | 说明 |
|------|-------------|
| `language` | 按会话覆盖语言设置——可使用代码或区域设置，例如 `en`、`es` 或 `fr-FR` |
| `voice` | 按会话覆盖语音设置——可使用语音名称，例如 `maria` |
| `context` | 传递给智能体的事实性页面或网站上下文（服务端会截断至 12,000 个字符） |

有关完整的属性表，请参阅 [React 组件参考](/zh/widget/react)。

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

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

---

## 集成选项

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

<CardGroup cols={3}>
  <Card title="React 组件" icon="react" href="/zh/widget/react">
    预构建的 UI 组件，内置通话控制和状态显示。导入、传入 props，即可完成。
  </Card>
  <Card title="无头 Hook" icon="code" href="/zh/widget/headless-hook">
    完全掌控 UI。`useThunderPhone` Hook 管理语音会话，您可以构建自己的界面。
  </Card>
  <Card title="CDN / Script 标签" icon="globe" href="/zh/widget/cdn-script-tag">
    无需打包工具。通过 script 标签为静态网站、WordPress 和其他非 React 环境加载小组件。
  </Card>
</CardGroup>

---

## 样式

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

<Note>
  需要帮助？请通过 [support@thunderphone.com](mailto:support@thunderphone.com) 联系我们
</Note>