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

ウィジェットを正しくレンダリングするには、CSS ファイルをインポートする必要があります。インポートしない場合、ウィジェットはスタイルなしで表示されます。

Props

コンポーネントは ThunderPhoneWidgetProps を介して以下の props を受け取ります。

Prop	型	必須	デフォルト	説明
`publishableKey`	`string`	はい	—	開発者設定の公開可能 API キー（`pk_live_...`）。エージェントはキーのウィジェット設定から自動的に解決されます。
`theme`	`'light' \| 'dark'`	いいえ	`'light'`	カラースキーム。ウィジェットのルートに `tp--light` または `tp--dark` クラスを適用します。
`primaryColor`	`string`	いいえ	`'#000000'`（ライト）/ `'#ffffff'`（ダーク）	アクセントカラーとして使用する CSS カラー文字列（通話ボタン、波形、アクティブインジケーター）。
`title`	`string`	いいえ	`'Voice assistant'`	ウィジェットバーに表示するテキスト。
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	いいえ	`'bottom-right'`	ウィジェットの固定ビューポート位置。
`apiBase`	`string`	いいえ	`'https://api.thunderphone.com/v1'`	API ベース URL のオーバーライド。
`language`	`string`	いいえ	—	セッションごとの言語オーバーライド。`en`、`es`、`fr-FR` などの言語コードまたはロケールです。未設定の場合、エージェントに設定された言語が適用されます。
`voice`	`string`	いいえ	—	セッションごとの音声オーバーライド。`maria` などの音声名です。未設定の場合、エージェントに設定された音声が適用されます。
`context`	`string`	いいえ	—	エージェントに渡す、セッションごとの事実に基づくページまたはサイトコンテキスト（例: 訪問者が閲覧しているページの詳細）。サーバー側で 12,000 文字に切り詰められます。
`onConnect`	`() => void`	いいえ	—	音声セッションが正常に接続されたときに呼び出されます。
`onDisconnect`	`() => void`	いいえ	—	セッションが終了したときに呼び出されます。
`onError`	`(error) => void`	いいえ	—	エラー発生時に呼び出されます。`error` オブジェクトには `error`（コード）フィールドと `message` フィールドがあります。
`className`	`string`	いいえ	—	ウィジェットコンテナに適用する追加の CSS クラス名。
`ringtone`	`boolean \| 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）へ渡され、そのセッションにおけるエージェントの設定済みデフォルト値を上書きします。

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ベースを使用

セルフホスト型またはプロキシAPIエンドポイントを使用している場合にのみ、apiBaseを設定する必要があります。デフォルトではhttps://api.thunderphone.com/v1が指定されています。

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

エラー処理

onErrorコールバックが実行されると、次の2つのフィールドを持つエラーオブジェクトを受け取ります。

フィールド	型	説明
`error`	`string`	機械可読なエラーコード
`message`	`string`	人間が読めるエラー説明

一般的なエラーコードには、許可されていないドメイン、エージェントが見つからない、無効なAPIキーなどがあります。

次のステップ

ヘッドレスフック

UIを完全に制御するには、代わりに useThunderPhone フックを使用します。

スタイリング

CSSカスタムプロパティで色、サイズ、レイアウトをカスタマイズします。

​インストール

​基本的な使用方法

​Props

​例

​カスタムカラーを使用したダークテーマ

​カスタム位置

​セッションごとの言語、音声、コンテキスト

​イベントコールバックを使用

​カスタムスタイルを使用

​着信音を使用

​カスタムAPIベースを使用

​エラー処理

​次のステップ

ヘッドレスフック

スタイリング

インストール

基本的な使用方法

Props

例

カスタムカラーを使用したダークテーマ

カスタム位置

セッションごとの言語、音声、コンテキスト

イベントコールバックを使用

カスタムスタイルを使用

着信音を使用

カスタムAPIベースを使用

エラー処理

次のステップ