React 元件

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

安裝

npm install @thunderphone/widget

基本用法

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

屬性

此元件透過 ThunderPhoneWidgetProps 接受以下屬性：

範例

深色主題配合自訂顏色

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 props 會轉送至工作階段請求（POST /widget/session），並覆寫該工作階段中智能體已設定的預設值：

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"
/>

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

使用自訂 API 基礎網址

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

錯誤處理

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

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

下一步