---
title: "可嵌入式語音小工具"
description: "只需幾行程式碼，即可將語音人工智慧智慧體加入任何網站"
---

ThunderPhone 可嵌入式語音小工具可讓你的網站訪客直接從瀏覽器與 AI 智慧體交談。不需要撥打電話——使用者只要點擊按鈕，即可開始由 ThunderPhone 驅動的即時語音對話。

此小工具會呈現為可適應淺色與深色主題的玻璃擬態橫條，並支援自訂強調色與位置。它以 `@thunderphone/widget` npm 套件形式發布，也可透過 CDN 用於未使用打包工具的環境。

<Frame>
  <img src="/images/widget-showcase.png" alt="淺色與深色主題中的 ThunderPhone 小工具，搭配各種強調色" />
</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-Hant/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 智慧體。

---

## 自訂

此小工具提供四個外觀 prop：

| Prop | 預設值 | 說明 |
|------|---------|-------------|
| `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>

另外三個 prop 用於自訂工作階段，而非外觀——通話開始時，這些設定都會傳送至工作階段請求。每個 prop 僅在 widget 的可發布金鑰於 **瀏覽器覆寫** 中允許時才會生效；否則工作階段請求會因 `400 override_not_allowed` 而失敗：

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

請參閱 [React 元件參考資料](/zh-Hant/widget/react)，取得完整的 prop 表格。

若要建立完全自訂的 UI，請使用 [無介面 hook](/zh-Hant/widget/headless-hook) 管理語音工作階段，同時建構自己的介面。此 hook 會提供即時音訊音量，供你建立隨音訊反應的視覺效果。

每次 widget 對話都算作一通通話。它會計入你組織的[同時通話限制](/api-reference/introduction#call-limits)（預設為 20 通進行中的通話，與電話及其他通話共用），以及 widget 的 25 個作用中工作階段上限（若你的同時通話限制較高，則以該限制為準）。達到任一限制時，必須等到一通通話結束後，才能開始新的對話。

---

## 整合選項

選擇適合你的技術堆疊的整合方式：

<CardGroup cols={3}>
  <Card title="React 元件" icon="react" href="/zh-Hant/widget/react">
    預先建置的 UI 元件，內建通話控制項與狀態顯示。匯入、傳入 props，即可完成。
  </Card>
  <Card title="無頭 Hook" icon="code" href="/zh-Hant/widget/headless-hook">
    完整掌控 UI。`useThunderPhone` Hook 會管理語音工作階段，同時讓你建立自己的介面。
  </Card>
  <Card title="CDN／指令碼標籤" icon="globe" href="/zh-Hant/widget/cdn-script-tag">
    不需要打包工具。透過指令碼標籤載入小工具，適用於靜態網站、WordPress 及其他非 React 環境。
  </Card>
</CardGroup>

---

## 樣式設定

小工具內建由 `theme` prop 控制的淺色與深色主題，以及由 `primaryColor` prop 控制的強調色。如需更深入的自訂，你可以覆寫 CSS 自訂屬性與類別。詳情請參閱[樣式設定指南](/zh-Hant/widget/styling)。

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