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

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

モダリティ設定

ウィジェットは、用途に合わせて柔軟な入力モードをサポートしています。ダッシュボードの チャンネル → ウィジェット → インターフェース で設定できます。

利用可能なモード：

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

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

ウィジェットの埋め込み

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

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

ウィジェット属性

この基本的な埋め込みコードでは、エージェントのダッシュボードで定義されたデフォルト設定でウィジェットが表示されます。 ウィジェットでは、さらにカスタマイズするためのさまざまな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>

<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属性を使用して、ランタイム時のエージェントの動作をカスタマイズできます。これらの機能は併用することも、個別に使用することも、使用しないこともできます。

動的変数

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

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

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

外観のカスタマイズ

ウィジェットの外観、表示テキスト、言語選択などをカスタマイズできます。

リッチコンテンツ

リッチコンテンツを使用すると、エージェントはメッセージとともにインタラクティブなコンポーネントで応答できます。ダッシュボードの チャンネル → ウィジェット → リッチコンテンツ で設定します。

リッチコンテンツはテキスト会話で表示され、音声会話では 会話のリアルタイム文字起こし を インターフェース で有効にした場合に表示されます。埋め込みウィジェットでのみ利用できます。

エージェントによるリッチコンテンツの使用方法

最初のメッセージの返信を除き、エージェントは各ターンでクイック返信またはカルーセルを表示するかどうかを決定します。コンポーネントを必要としない返信はプレーンテキストのままです。表示するタイミングや方法を調整するには、エージェントのシステムプロンプトで説明してください。

新しいエージェントでは、クイック返信とカルーセルがデフォルトで有効になっています。リッチコンテンツが利用可能になる前に作成されたエージェントでは、ウィジェット設定で有効にしてください。

高度な実装

クライアントツール

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

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

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

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

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

実装例

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

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