> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webウィジェットを埋め込む

> 電話番号なしで、マーケティングサイトやサポートサイトに音声エージェントを追加。

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

<Note>
  これらはすべてcURLなしで実行できます。**ウェブウィジェット**ダッシュボードページ
  (`/dashboard/web-widgets`) で、ウィジェットの作成、モードとエージェントの設定、許可ドメインの管理、埋め込みスニペットの取得を行えます。
</Note>

## 前提条件

<Steps>
  <Step title="エージェントを作成">
    プロンプトと音声がウィジェットセッションで使用されるエージェントです。
    `widget_enabled: true`（デフォルト）に設定します。
  </Step>

  <Step title="ルーティングモードを決定">
    * `mode="agent"` — キーごとに1つの静的エージェント。最も簡単です。
    * `mode="webhook"` — サーバーが
      [`web.incoming` webhook](/ja/webhooks/call-incoming) を通じて訪問者ごとにエージェントを選択します。ログイン済みユーザー、A/Bテスト、ページごとのルーティングに使用します。
  </Step>

  <Step title="許可するドメインを一覧化">
    公開可能キーはオリジンにロックされます。ウィジェットを埋め込むすべてのホスト名を指定する必要があります。ローカル開発中は、`localhost` / `127.0.0.1` が常に許可されます。
  </Step>
</Steps>

## 公開可能キーを作成

<CodeGroup>
  ```bash Static agent theme={null}
  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"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  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"]
    }'
  ```
</CodeGroup>

レスポンスには、`pk_live_...` で始まる `key` が含まれます。**公開可能キーは意図的に公開されています**。フロントエンドバンドルに安全に含めることができます。すべてのフィールドについては、[公開可能キーリファレンス](/api-reference/publishable-keys)を参照してください。

<Warning>
  `allowed_domains` には少なくとも1つのエントリが必要です。`*.example.com`
  はサブドメイン（例: `api.example.com`）に一致しますが、ベアドメインには**一致しません**。`*` や `*.*` のようなベアワイルドカードは拒否されます。
</Warning>

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

次の3つの統合オプションについて、[ウィジェットSDKドキュメント](/ja/widget/overview)で説明しています。

<CardGroup cols={3}>
  <Card title="Reactコンポーネント" icon="react" href="/ja/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`。
  </Card>

  <Card title="ヘッドレスフック" icon="circle-nodes" href="/ja/widget/headless-hook">
    カスタムUI用の `useThunderPhone()`。
  </Card>

  <Card title="CDNスクリプトタグ" icon="code" href="/ja/widget/cdn-script-tag">
    バンドラーを使用しないサイト向けの `ThunderPhone.mount({...})`。
  </Card>
</CardGroup>

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

ウィジェットの `context` は12,000文字（一般的な英語テキストで約3,400トークン）で切り詰められ、[プロンプトサイズ追加料金](/ja/guides/billing-and-topups)の対象になります。

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

`mode="webhook"` の場合、ThunderPhoneはセッションが開始されるたびに、`web.incoming` ペイロードを含めて `webhook_url` を呼び出します。その訪問者に対して実行するエージェント設定を返します。これは電話と同じ[レスポンススキーマ](/ja/webhooks/call-incoming)に従います。

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

独自のセッションのコンテキスト（どの顧客が閲覧しているか、どのページを表示しているか）をプロンプトに組み込み、ロールアウトごとにエージェントを切り替えられます。

## セッションを確認

ウィジェットセッションは、
[`GET /v1/calls`](/api-reference/calls#list-calls) で
`direction="widget"` を指定すると表示されます。文字起こし、録音、評価、
請求は電話と同じです。`direction` でフィルタリングして、ウィジェット専用の
ダッシュボードを構築します。

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="ウィジェット SDK リファレンス" icon="window-maximize" href="/ja/widget/overview">
    React / フック / CDN 統合の詳細。
  </Card>

  <Card title="通話ごとの動的設定" icon="bolt" href="/ja/guides/dynamic-call-config">
    `mode="webhook"` フローをエンドツーエンドで実装。
  </Card>

  <Card title="公開可能キーのリファレンス" icon="key" href="/api-reference/publishable-keys">
    キーリソースのすべてのフィールド。
  </Card>

  <Card title="マイクセッション API" icon="microphone" href="/api-reference/mic-sessions">
    ウィジェットを使わず、カスタム UI 向けに LiveKit を直接操作。
  </Card>
</CardGroup>