---
title: "可嵌入式語音小工具"
description: "只需數行程式碼，即可在任何網站加入語音 AI 智能體"
---

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="建立可公開 API 金鑰">
  前往控制台設定中的 **開發人員**，並建立可公開金鑰。可公開金鑰以 `pk_live_` 開頭，可安全地包含於用戶端程式碼中。
</Step>

<Step title="設定允許的網域">
  在相同的開發人員設定中，加入將嵌入小工具的網域。開發時一律允許 `localhost`。支援萬用字元（例如 `*.example.com`）。
</Step>

<Step title="建立網頁小工具">
  前往控制台中的 **網頁小工具** 並建立小工具。選擇要公開的智能體及要使用的可公開金鑰。系統會根據你的可公開金鑰設定自動識別智能體。
</Step>
</Steps>

<Warning>
  可公開金鑰（`pk_live_...`）與你的私密 API 權杖**並不相同**。可公開金鑰專為用戶端使用而設，並限於允許網域上的小工具工作階段。切勿在用戶端程式碼中使用私密 API 權杖。
</Warning>

---

## 快速開始

安裝套件：

```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>

另有三個屬性可自訂工作階段而非外觀——通話開始時，全部都會傳送至工作階段請求：

| 屬性 | 說明 |
|------|-------------|
| `language` | 每個工作階段的語言覆寫設定——可使用 `en`、`es` 或 `fr-FR` 等代碼或地區設定 |
| `voice` | 每個工作階段的語音覆寫設定——可使用 `maria` 等語音名稱 |
| `context` | 傳送至智能體的頁面或網站事實背景資料（伺服器端會截斷至 12,000 個字元） |

完整的屬性表請參閱 [React 元件參考](/yue/widget/react)。

如需完全自訂的介面，請使用 [無介面 Hook](/yue/widget/headless-hook) 管理語音工作階段，同時建立自己的介面。此 Hook 會提供即時音訊音量，方便建立會隨音訊反應的視覺效果。

---

## 整合選項

選擇適合你技術架構的整合方式：

<CardGroup cols={3}>
  <Card title="React 元件" icon="react" href="/yue/widget/react">
    預先建立的 UI 元件，內置通話控制項及狀態顯示。匯入、傳入 props，即可完成。
  </Card>
  <Card title="Headless Hook" icon="code" href="/yue/widget/headless-hook">
    完全掌控 UI。`useThunderPhone` hook 負責管理語音工作階段，而你可自行建立介面。
  </Card>
  <Card title="CDN／Script Tag" icon="globe" href="/yue/widget/cdn-script-tag">
    無需 bundler。透過 script tag 載入小工具，適用於靜態網站、WordPress 及其他非 React 環境。
  </Card>
</CardGroup>

---

## 樣式設定

小工具內置淺色及深色主題，可透過 `theme` prop 控制；重點色則可透過 `primaryColor` prop 控制。如需更深入自訂，你可覆寫 CSS 自訂屬性及類別。詳情請參閱[樣式設定指南](/yue/widget/styling)。

<Note>
  需要協助？請透過 [support@thunderphone.com](mailto:support@thunderphone.com) 聯絡我們
</Note>