> ## 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.

# 埋め込み可能な音声ウィジェット

> 数行のコードで、あらゆるウェブサイトに音声AIエージェントを追加

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

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

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## 前提条件

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

<Steps>
  <Step title="公開可能 API キーを作成">
    ダッシュボード設定の **開発者** に移動し、公開可能キーを作成します。公開可能キーは `pk_live_` で始まり、クライアントサイドコードに含めても安全です。
  </Step>

  <Step title="許可するドメインを設定">
    同じ開発者設定で、ウィジェットを埋め込むドメインを追加します。開発時は常に `localhost` が許可されます。ワイルドカードもサポートされています（例: `*.example.com`）。
  </Step>

  <Step title="Web ウィジェットを作成">
    ダッシュボードの **Web ウィジェット** に移動し、ウィジェットを作成します。公開するエージェントと使用する公開可能キーを選択します。エージェントは、公開可能キーの設定から自動的に解決されます。
  </Step>
</Steps>

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

***

## クイックスタート

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

```bash theme={null}
npm install @thunderphone/widget
```

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

```tsx theme={null}
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) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

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

外観ではなくセッションをカスタマイズする props がさらに 3 つあります。いずれも通話開始時にセッションリクエストへ転送されます。

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

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

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

***

## 統合オプション

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

<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>