Open in

Claude ChatGPT Cursor

嵌入網頁小工具

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

網頁小工具讓你的網站訪客可透過瀏覽器的麥克風，與智慧體進行點擊通話對話。這是獨立的 JavaScript／React SDK，並有專屬的 SDK 參考文件 ——本指南著重說明小工具所需的 ThunderPhone 端設定。

必要條件

建立智慧體
將執行小工具工作階段的提示詞與語音所屬的智慧體。設定 widget_enabled: true（預設值）。
決定路由模式
- mode="agent" ——每個金鑰對應一個固定智慧體。最簡單。
- mode="webhook" ——你的伺服器會透過 web.incoming Webhook 為每位訪客選擇智慧體。適用於已登入使用者、A/B 測試或依頁面路由。
列出允許的網域
列出每個會嵌入小工具的主機名稱。瀏覽器會在每次工作階段請求中傳送頁面的來源，因此當有人將你的金鑰複製到其他網站時，這份清單會阻止金鑰繼續運作。這不是驗證機制：瀏覽器外的指令碼可以傳送任何 Origin 標頭。在正式環境中不會自動允許 localhost；若要以正式 API 在本機測試，請將 localhost 加入清單。
選擇瀏覽器覆寫設定
決定你的頁面可以傳送哪些工作階段設定。新建立的金鑰不接受任何覆寫設定；請參閱瀏覽器覆寫設定。

建立可公開金鑰

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"]
  }'

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"]
  }'

回應會包含一個以 pk_live_... 開頭的 key。可公開金鑰的設計本來就是公開的 ——可安全地放入你的前端套件中。請參閱可公開金鑰參考文件，了解所有欄位。

將小工具加入你的網站

小工具 SDK 文件涵蓋三種整合方式：

React 元件

<ThunderPhoneWidget publishableKey="pk_live_..." />。

無介面鉤子

以 useThunderPhone() 建立自訂使用者介面。

CDN 指令碼標籤

適用於非套件打包網站的 ThunderPhone.mount({...})。

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

瀏覽器覆寫

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

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

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

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

{
  "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 個詞元），並計入提示詞大小附加費。智慧體會被告知將其視為頁面內容，而非指令。

小工具模式網路回呼

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

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

你可以將自己工作階段中的脈絡資訊（例如哪位客戶正在瀏覽、他們所在的頁面）混入提示詞，並依發布批次替換智慧體。

監控工作階段

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

後續步驟

小工具 SDK 參考資料

React／hook／CDN 整合詳細資料。

每通電話的動態設定

端對端實作 mode="webhook" 流程。

可發佈金鑰參考資料

金鑰資源上的每個欄位。

麥克風工作階段 API

略過小工具；直接使用 LiveKit 驅動自訂 UI。

嵌入網頁小工具

必要條件#

建立可公開金鑰#

將小工具加入你的網站#

瀏覽器覆寫#

小工具模式網路回呼#

監控工作階段#

後續步驟#