嵌入網頁小工具

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

網頁小工具讓你網站的訪客透過瀏覽器咪高峰，一按即可與 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 會在每次工作階段開始時，以 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 篩選，即可建立只顯示小工具的 控制台。

下一步#