Skip to main content
網頁小工具可讓你的網站訪客透過瀏覽器的麥克風，點擊即可與 AI 智慧體交談。它是獨立的 JavaScript / React SDK，並有自己的 SDK 參考文件——本指南著重介紹小工具所需的 ThunderPhone 端設定。
無需使用 cURL 即可完成所有設定：網頁小工具控制台頁面 （/dashboard/web-widgets）可建立小工具、設定其模式與智慧體、管理允許的網域，並提供嵌入程式碼片段。

​
先決條件

1

建立智慧體

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

決定路由模式

  • mode="agent" ——每個金鑰對應一個固定智慧體。最簡單。
  • mode="webhook" ——你的伺服器會透過 web.incoming webhook 為每位訪客選擇智慧體。適用於 已登入的使用者、A/B 測試或依頁面路由。
3

列出允許的網域

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

​
建立可發布金鑰

回應包含一個以 pk_live_... 開頭的 key。可發布金鑰在設計上即為公開 ——可安全地放入你的前端套件中。 請參閱可發布金鑰參考文件，了解所有欄位。
allowed_domains 至少必須包含一個項目。*.example.com 可比對子網域（例如 api.example.com），但不比對 根網域。不接受如 * 或 *.* 的純萬用字元。

​
在你的網站嵌入小工具

小工具 SDK 文件涵蓋三種整合方式：

React 元件

<ThunderPhoneWidget publishableKey="pk_live_..." />。

無介面 hook

適用於自訂 UI 的 useThunderPhone()。

CDN 指令碼標籤

適用於未使用打包工具網站的 ThunderPhone.mount({...})。
三種方式皆接受相同的 publishableKey，並會呈現麥克風按鈕 和通話中的音訊元素。 小工具的 context 會截斷為 12,000 個字元（約為 3,400 個一般英文文字的 token），並計入 提示詞大小附加費。

​
小工具模式 webhook

當 mode="webhook" 時，ThunderPhone 會在每個工作階段開始時，以 web.incoming 酬載呼叫你的 webhook_url。傳回你希望為該訪客執行的 智慧體設定——其遵循與電話通話相同的 回應結構描述：
你可以將自己工作階段中的情境資訊（例如正在瀏覽的客戶、 所在頁面）加入提示詞，並依發布階段切換智慧體。

​
查看工作階段

小工具工作階段會顯示在 GET /v1/calls 中，並帶有 direction="widget"——其逐字稿、錄音、評分和計費方式皆與電話通話相同。依 direction 篩選，即可建立僅顯示小工具的控制台。

​
後續步驟

小工具 SDK 參考資料

React／hook／CDN 整合詳細資訊。

動態逐通話設定

端對端實作 mode="webhook" 流程。

可發布金鑰參考資料

金鑰資源中的每個欄位。

麥克風工作階段 API

略過小工具；直接驅動 LiveKit 以建立自訂 UI。