Developer cookbook

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

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

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

前提条件#

1. エージェントを作成

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

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

   公開可能キーはオリジンにロックされます。ウィジェットを埋め込むすべてのホスト名を指定する必要があります。 ローカル開発中は localhost / 127.0.0.1 が常に許可されます。

公開可能キーを作成#

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"]
  }'

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 を受け取り、マイクボタンと 通話中の音声要素をレンダリングします。

ウィジェットの 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 でフィルタリングして、ウィジェット専用の ダッシュボードを構築します。

次のステップ#