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

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

<Note>
  これらはすべて cURL を使わずに実行できます。**Web Widgets** ダッシュボード
  ページ（`/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="許可するドメインを一覧化">
    ウィジェットを埋め込むすべてのホスト名を指定します。ブラウザはセッションリクエストごとに
    ページのオリジンを送信するため、この一覧により、キーが別のサイトにコピーされた場合に
    機能しないようにできます。これは認証ではありません。ブラウザ外のスクリプトは任意の `Origin`
    ヘッダーを送信できます。本番環境では `localhost` は自動的に許可されません。本番APIに対して
    ローカルでテストするには、一覧に `localhost` を追加してください。
  </Step>
  <Step title="ブラウザオーバーライドを選択">
    ページから送信できるセッション設定を決定します。新しいキーでは何も許可されません。
    [ブラウザオーバーライド](#browser-overrides)を参照してください。
  </Step>
</Steps>

## 公開可能キーを作成

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

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

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

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

| 設定 | ウィジェット prop | 変更内容 |
|---------|-------------|-----------------|
| `context` | `context` | ページのテキスト。参照用としてエージェントプロンプトに追加されます |
| `variables` | なし（未加工の `POST /v1/widget/session` のみ） | プロンプト内の `{{variable}}` プレースホルダーの値 |
| `voice` | `voice` | このセッションのエージェント音声 |
| `language` | `language` | セッション開始時の言語 |

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

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

```json
{
  "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 トークン）。また、[プロンプトサイズ追加料金](/ja/guides/billing-and-topups)の対象になります。エージェントには、これを指示ではなくページコンテンツとして扱うよう伝えられます。

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

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

```json
{
  "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>