可嵌入式語音小工具

只需數行程式碼，即可在任何網站加入語音 AI 智能體

ThunderPhone 可嵌入式語音小工具讓網站訪客直接透過瀏覽器與 AI 智能體交談。無需撥打電話——使用者只需按一下按鈕，即可開始由 ThunderPhone 驅動的即時語音對話。

此小工具會顯示為玻璃擬態通話列，自動配合淺色及深色主題，並可自訂強調色及位置。小工具以 @thunderphone/widget npm 套件發佈，亦可透過 CDN 用於非打包工具環境。

先決條件#

嵌入小工具前，請先在 ThunderPhone 控制台 完成以下三個步驟：

1. 建立網頁小工具

   前往控制台的 網頁小工具，然後建立小工具。選擇你要提供的智能體。每個小工具均有專屬的可發布金鑰（pk_live_...），可安全地加入用戶端程式碼；系統會根據該金鑰識別智能體。

2. 設定允許的網域

   在同一個小工具中，加入將會嵌入小工具的網域。支援萬用字元（例如 *.example.com）。此清單可防止他人將你的金鑰複製到其他網站後使用小工具；這並非身分驗證，因為瀏覽器以外的指令碼可以傳送任何 Origin 標頭。生產環境不會自動允許 localhost：如要在本機針對生產 API 進行測試，請將其加入清單。

3. 選擇瀏覽器覆寫設定

   如你的網頁設定 language、voice 或 context，請在 瀏覽器覆寫設定 下分別啟用。新小工具預設不接受任何覆寫設定，而工作階段請求如包含未啟用的設定，將會以 400 override_not_allowed 失敗。請參閱瀏覽器覆寫設定。

快速開始#

安裝套件：

npm install @thunderphone/widget

將小工具加入你的應用程式：

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}

完成。你的使用者會看見玻璃擬態通話列，只需按一下即可連接至你的 AI 智能體。

自訂#

小工具提供四個外觀屬性：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>

另外三個 prop 用於自訂工作階段，而非外觀——通話開始時，全部都會轉送至工作階段請求。每個 prop 僅會在 widget 的 publishable key 於 瀏覽器覆寫 下獲准使用時生效；否則工作階段請求會因 400 override_not_allowed 而失敗：

完整的屬性表請參閱 React 元件參考。

如需完全自訂的介面，請使用 無介面 Hook 管理語音工作階段，同時建立自己的介面。此 Hook 會提供即時音訊音量，方便建立會隨音訊反應的視覺效果。

每次 widget 對話均視為一次通話，會計入你組織的並行通話上限（預設為 20 個進行中的通話，並與電話及其他通話共用），以及 widget 的 25 個活躍工作階段上限（如你的並行通話上限較高，則以該上限為準）。達到任何一項上限時，必須待通話結束後才可開始新的對話。

整合選項#

選擇適合你技術架構的整合方式：

樣式設定#

小工具內置淺色及深色主題，可透過 theme prop 控制；重點色則可透過 primaryColor prop 控制。如需更深入自訂，你可覆寫 CSS 自訂屬性及類別。詳情請參閱樣式設定指南。