> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 嵌入網頁小工具

> 將語音智慧體加入你的行銷或支援網站——無需電話號碼。

網頁小工具可讓你的網站訪客透過瀏覽器的麥克風，點擊即可與 AI 智慧體交談。它是獨立的 JavaScript / React SDK，並有自己的 [SDK 參考文件](/zh-Hant/widget/overview)——本指南著重介紹小工具所需的 ThunderPhone 端設定。

<Note>
  無需使用 cURL 即可完成所有設定：**網頁小工具**控制台頁面
  （`/dashboard/web-widgets`）可建立小工具、設定其模式與智慧體、管理允許的網域，並提供嵌入程式碼片段。
</Note>

## 先決條件

<Steps>
  <Step title="建立智慧體">
    此智慧體的提示詞和語音將用於執行小工具工作階段。設定
    `widget_enabled: true`（預設值）。
  </Step>

  <Step title="決定路由模式">
    * `mode="agent"` ——每個金鑰對應一個固定智慧體。最簡單。
    * `mode="webhook"` ——你的伺服器會透過
      [`web.incoming` webhook](/zh-Hant/webhooks/call-incoming) 為每位訪客選擇智慧體。適用於
      已登入的使用者、A/B 測試或依頁面路由。
  </Step>

  <Step title="列出允許的網域">
    可發布金鑰會鎖定來源。你必須列出每個會嵌入小工具的主機名稱。
    在本機開發期間，`localhost` / `127.0.0.1` 一律受到允許。
  </Step>
</Steps>

## 建立可發布金鑰

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

回應包含一個以 `pk_live_...` 開頭的 `key`。**可發布金鑰在設計上即為公開**
——可安全地放入你的前端套件中。
請參閱[可發布金鑰參考文件](/api-reference/publishable-keys)，了解所有欄位。

<Warning>
  `allowed_domains` 至少必須包含一個項目。`*.example.com`
  可比對子網域（例如 `api.example.com`），但**不**比對
  根網域。不接受如 `*` 或 `*.*` 的純萬用字元。
</Warning>

## 在你的網站嵌入小工具

[小工具 SDK 文件](/zh-Hant/widget/overview)涵蓋三種整合方式：

<CardGroup cols={3}>
  <Card title="React 元件" icon="react" href="/zh-Hant/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`。
  </Card>

  <Card title="無介面 hook" icon="circle-nodes" href="/zh-Hant/widget/headless-hook">
    適用於自訂 UI 的 `useThunderPhone()`。
  </Card>

  <Card title="CDN 指令碼標籤" icon="code" href="/zh-Hant/widget/cdn-script-tag">
    適用於未使用打包工具網站的 `ThunderPhone.mount({...})`。
  </Card>
</CardGroup>

三種方式皆接受相同的 `publishableKey`，並會呈現麥克風按鈕
和通話中的音訊元素。

小工具的 `context` 會截斷為 12,000 個字元（約為 3,400
個一般英文文字的 token），並計入
[提示詞大小附加費](/zh-Hant/guides/billing-and-topups)。

## 小工具模式 webhook

當 `mode="webhook"` 時，ThunderPhone 會在每個工作階段開始時，以
`web.incoming` 酬載呼叫你的 `webhook_url`。傳回你希望為該訪客執行的
智慧體設定——其遵循與電話通話相同的
[回應結構描述](/zh-Hant/webhooks/call-incoming)：

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

你可以將自己工作階段中的情境資訊（例如正在瀏覽的客戶、
所在頁面）加入提示詞，並依發布階段切換智慧體。

## 查看工作階段

小工具工作階段會顯示在
[`GET /v1/calls`](/api-reference/calls#list-calls) 中，並帶有
`direction="widget"`——其逐字稿、錄音、評分和計費方式皆與電話通話相同。依 `direction` 篩選，即可建立僅顯示小工具的控制台。

***

## 後續步驟

<CardGroup cols={2}>
  <Card title="小工具 SDK 參考資料" icon="window-maximize" href="/zh-Hant/widget/overview">
    React／hook／CDN 整合詳細資訊。
  </Card>

  <Card title="動態逐通話設定" icon="bolt" href="/zh-Hant/guides/dynamic-call-config">
    端對端實作 `mode="webhook"` 流程。
  </Card>

  <Card title="可發布金鑰參考資料" icon="key" href="/api-reference/publishable-keys">
    金鑰資源中的每個欄位。
  </Card>

  <Card title="麥克風工作階段 API" icon="microphone" href="/api-reference/mic-sessions">
    略過小工具；直接驅動 LiveKit 以建立自訂 UI。
  </Card>
</CardGroup>