---
title: "嵌入網頁小工具"
description: "只需加入一個 script 標籤，即可在你的市場推廣或支援網站加入語音智能體——訪客可直接透過瀏覽器與它交談，無需電話號碼。"
---

網頁小工具讓你網站的訪客透過瀏覽器咪高峰，一按即可與 AI 智能體進行對話。這是一套獨立的 JavaScript / React SDK，設有專屬的 [SDK 參考文件](/yue/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](/yue/webhooks/call-incoming)，為每位訪客選擇智能體。適合已登入用戶、A/B 測試或按頁面路由。
  </Step>
  <Step title="列出允許的網域">
    可發佈金鑰會鎖定原始來源。你必須列出所有會嵌入小工具的主機名稱。
    本機開發期間一律允許 `localhost` / `127.0.0.1`。
  </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"]
  }'
```

```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 文件](/yue/widget/overview)涵蓋三種整合方式：

<CardGroup cols={3}>
  <Card title="React 元件" icon="react" href="/yue/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`。
  </Card>
  <Card title="無介面 Hook" icon="circle-nodes" href="/yue/widget/headless-hook">
    用於自訂介面的 `useThunderPhone()`。
  </Card>
  <Card title="CDN script 標籤" icon="code" href="/yue/widget/cdn-script-tag">
    適用於非打包工具網站的 `ThunderPhone.mount({...})`。
  </Card>
</CardGroup>

三者均接受相同的 `publishableKey`，並會渲染咪高峰按鈕及通話中的音訊元素。

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

## 小工具模式 webhook

當使用 `mode="webhook"` 時，ThunderPhone 會在每次工作階段開始時，以 `web.incoming` payload 呼叫你的 `webhook_url`。請回傳你希望為該訪客執行的智能體設定——其格式與電話通話使用的[回應綱要](/yue/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="/yue/widget/overview">
    React／hook／CDN 整合詳情。
  </Card>
  <Card title="每通通話的動態設定" icon="bolt" href="/yue/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>