Open in
嵌入網頁小工具
只需加入一個 script 標籤,即可在你的市場推廣或支援網站加入語音智能體——訪客可直接透過瀏覽器與它交談,無需電話號碼。
網頁小工具讓你網站的訪客透過瀏覽器咪高峰,一按即可與 AI 智能體進行對話。這是一套獨立的 JavaScript / React SDK,設有專屬的 SDK 參考文件——本指南集中說明小工具所需的 ThunderPhone 端設定。
先決條件
- 建立智能體
此智能體的提示詞及語音將會用於小工具工作階段。設定
widget_enabled: true(預設值)。 - 決定路由模式
mode="agent"—— 每個金鑰對應一個固定智能體。最簡單。mode="webhook"—— 你的伺服器透過web.incomingwebhook 為每位訪客選擇智能體。適用於 已登入用戶、A/B 測試或按頁面路由。
- 列出允許的網域
列出所有會嵌入小工具的主機名稱。瀏覽器會在每次工作階段請求中傳送 頁面的來源,因此此清單可防止他人將你的金鑰複製到其他網站後繼續使用。這並非 驗證機制:瀏覽器以外的指令碼可以傳送任何
Origin標頭。生產環境不會自動允許localhost;如要針對生產 API 進行本機測試,請將localhost加入 清單。 - 選擇瀏覽器覆寫設定
決定你的頁面可傳送哪些工作階段設定。新金鑰預設不接受任何覆寫;請參閱瀏覽器覆寫設定。
建立可發佈金鑰
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"]
}'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 文件涵蓋三種整合方式:
<ThunderPhoneWidget publishableKey="pk_live_..." />。
用於自訂介面的 useThunderPhone()。
適用於非打包工具網站的 ThunderPhone.mount({...})。
三者均接受相同的 publishableKey,並會渲染咪高峰按鈕及通話中的音訊元素。
瀏覽器覆寫
小工具可從網頁傳送四項工作階段專用設定:
| 設定 | 小工具 prop | 變更內容 |
|---|---|---|
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 傳送)。在此設定推出前建立的金鑰允許全部四項設定,
因此現有嵌入方式可繼續運作;請停用不使用的項目。
Widget context 會截斷至 12,000 個字元(約為 3,400 個一般英文文本的
token),而且屬於模型讀取的提示內容一部分,因此較長的 context
每分鐘成本較高。
系統會指示智能體將其視為頁面內容,而非指令。
小工具模式 webhook
當使用 mode="webhook" 時,ThunderPhone 會在每次工作階段開始時,以 web.incoming payload 呼叫你的 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 篩選,即可建立只顯示小工具的
控制台。