Developer cookbook

嵌入網頁小工具

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

網頁小工具讓你的網站訪客可透過瀏覽器的麥克風，與智慧體進行點擊通話對話。這是獨立的 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 個一般英文文字的詞元），並計入 提示詞大小附加費。

小工具模式網路回呼#

使用 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 篩選，即可建立僅顯示小工具的 控制台。

後續步驟#