埋め込み可能な音声ウィジェット

数行のコードで、あらゆるウェブサイトに音声AIエージェントを追加

ThunderPhone の埋め込み音声ウィジェットを使用すると、Web サイトの訪問者はブラウザから直接 AI エージェントと会話できます。電話は不要です -- ユーザーはボタンをクリックするだけで、ThunderPhone を利用したリアルタイム音声会話を開始できます。

このウィジェットは、ライトテーマとダークテーマに対応するグラスモーフィックなバーとして表示され、アクセントカラーと配置をカスタマイズできます。@thunderphone/widget npm パッケージとして配布されており、バンドラーを使用しない環境向けに CDN からも利用できます。

前提条件#

ウィジェットを埋め込む前に、ThunderPhone ダッシュボードで次の 3 つの手順を完了してください。

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 エージェントに接続できるグラスモーフィックな通話バーが表示されます。

カスタマイズ#

ウィジェットには、外観を設定する 4 つの props があります。

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

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

さらに3つのプロパティで外観ではなくセッションをカスタマイズできます。いずれも通話開始時にセッションリクエストへ転送されます。各プロパティは、ウィジェットの公開可能キーで ブラウザのオーバーライド として許可されている場合にのみ機能します。許可されていない場合、セッションリクエストは 400 override_not_allowed で失敗します。

完全な props の一覧については、React コンポーネントリファレンスを参照してください。

完全にカスタムな UI を作成する場合は、ヘッドレスフックを使用して、独自のインターフェースを構築しながら音声セッションを管理します。このフックは、音声に反応するビジュアライゼーションを構築するためのリアルタイム音量レベルを公開します。

各ウィジェットの会話は1件の通話です。組織の同時通話数上限（デフォルトでは進行中の通話20件で、電話およびその他の通話と共有）と、ウィジェットのアクティブセッション上限25件（同時通話数上限のほうが高い場合はその上限）にカウントされます。いずれかの上限に達すると、通話が終了するまで新しい会話を開始できません。

統合オプション#

スタックに適した統合方法を選択します。

スタイリング#

ウィジェットには、theme propで制御するライトテーマとダークテーマ、およびprimaryColor propで制御するアクセントカラーが組み込まれています。さらに細かくカスタマイズするには、CSSカスタムプロパティとクラスをオーバーライドします。詳細はスタイリングガイドを参照してください。