ThunderPhone 2.0 正式上線。自助開通，每分鐘 2¢ 起。查看公告
立即開始

Widget

View as Markdown
Open in
ClaudeChatGPTCursor

React 元件

在 React 應用程式中嵌入 ThunderPhone 語音小工具

ThunderPhoneWidget 元件會呈現具有玻璃擬態風格的通話列，內建靜音、結束通話及顯示連線狀態的控制項。這是在 React 應用程式中加入語音人工智慧功能最快的方法。

安裝

npm install @thunderphone/widget

基本用法

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

Props

此元件可透過 ThunderPhoneWidgetProps 接受以下 props：

屬性類型必填預設值說明
publishableKeystring是--控制台 網頁小工具中的可發布 API 金鑰（pk_live_...）。系統會根據金鑰的小工具設定自動解析智慧體。
theme'light' | 'dark'否'light'色彩配置。將 tp--light 或 tp--dark 類別套用至小工具根元素。
primaryColorstring否'#000000' (light) / '#ffffff' (dark)作為強調色使用的 CSS 色彩字串（通話按鈕、波形、啟用中的指示器）。
titlestring否'Voice assistant'顯示於小工具列中的文字。
position'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'否'bottom-right'小工具在檢視區中的固定位置。
apiBasestring否'https://api.thunderphone.com/v1'覆寫 API 基礎 URL。
languagestring否--每個工作階段的語言覆寫設定——語言代碼或地區設定，例如 en、es 或 fr-FR。未設定時，會套用智慧體已設定的語言。需要在金鑰的瀏覽器覆寫下設定 language。
voicestring否--每個工作階段的語音覆寫設定——語音名稱，例如 maria。未設定時，會套用智慧體已設定的語音。需要在金鑰的瀏覽器覆寫下設定 voice。
contextstring否--傳遞給智慧體的每個工作階段事實性頁面或網站情境（例如訪客正在瀏覽頁面的詳細資訊）。伺服器端會截斷為 12,000 個字元。需要在金鑰的瀏覽器覆寫下設定 context。
onConnect() => void否--語音工作階段成功連線時呼叫。
onDisconnect() => void否--工作階段結束時呼叫。
onError(error) => void否--發生錯誤時呼叫。error 物件包含 error（代碼）和 message 欄位。
classNamestring否--套用至小工具容器的額外 CSS 類別名稱。
ringtoneboolean | string否false連線時播放鈴聲。true 使用預設鈴聲，或使用自訂音訊的 URL 字串。

範例

深色主題搭配自訂顏色

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

自訂位置

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

每個工作階段的語言、語音和情境

當通話開始時，language、voice 與 context 屬性會轉送至工作階段請求（POST /widget/session），並覆寫該工作階段中智慧體已設定的預設值。在控制台中該小工具的 瀏覽器覆寫 下啟用你要使用的每個屬性（或在金鑰的 allowed_overrides 中啟用）。新建立的小工具不接受任何覆寫，而帶有未啟用覆寫的工作階段請求會以 400 override_not_allowed 失敗；請參閱瀏覽器覆寫。

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

使用 context 為智慧體提供訪客目前所在頁面的事實資訊——例如產品詳細資料、定價或頁面專屬常見問題。智慧體會將其視為頁面內容，而非指令。伺服器端會將其截斷為 12,000 個字元。

搭配事件回呼

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

搭配自訂樣式

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

請參閱樣式指南，瞭解所有可用的 CSS 類別和自訂屬性。

搭配鈴聲

建立連線時播放電話響鈴聲：

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

傳入音訊檔案 URL 以使用自訂鈴聲：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

當小工具處於 connecting 狀態時，鈴聲會循環播放；智慧體連線後，鈴聲會平順淡出。

搭配自訂 API 基底

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

錯誤處理

觸發 onError 回呼時，會收到包含兩個欄位的錯誤物件：

欄位類型說明
errorstring機器可讀的錯誤代碼
messagestring人類可讀的錯誤說明

常見錯誤代碼包括不允許的網域、找不到智慧體，以及無效的 API 金鑰。

後續步驟

無介面 Hook

需要完全掌控 UI？改用 useThunderPhone Hook。

樣式設定

使用 CSS 自訂屬性自訂顏色、尺寸與版面配置。