---
title: "嵌入網頁小工具"
description: "只要加入一個指令碼標籤，即可將語音智慧體嵌入你的行銷或支援網站——訪客可直接透過瀏覽器與它交談，無需電話號碼。"
---

網頁小工具讓你的網站訪客可透過瀏覽器的麥克風，與智慧體進行點擊通話對話。這是獨立的
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="列出允許的網域">
    列出每個會嵌入小工具的主機名稱。瀏覽器會在每次工作階段請求中傳送
    頁面的來源，因此當有人將你的金鑰複製到其他網站時，這份清單會阻止金鑰繼續運作。這不是
    驗證機制：瀏覽器外的指令碼可以傳送任何 `Origin`
    標頭。在正式環境中不會自動允許 `localhost`；若要以正式 API 在本機測試，請將 `localhost` 加入
    清單。
  </Step>
  <Step title="選擇瀏覽器覆寫設定">
    決定你的頁面可以傳送哪些工作階段設定。新建立的金鑰不接受任何覆寫設定；請參閱[瀏覽器覆寫設定](#browser-overrides)。
  </Step>
</Steps>

## 建立可公開金鑰

<CodeGroup>
```bash Static agent
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"],
    "allowed_overrides": ["context"]
  }'
```

```bash Dynamic via webhook
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="無介面鉤子" icon="circle-nodes" href="/zh-Hant/widget/headless-hook">
    以 `useThunderPhone()` 建立自訂使用者介面。
  </Card>
  <Card title="CDN 指令碼標籤" icon="code" href="/zh-Hant/widget/cdn-script-tag">
    適用於非套件打包網站的 `ThunderPhone.mount({...})`。
  </Card>
</CardGroup>

三者都接受相同的 `publishableKey`，並會呈現麥克風按鈕
及通話中的音訊元素。

## 瀏覽器覆寫

小工具可從頁面傳送四項每個工作階段的設定：

| 設定 | 小工具屬性 | 變更內容 |
|---------|-------------|-----------------|
| `context` | `context` | 頁面中的文字，會附加至智慧體提示詞作為參考 |
| `variables` | 無（僅限原始 `POST /v1/widget/session`） | 提示詞中 `{{variable}}` 預留位置的值 |
| `voice` | `voice` | 此工作階段中智慧體的語音 |
| `language` | `language` | 工作階段開始時使用的語言 |

你的可發布金鑰是公開的，因此任何取得該金鑰的人都能傳送這些
設定，包括透過偽造你網域的指令碼。每項設定預設皆為關閉，直到你在金鑰上允許：
在控制台中建立或編輯小工具時，於 **瀏覽器覆寫** 下方勾選，或透過
[可發布金鑰 API](/api-reference/publishable-keys) 設定
`allowed_overrides`。僅允許你的頁面實際傳送的設定。

若工作階段請求攜帶金鑰未允許的設定，請求會以 `400` 失敗，並指出該設定：

```json
{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}
```

兩種模式皆會套用此檢查。在 Webhook 模式中，允許的設定也會轉送至你的 `web.incoming` Webhook（`context` 會以
`website_context` 傳送）。在此設定推出前建立的金鑰允許全部四項設定，因此既有嵌入項會繼續運作；請關閉你未使用的設定。

小工具的 `context` 會截斷為 12,000 個字元（約為一般英文文字的 3,400 個詞元），並計入
[提示詞大小附加費](/zh-Hant/guides/billing-and-topups)。
智慧體會被告知將其視為頁面內容，而非指令。

## 小工具模式網路回呼

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

```json
{
  "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>