可嵌入式語音小工具

只需幾行程式碼，即可將語音人工智慧智慧體加入任何網站

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 智慧體。

自訂#

此小工具提供四個外觀 prop：

<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 的可發布金鑰於 瀏覽器覆寫 中允許時才會生效；否則工作階段請求會因 400 override_not_allowed 而失敗：

請參閱 React 元件參考資料，取得完整的 prop 表格。

若要建立完全自訂的 UI，請使用 無介面 hook 管理語音工作階段，同時建構自己的介面。此 hook 會提供即時音訊音量，供你建立隨音訊反應的視覺效果。

每次 widget 對話都算作一通通話。它會計入你組織的同時通話限制（預設為 20 通進行中的通話，與電話及其他通話共用），以及 widget 的 25 個作用中工作階段上限（若你的同時通話限制較高，則以該限制為準）。達到任一限制時，必須等到一通通話結束後，才能開始新的對話。

整合選項#

選擇適合你的技術堆疊的整合方式：

樣式設定#

小工具內建由 theme prop 控制的淺色與深色主題，以及由 primaryColor prop 控制的強調色。如需更深入的自訂，你可以覆寫 CSS 自訂屬性與類別。詳情請參閱樣式設定指南。