可嵌入式語音小工具

ThunderPhone 可嵌入式語音小工具可讓你的網站訪客直接從瀏覽器與 AI 智慧體交談。不需要撥打電話——使用者只要點擊按鈕，即可開始由 ThunderPhone 驅動的即時語音對話。此小工具會呈現為可適應淺色與深色主題的玻璃擬態橫條，並支援自訂強調色與位置。它以 @thunderphone/widget npm 套件形式發布，也可透過 CDN 用於未使用打包工具的環境。

先決條件

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

建立可公開的 API 金鑰

前往控制台設定中的 開發人員，並建立可公開的金鑰。可公開金鑰以 pk_live_ 開頭，可安全地包含在用戶端程式碼中。

設定允許的網域

在相同的開發人員設定中，新增要嵌入小工具的網域。開發時一律允許使用 localhost。支援萬用字元（例如 *.example.com）。

建立網頁小工具

前往控制台中的 網頁小工具，並建立一個小工具。選擇你要公開的智慧體及要使用的可公開金鑰。系統會根據你的可公開金鑰設定自動解析智慧體。

可公開金鑰（pk_live_...）不等同於你的私密 API 權杖。可公開金鑰專為用戶端使用而設計，且僅適用於你允許網域上的小工具工作階段。切勿在用戶端程式碼中使用私密 API 權杖。

快速開始

安裝套件：

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：

Prop	預設值	說明
`theme`	`'light'`	白色玻璃使用 `'light'`，深色玻璃使用 `'dark'`
`primaryColor`	`'#000000'`（淺色）/ `'#ffffff'`（深色）	開始按鈕、波形與連線指示器的強調色
`title`	`'Voice assistant'`	顯示於小工具中的文字
`position`	`'bottom-right'`	檢視區角落：`'bottom-right'`、`'bottom-left'`、`'top-right'`、`'top-left'`

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

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

另外三個 prop 用於自訂工作階段，而非外觀——通話開始時都會轉送至工作階段請求：

Prop	說明
`language`	每個工作階段的語言覆寫——使用如 `en`、`es` 或 `fr-FR` 的語言代碼或地區設定
`voice`	每個工作階段的語音覆寫——使用如 `maria` 的語音名稱
`context`	傳遞給智慧體的頁面或網站事實背景資訊（伺服器端會截斷為 12,000 個字元）

請參閱 React 元件參考資料，取得完整的 prop 表格。若要建立完全自訂的 UI，請使用無介面 hook 管理語音工作階段，同時建構自己的介面。此 hook 會提供即時音訊音量，供你建立隨音訊反應的視覺效果。

整合選項

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

React 元件

預先建置的 UI 元件，內建通話控制項與狀態顯示。匯入、傳入 props，即可完成。

無頭 Hook

完整掌控 UI。useThunderPhone Hook 會管理語音工作階段，同時讓你建立自己的介面。

CDN／指令碼標籤

不需要打包工具。透過指令碼標籤載入小工具，適用於靜態網站、WordPress 及其他非 React 環境。

樣式設定

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

需要協助嗎？請透過 support@thunderphone.com 聯絡我們

​先決條件

​快速開始

​自訂

​整合選項

React 元件

無頭 Hook

CDN／指令碼標籤

​樣式設定

先決條件

快速開始

自訂

整合選項

樣式設定