> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# ウィジェットのカスタマイズ
**ウィジェット**を使えば、ElevenAgentsをあらゆるウェブサイトにすぐに統合できます。UIからウィジェットをカスタマイズすることも、スタイルや動作を完全に制御できるタイプセーフな[ElevenAgents SDK](/docs/ja/eleven-api/resources/libraries)を使用することもできます。SDKによるオーバーライドは、UIでのカスタマイズより優先されます。
ウィジェットはマルチモーダルで、テキストとオーディオの両方を処理できます。
> **Note**
>
> ClaudeまたはほかのMCPクライアントから、[ホスト型MCPサーバー](/docs/ja/eleven-agents/operate/hosted-mcp)を通じて
> エージェントのウィジェット設定と共有可能なリンクを取得することもできます。
## モダリティ設定
ウィジェットは、ユースケースに合わせて柔軟な入力モードに対応しています。ダッシュボードの**Channels**→**Widget**→**Interface**でこれらのオプションを設定します。
> **Note**
>
> マルチモーダルはクライアントSDKで完全にサポートされています。詳しくは
> [こちら](/docs/ja/eleven-api/resources/libraries)をご覧ください。
**利用可能なモード：**
* **音声のみ**（デフォルト）：ユーザーは音声のみで操作します。
* **音声＋テキスト**：会話中に音声入力とテキスト入力を切り替えられます。
* **チャットモード**：テキストメッセージで開始した場合、音声機能なしのチャット（テキストのみ）モードで会話が始まります。
SDKを介してチャット（テキストのみ）モードを使用する方法については、[チャットモードガイド](/docs/ja/eleven-agents/guides/chat-mode)をご覧ください。
> **Note**
>
> ウィジェットのデフォルトは音声のみモードです。マルチモーダルな
> インタラクションを可能にするにはテキスト入力の切り替えを有効にするか、テキストで開始する完全なテキストベースの会話には
> テキストのみモードのサポートを有効にしてください。
## ウィジェットの埋め込み
> **Note**
>
> 現在、ウィジェットには認証を無効にした公開エージェントが必要です。
> エージェント設定の**Advanced**タブで無効になっていることを確認してください。
このコードスニペットをウェブサイトの``セクションに追加してください。サイト全体で利用できるよう、メインの`index.html`ファイルに配置します：
**`Widget embed code`**
```html title="Widget embed code"
```
> **Info**
>
> セキュリティを強化するには、エージェントの**Allowlist**（**Security**タブ内）で許可ドメインを定義してください。
> これにより、指定したホストのみにアクセスが制限されます。
## ウィジェット属性
この基本的な埋め込みコードでは、エージェントのダッシュボードで定義したデフォルト設定でウィジェットが表示されます。
ウィジェットでは、さらにカスタマイズするためのさまざまなHTML属性をサポートしています：
#### コア設定
```html
```
#### 外観のカスタマイズ
```html
```
#### テキストのカスタマイズ
```html
```
#### Markdownレンダリング
ウィジェットはエージェントの応答内のMarkdownをレンダリングします。フィッシングを防ぐため、リンクはデフォルトでプレーンテキストとして表示されます。
```html
```
## ランタイム設定
ランタイムでエージェントの動作をカスタマイズするために、さらに2つのhtml属性を使用できます。この2つの機能は、併用、個別利用、またはどちらも使用しないことができます。
### 動的変数
動的変数を使うと、ランタイム値をエージェントのメッセージ、システムプロンプト、ツールに挿入できます。
```html
```
エージェントが必要とするすべての動的変数をウィジェットに渡す必要があります。
> **Info**
>
> 詳しくは[動的変数ガイド](/docs/ja/eleven-agents/customization/personalization/dynamic-variables)をご覧ください。
### オーバーライド
オーバーライドを使うと、ランタイムでエージェントの動作を完全にカスタマイズできます：
```html
```
オーバーライドは特定のフィールドに対して有効にでき、完全に任意です。
> **Info**
>
> 詳しくは[オーバーライドガイド](/docs/ja/eleven-agents/customization/personalization/overrides)をご覧ください。
## 外観のカスタマイズ
ウィジェットの外観、テキストコンテンツ、言語選択などをカスタマイズします。
#### ダッシュボードで更新
ダッシュボードでエージェントを開き、**Widget**タブに移動すると、外観、アバター、テキスト、利用規約、言語サポートなどをカスタマイズできます。
#### CLIで更新
#### エージェント設定を取得
```bash
elevenlabs agents pull --agent ""
```
#### \`agent_configs/\.json\`を編集
`platform_settings.widget`配下のフィールドを設定します。たとえば、オーブの色とフィードバックモードを変更するには：
```json
{
"platform_settings": {
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB"
},
"feedback_mode": "during",
"bg_color": "#ffffff",
"text_color": "#000000",
"btn_color": "#000000",
"btn_text_color": "#ffffff"
}
}
}
```
#### 変更をプッシュ
```bash
elevenlabs agents push --agent ""
```
#### APIで更新
```python
from elevenlabs import ElevenLabs
elevenlabs = ElevenLabs()
elevenlabs.conversational_ai.agents.update(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
platform_settings={
"widget": {
"variant": "full",
"placement": "bottom-right",
"avatar": {
"type": "orb",
"color_1": "#6DB035",
"color_2": "#F5CABB",
},
"feedback_mode": "during",
},
},
)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
platformSettings: {
widget: {
variant: "full",
placement: "bottom-right",
avatar: {
type: "orb",
color1: "#6DB035",
color2: "#F5CABB",
},
feedbackMode: "during",
},
},
});
```
#### 外観
ブランドアイデンティティに合わせて、ウィジェットの色と形状をカスタマイズします。
#### フィードバック
エージェントのパフォーマンスを改善するために、ユーザーのインサイトを収集します。エージェントのナレッジベースとシステムプロンプトの微調整に活用できます。
**収集モード**
* **なし**：フィードバック収集を完全に無効にします。
* **会話中**：会話中のリアルタイムフィードバックに対応します。フィードバックのきっかけとなったエージェントの応答などの追加メタデータも収集されるため、ギャップをさらに特定しやすくなります。
* **会話後**：会話後に1回だけフィードバックプロンプトを表示します。
> **Note**
>
> カスタムSDK実装を使用する場合は、[API](/docs/ja/eleven-agents/api-reference/conversations/create)を通じてプログラムからフィードバックを送信してください。
#### アバター
音声オーブを設定するか、独自のアバターを指定します。
**利用可能なオプション**
* **オーブ**：2つのグラデーションカラーを選択します（例：#6DB035＆#F5CABB）。
* **リンク／画像**：カスタムアバター画像を使用します。
#### 表示テキスト
ボタンラベルの変更など、表示されるすべてのウィジェットテキスト要素をカスタマイズします。
#### 利用規約
会話前にカスタムの利用規約を表示します。
**利用可能なオプション**
* **利用規約の内容**：Markdownを使用してポリシーテキストを整形します。
* **ローカルストレージキー**：再訪ユーザーへの表示を避けるためのキー（例："terms_accepted"）。
**使い方**
利用規約は、通話を開始する前にモーダルでユーザーに表示されます：
利用規約はMarkdownで記述でき、次のことができます：
* 外部ポリシーへのリンクを追加
* 見出しやリストでテキストを整形
* 強調やスタイルを追加
Markdownの詳細については、[CommonMarkヘルプガイド](https://commonmark.org/help/)をご覧ください。
> **Info**
>
> 一度承諾されると、ステータスはローカルに保存され、以降の訪問時にユーザーへ再度表示されることはありません。
#### 言語
ウィジェットで多言語サポートを有効にします。
> **Note**
>
> 言語選択を有効にするには、まずエージェントに[追加の言語を 追加](/docs/ja/eleven-agents/customization/voice/customization/language)する必要があります。
#### ミュート
ユーザーがウィジェットでオーディオをミュートできるようにします。
ミュートボタンを追加するには、エージェントの`widget`
設定の`interface`カードでこれを有効にしてください。
#### 共有ページ
公開ウィジェットのランディングページ（共有可能なリンク）をカスタマイズします。
**利用可能なオプション**
* **説明**：通話の目的を説明する短い段落を記載します。
---
## 高度な実装
> **Note**
>
> より高度なカスタマイズには、Next.js、React、またはPythonアプリケーションでタイプセーフな[ElevenAgents SDK](/docs/ja/eleven-api/resources/libraries)を使用してください。
### クライアントツール
クライアントツールを使用すると、イベントリスナーを追加してウィジェットの機能を拡張できます。これにより、ウィジェットで次のようなアクションを実行できます：
* ユーザーを特定のページにリダイレクトする
* サポートチームにメールを送信する
* ユーザーを外部URLにリダイレクトする
これらのツールの動作例を見るには、このページの右下にあるエージェントで通話を開始してください。参考として、[ソースコードはGitHubで公開されています](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/assets/scripts/widget.js)。
#### クライアントツールの作成
最初のクライアントツールを作成するには、[クライアントツールガイド](/docs/ja/eleven-agents/customization/tools/client-tools)に従ってください。
#### 例：\`redirectToExternalURL\`ツールの作成
#### 実装例
以下は、JavaScriptコードでウィジェットによってトリガーされた`redirectToExternalURL`ツールを処理する例です：
**`index.js`**
```javascript title="index.js"
document.addEventListener("DOMContentLoaded", () => {
const widget = document.querySelector("elevenlabs-convai");
if (widget) {
// Listen for the widget's "call" event to trigger client-side tools
widget.addEventListener("elevenlabs-convai:call", (event) => {
event.detail.config.clientTools = {
// Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
redirectToExternalURL: ({ url }) => {
window.open(url, "_blank", "noopener,noreferrer");
},
};
});
}
});
```
> **Info**
>
> React、Next.js、Pythonでの実装については、タイプセーフな[SDK](/docs/ja/eleven-api/resources/libraries)をご覧ください。