---
title: "埋め込み可能な音声ウィジェット"
description: "数行のコードで、あらゆるウェブサイトに音声AIエージェントを追加"
---

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

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

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## 前提条件

ウィジェットを埋め込む前に、[ThunderPhone ダッシュボード](https://app.thunderphone.com)で次の 3 つの手順を完了してください。

<Steps>
<Step title="ウェブウィジェットを作成">
  ダッシュボードで **ウェブウィジェット** に移動し、ウィジェットを作成します。公開するエージェントを選択します。各ウィジェットには固有の公開可能キー（`pk_live_...`）があり、クライアントサイドのコードに安全に含められます。エージェントはキーから解決されます。
</Step>

<Step title="許可するドメインを設定">
  同じウィジェットで、埋め込むドメインを追加します。ワイルドカードもサポートされています（例: `*.example.com`）。このリストにより、キーが別のサイトにコピーされてもウィジェットが動作しないようにできます。ただし、ブラウザ外のスクリプトは任意の `Origin` ヘッダーを送信できるため、これは認証ではありません。本番環境では `localhost` は自動的に許可されません。本番 API に対してローカルでテストするには、リストに追加してください。
</Step>

<Step title="ブラウザオーバーライドを選択">
  ページで `language`、`voice`、または `context` を設定する場合は、それぞれ **ブラウザオーバーライド** で有効にします。新しいウィジェットではいずれも許可されておらず、無効な設定を含むセッションリクエストは `400 override_not_allowed` で失敗します。[ブラウザオーバーライド](/ja/guides/embed-web-widget)を参照してください。
</Step>
</Steps>

<Warning>
  公開可能キー（`pk_live_...`）は、シークレット API トークンと**同じではありません**。公開可能キーはクライアントサイドでの使用を想定して設計されており、許可したドメイン上のウィジェットセッションにスコープされます。シークレット API トークンをクライアントサイドコードで使用しないでください。
</Warning>

<Note>
  ウィジェットセッションはデフォルトで 30 分後に終了します。エージェント自体の最大通話時間がそれより短い場合は、より早く終了します。[公開可能キー](/api-reference/publishable-keys)の `max_call_duration_seconds` でキーごとに上限を変更できます（最大 6 時間）。または、`null` を設定してエージェント自体の上限を使用します。
</Note>

---

## クイックスタート

パッケージをインストールします。

```bash
npm install @thunderphone/widget
```

アプリにウィジェットを追加します。

```tsx
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 があります。

| Prop | デフォルト | 説明 |
|------|---------|-------------|
| `theme` | `'light'` | 白いガラスには `'light'`、暗いガラスには `'dark'` |
| `primaryColor` | `'#000000'`（ライト）/ `'#ffffff'`（ダーク） | 開始ボタン、波形、接続中インジケーターのアクセントカラー |
| `title` | `'Voice assistant'` | ウィジェットに表示するテキスト |
| `position` | `'bottom-right'` | ビューポートの隅: `'bottom-right'`、`'bottom-left'`、`'top-right'`、`'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

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

| Prop | 説明 |
|------|-------------|
| `language` | セッションごとの言語オーバーライド -- `en`、`es`、`fr-FR` などのコードまたはロケール |
| `voice` | セッションごとの音声オーバーライド -- `maria` などの音声名 |
| `context` | エージェントに渡すページまたはサイトの事実情報コンテキスト（サーバー側で 12,000 文字に切り詰められます） |

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

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

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

---

## 統合オプション

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

<CardGroup cols={3}>
  <Card title="Reactコンポーネント" icon="react" href="/ja/widget/react">
    通話コントロールとステータス表示を組み込んだ事前構築済みUIコンポーネントです。インポートしてpropsを渡すだけで完了します。
  </Card>
  <Card title="ヘッドレスフック" icon="code" href="/ja/widget/headless-hook">
    UIを完全に制御できます。独自のインターフェースを構築しながら、`useThunderPhone`フックで音声セッションを管理します。
  </Card>
  <Card title="CDN / スクリプトタグ" icon="globe" href="/ja/widget/cdn-script-tag">
    バンドラーは不要です。静的サイト、WordPress、その他のReact以外の環境では、スクリプトタグでウィジェットを読み込みます。
  </Card>
</CardGroup>

---

## スタイリング

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

<Note>
  サポートが必要ですか？ [support@thunderphone.com](mailto:support@thunderphone.com)までお問い合わせください。
</Note>