ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Developer cookbook

嵌入網頁小工具

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

網頁小工具讓你網站的訪客透過瀏覽器咪高峰,一按即可與 AI 智能體進行對話。這是一套獨立的 JavaScript / React SDK,設有專屬的 SDK 參考文件——本指南集中說明小工具所需的 ThunderPhone 端設定。

先決條件

  1. 建立智能體

    此智能體的提示詞及語音將會用於小工具工作階段。設定 widget_enabled: true(預設值)。

  2. 決定路由模式
    • mode="agent" —— 每個金鑰對應一個固定智能體。最簡單。
    • mode="webhook" —— 你的伺服器透過 web.incoming webhook 為每位訪客選擇智能體。適用於 已登入用戶、A/B 測試或按頁面路由。
  3. 列出允許的網域

    列出所有會嵌入小工具的主機名稱。瀏覽器會在每次工作階段請求中傳送 頁面的來源,因此此清單可防止他人將你的金鑰複製到其他網站後繼續使用。這並非 驗證機制:瀏覽器以外的指令碼可以傳送任何 Origin 標頭。生產環境不會自動允許 localhost;如要針對生產 API 進行本機測試,請將 localhost 加入 清單。

  4. 選擇瀏覽器覆寫設定

    決定你的頁面可傳送哪些工作階段設定。新金鑰預設不接受任何覆寫;請參閱瀏覽器覆寫設定。

建立可發佈金鑰

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 文件涵蓋三種整合方式:

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

瀏覽器覆寫

小工具可從網頁傳送四項工作階段專用設定:

設定小工具 prop變更內容
contextcontext網頁文字,會作為參考資料附加至智能體提示詞
variables無(僅限原始 POST /v1/widget/session)提示詞中 {{variable}} 佔位符的值
voicevoice此工作階段的智能體語音
languagelanguage工作階段開始時使用的語言

你嘅可公開金鑰屬於公開資料,因此任何取得該金鑰嘅人士都可以傳送呢啲 設定,包括透過偽冒你網域嘅指令碼。因此,除非你喺金鑰上明確允許,否則各項設定 預設均會停用:你可以喺控制台建立或編輯小工具時,於 瀏覽器覆寫 勾選相關項目,或者透過 可公開金鑰 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 篩選,即可建立只顯示小工具的 控制台。


下一步