ウィジェットのカスタマイズ | ElevenLabs Documentation

ウィジェットを使えば、ElevenAgentsをあらゆるウェブサイトにすぐに統合できます。UIからウィジェットをカスタマイズすることも、スタイルや動作を完全に制御できるタイプセーフなElevenAgents SDKを使用することもできます。SDKによるオーバーライドは、UIでのカスタマイズより優先されます。ウィジェットはマルチモーダルで、テキストとオーディオの両方を処理できます。

ClaudeまたはほかのMCPクライアントから、ホスト型MCPサーバーを通じてエージェントのウィジェット設定と共有可能なリンクを取得することもできます。

モダリティ設定

ウィジェットは、ユースケースに合わせて柔軟な入力モードに対応しています。ダッシュボードのChannels→Widget→Interfaceでこれらのオプションを設定します。

マルチモーダルはクライアントSDKで完全にサポートされています。詳しくはこちらをご覧ください。

利用可能なモード：

音声のみ（デフォルト）：ユーザーは音声のみで操作します。
音声＋テキスト：会話中に音声入力とテキスト入力を切り替えられます。
チャットモード：テキストメッセージで開始した場合、音声機能なしのチャット（テキストのみ）モードで会話が始まります。

SDKを介してチャット（テキストのみ）モードを使用する方法については、チャットモードガイドをご覧ください。

ウィジェットのデフォルトは音声のみモードです。マルチモーダルなインタラクションを可能にするにはテキスト入力の切り替えを有効にするか、テキストで開始する完全なテキストベースの会話にはテキストのみモードのサポートを有効にしてください。

ウィジェットの埋め込み

現在、ウィジェットには認証を無効にした公開エージェントが必要です。エージェント設定のAdvancedタブで無効になっていることを確認してください。

このコードスニペットをウェブサイトの<body>セクションに追加してください。サイト全体で利用できるよう、メインのindex.htmlファイルに配置します：

Widget embed code

<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

セキュリティを強化するには、エージェントのAllowlist（Securityタブ内）で許可ドメインを定義してください。これにより、指定したホストのみにアクセスが制限されます。

ウィジェット属性

この基本的な埋め込みコードでは、エージェントのダッシュボードで定義したデフォルト設定でウィジェットが表示されます。ウィジェットでは、さらにカスタマイズするためのさまざまなHTML属性をサポートしています：

コア設定

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>

外観のカスタマイズ

<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>

テキストのカスタマイズ

<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

Markdownレンダリング

ウィジェットはエージェントの応答内のMarkdownをレンダリングします。フィッシングを防ぐため、リンクはデフォルトでプレーンテキストとして表示されます。

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

ランタイム設定

ランタイムでエージェントの動作をカスタマイズするために、さらに2つのhtml属性を使用できます。この2つの機能は、併用、個別利用、またはどちらも使用しないことができます。

動的変数

動的変数を使うと、ランタイム値をエージェントのメッセージ、システムプロンプト、ツールに挿入できます。

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

エージェントが必要とするすべての動的変数をウィジェットに渡す必要があります。

詳しくは動的変数ガイドをご覧ください。

オーバーライド

オーバーライドを使うと、ランタイムでエージェントの動作を完全にカスタマイズできます：

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

オーバーライドは特定のフィールドに対して有効にでき、完全に任意です。

詳しくはオーバーライドガイドをご覧ください。

外観のカスタマイズ

ウィジェットの外観、テキストコンテンツ、言語選択などをカスタマイズします。

ダッシュボードで更新

CLIで更新

APIで更新

ダッシュボードでエージェントを開き、Widgetタブに移動すると、外観、アバター、テキスト、利用規約、言語サポートなどをカスタマイズできます。

外観

フィードバック

アバター

表示テキスト

利用規約

言語

ミュート

共有ページ

ブランドアイデンティティに合わせて、ウィジェットの色と形状をカスタマイズします。

高度な実装

より高度なカスタマイズには、Next.js、React、またはPythonアプリケーションでタイプセーフなElevenAgents SDKを使用してください。

クライアントツール

クライアントツールを使用すると、イベントリスナーを追加してウィジェットの機能を拡張できます。これにより、ウィジェットで次のようなアクションを実行できます：

ユーザーを特定のページにリダイレクトする
サポートチームにメールを送信する
ユーザーを外部URLにリダイレクトする

これらのツールの動作例を見るには、このページの右下にあるエージェントで通話を開始してください。参考として、ソースコードはGitHubで公開されています。

クライアントツールの作成

最初のクライアントツールを作成するには、クライアントツールガイドに従ってください。

例：redirectToExternalURLツールの作成

実装例

以下は、JavaScriptコードでウィジェットによってトリガーされたredirectToExternalURLツールを処理する例です：

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");
        },
      };
    });
  }
});

React、Next.js、Pythonでの実装については、タイプセーフなSDKをご覧ください。