嵌入網頁小工具

網頁小工具讓網站訪客透過瀏覽器的咪高峰，與 AI 智能體進行點按通話對話。這是獨立的 JavaScript / React SDK，設有專屬的 SDK 參考文件 ——本指南聚焦於小工具所需的 ThunderPhone 端設定。

先決條件

1. 建立智能體

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

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

   可發布金鑰會鎖定來源。你必須列出所有會嵌入小工具的主機名稱。 本機開發期間一律允許 localhost / 127.0.0.1。

建立可發布金鑰

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

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，並會顯示咪高峰按鈕 及通話中的音訊元素。

小工具的 context 會截斷至 12,000 個字元（約相當於 3,400 個一般英文文字 token），並會計入 提示詞大小附加費。

小工具模式 webhook

使用 mode="webhook" 時，ThunderPhone 會於每次 工作階段開始時，向你的 webhook_url 發送包含 web.incoming 資料負載的呼叫。傳回你希望為該訪客執行的智能體 設定——其格式與電話通話使用的 回應結構 相同：

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

你可將自己工作階段中的內容（例如哪位客戶正在瀏覽、 他們所在的頁面）加入提示詞，並按每次發佈切換智能體。

監察工作階段

小工具工作階段會顯示於 GET /v1/calls，並設有 direction="widget" —— 其逐字稿、錄音、評分及 收費方式均與電話通話相同。按 direction 篩選，即可建立只顯示小工具的 控制台。

下一步