パーソナライズ

動的変数とオーバーライドを使ってエージェントの動作をパーソナライズする方法を学びます。

概要

パーソナライズにより、個々のユーザーに合わせてエージェントの動作を調整し、より自然で文脈に即した会話を実現できます。ElevenLabsでは、複数のパーソナライズ方法を提供しています。

動的変数 - 実行時の値をプロンプトやメッセージに挿入
オーバーライド - システムプロンプトやメッセージを完全に置き換え
会話開始Webhook - 会話の開始時にサーバーからデータを取得

パーソナライズ方法

動的変数

{{ var_name }} 構文で実行時の値を定義し、エージェントのメッセージ、システムプロンプト、ツールをパーソナライズします。

オーバーライド

会話ごとにシステムプロンプト、最初のメッセージ、言語、音声設定を完全に置き換えます。

会話開始Webhook

着信会話用の動的変数とオーバーライドをサーバーから取得します。

会話開始クライアントデータの構造

conversation_initiation_client_data オブジェクトは、会話開始時にカスタマイズできる内容を定義します。クライアントから直接送信できます。会話開始Webhookも同じオブジェクトを返します。

{
  "type": "conversation_initiation_client_data",
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "prompt": "overriding system prompt",
        "llm": "gpt-5.6-luna"
      },
      "first_message": "overriding first message",
      "language": "en"
    },
    "tts": {
      "voice_id": "voice-id-here"
    },
    "conversation": {
      "text_only": false
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso"]
    }
  },
  "custom_llm_extra_body": {
    "temperature": 0.7,
    "max_tokens": 100
  },
  "dynamic_variables": {
    "string_var": "text value",
    "number_var": 1.2,
    "integer_var": 123,
    "boolean_var": true
  },
  "user_id": "your_custom_user_id",
  "branch_id": "agtbrch_xxxx",
  "environment": "production"
}

システム動的変数（system__ で始まるもの）は、クライアント開始ペイロードで送信またはオーバーライドできません。dynamic_variables フィールドで設定できるのは、カスタム動的変数のみです。

会話開始Webhook

着信電話とメッセージングでは、ElevenAgentsはクライアントではなくサーバーからこの開始データを取得できます。Webhookを有効にすると、ElevenAgentsは POST リクエストを送信し、返されたJSONを適用します。

Webhook URLとヘッダーシークレットをエージェント設定で構成します。エージェントの セキュリティ タブで、Webhookから開始クライアントデータを取得 と、レスポンスに含める可能性のあるオーバーライドフィールドを有効にします。

開始クライアントデータがまだ存在しない場合、Twilio音声、Exotel、SIPトランク、WhatsApp、またはTwilio SMSの新しい着信会話でWebhookが実行されます。Amazon Connectのセッションでも実行され、その場合はレスポンスがAmazon Connectから提供されるコンタクトコンテキストとマージされます。

発信Twilio音声、Exotel、SIP、WhatsApp通話では、発信リクエストに conversation_initiation_client_data が含まれていない場合にのみトリガーされます。発信WhatsAppメッセージではトリガーされません。代わりに発信リクエストで動的変数を渡してください。

ウィジェットまたはSDKの会話、その他のメッセージングインテグレーション、再開されたWhatsAppおよびSMSスレッドでは実行されません。

エージェント設定ページから開始したプレビュー会話では、会話開始Webhookはトリガーされません。プレビューでテストする際は、エージェントエディターの 動的変数 プレースホルダーを使用してください。これらのプレースホルダーは、本番の着信会話では使用されません。

ElevenAgentsはリクエスト本文で発信者コンテキストを送信します。

{
  "caller_id": "+15551234567",
  "called_number": "+15557654321",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "conversation_id": "conv_8901k5zvyjhmfg983brhmhkd98n6"
}

caller_id と called_number は、Twilio、Exotel、SIP、SMSでは電話番号です。着信WhatsAppでは、それぞれWhatsAppユーザーIDとWhatsApp電話番号IDです。発信通話では、caller_id はご利用の番号、called_number は発信先の相手です。call_sid は電話ではプロバイダーの通話SIDで、WhatsApp、SMS、Amazon Connectでは空文字列です。SIP通話には call_id と sip_headers が含まれる場合もあります。Amazon Connectセッションには、コンタクトIDに設定された call_id が含まれます。

レスポンスは上記の conversation_initiation_client_data 形式を使用する必要があります。エージェントで定義されているすべてのカスタム動的変数を含めてください。オーバーライドは任意ですが、セキュリティ で有効にする必要があります。HTTPレスポンス本文は256 KB以下（262,144バイト）にする必要があります。

Webhookの失敗またはタイムアウトにより、会話を開始できなくなることがあります。Twilioのセットアップについては、Twilioのパーソナライズを参照してください。このWebhookは通話後Webhookとは別のものです。

適切な方法を選ぶ

方法	最適な用途	実装
動的変数	テンプレートコンテンツへのユーザー固有データの挿入 - パーソナライズされた詳細を維持しつつ一貫したエージェント動作を実現 - ツールパラメータのパーソナライズ	`{{ variable_name }}` で変数を定義し、実行時に値を渡す
オーバーライド	ユーザーごとにエージェントの動作を完全に変更 - 言語または音声の切り替え - レガシーアプリケーション（動的変数への移行を検討）	セキュリティ設定で特定のオーバーライド権限を有効にし、完全な置換コンテンツを渡す
会話開始Webhook	サーバーから着信Twilio、SIP、WhatsApp、SMS会話をパーソナライズ - 会話開始前に発信者コンテキストを検索	セキュリティ設定でWebhookを有効にし、`conversation_initiation_client_data` を返す

概要

パーソナライズ方法

会話開始クライアントデータの構造

会話開始Webhook

適切な方法を選ぶ

詳細