ウェブウィジェットを埋め込む

1つのスクリプトタグで、マーケティングサイトやサポートサイトに音声エージェントを追加できます。訪問者は電話番号なしで、ブラウザから直接エージェントと会話できます。

Web ウィジェットを使用すると、サイト訪問者はブラウザのマイクを通じて AI エージェントとクリックして通話できます。これは独立した JavaScript / React SDK であり、専用の SDK リファレンス があります。このガイドでは、ウィジェットに必要な ThunderPhone 側の設定に焦点を当てます。

前提条件#

1. エージェントを作成

   プロンプトと音声がウィジェットセッションで実行されるエージェントを作成します。 widget_enabled: true（デフォルト）を設定します。

2. ルーティングモードを決定
   • mode="agent" — キーごとに1つの静的エージェントを使用します。最も簡単な方法です。
   • mode="webhook" — サーバーが訪問者ごとにエージェントを選択します。選択には web.incoming webhook を使用します。ログイン済みユーザー、A/Bテスト、ページごとのルーティングに使用してください。
3. 許可するドメインを一覧化

   ウィジェットを埋め込むすべてのホスト名を指定します。ブラウザはセッションリクエストごとに ページのオリジンを送信するため、この一覧により、キーが別のサイトにコピーされた場合に 機能しないようにできます。これは認証ではありません。ブラウザ外のスクリプトは任意の Origin ヘッダーを送信できます。本番環境では localhost は自動的に許可されません。本番APIに対して ローカルでテストするには、一覧に localhost を追加してください。

4. ブラウザオーバーライドを選択

   ページから送信できるセッション設定を決定します。新しいキーでは何も許可されません。 ブラウザオーバーライドを参照してください。

公開可能キーを作成#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

レスポンスには pk_live_... で始まる key が含まれます。公開可能キーは 公開を前提に設計されています — フロントエンドバンドルに含めても安全です。 すべてのフィールドについては、公開可能キーリファレンスを参照してください。

サイトにウィジェットを追加#

3 つの統合オプションについては、 ウィジェット SDK ドキュメントで説明しています。

3 つの方法はいずれも同じ publishableKey を受け取り、マイクボタンと 通話中の音声要素をレンダリングします。

ブラウザオーバーライド#

ウィジェットは、ページからセッションごとに次の 4 つの設定を送信できます。

公開可能キーは公開情報であるため、キーを持つすべてのユーザーが、ドメインを偽装するスクリプトからも含めて、これらの 設定を送信できます。そのため、キーで許可するまで各設定は無効です。ダッシュボードでウィジェットを作成または編集する際に ブラウザの オーバーライド でチェックを入れるか、 公開可能キー API を通じて allowed_overrides を設定してください。ページが実際に送信するものだけを 許可してください。

キーで許可されていない設定を含むセッションリクエストは、400 で失敗し、該当する設定名が返されます。

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

このチェックは両方のモードに適用されます。Webhook モードでは、許可された設定は web.incoming webhook にも転送されます（context は website_context として届きます）。この設定が追加される前に作成されたキーでは、4 つすべてが許可されています。そのため、既存の埋め込みは引き続き動作します。使用していない設定は無効にしてください。

ウィジェットの context は 12,000 文字に切り詰められます（一般的な英語テキストで約 3,400 トークン）。また、プロンプトサイズ追加料金の対象になります。エージェントには、これを指示ではなくページコンテンツとして扱うよう伝えられます。

ウィジェットモードの webhook#

mode="webhook" の場合、ThunderPhone はセッション開始ごとに web.incoming ペイロードを webhook_url に送信します。その訪問者に対して実行する エージェント設定を返します。これは電話通話と同じ レスポンススキーマに従います。

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

独自のセッション情報（閲覧中の顧客や表示中のページなど）をプロンプトに組み込み、 展開ごとにエージェントを切り替えられます。

セッションを確認#

ウィジェットのセッションは、電話と同じ文字起こし、録音、評価、請求情報とともに GET /v1/calls に direction="widget" として表示されます。direction でフィルタリングして、ウィジェット専用の ダッシュボードを構築します。

次のステップ#