# Personalization

## Overview

Personalization allows you to adapt your agent’s behavior for each individual user, enabling more natural and contextually relevant conversations. ElevenLabs offers multiple approaches to personalization:

1. **Dynamic Variables** - Inject runtime values into prompts and messages
2. **Overrides** - Completely replace system prompts or messages
3. **Conversation initiation webhooks** - Fetch that data from your server when a conversation starts

## Personalization Methods

::::card-grid
:::card{title="Dynamic Variables" href="/guides/elevenagents-customization-personalization-dynamic-variables"}
Define runtime values using `{{ var_name }}` syntax to personalize your agent’s messages, system prompts, and tools.
:::

:::card{title="Overrides" href="/guides/elevenagents-customization-personalization-overrides"}
Completely replace system prompts, first messages, language, or voice settings for each conversation.
:::

:::card{title="Conversation initiation webhooks" href="/guides/elevenagents-customization-personalization#conversation-initiation-webhooks"}
Fetch dynamic variables and overrides from your server for inbound conversations.
:::
::::

## Conversation Initiation Client Data Structure

The `conversation_initiation_client_data` object defines what can be customized when starting a conversation. Clients can send it directly. A conversation initiation webhook returns the same object.

```json
{
  "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"
}
```

:::callout{intent="warning"}
System dynamic variables (those prefixed with `system__`) cannot be sent or overridden in the client initiation payload. Only custom dynamic variables can be set via the `dynamic_variables` field.
:::

## Conversation initiation webhooks

For inbound telephony and messaging, ElevenAgents can fetch this initiation data from your server instead of from the client. When the webhook is enabled, ElevenAgents sends a `POST` request and applies the JSON you return.

Configure the webhook URL and header secrets in [Agents settings](https://elevenlabs.io/app/agents/settings). On the agent **Security** tab, enable **Fetch initiation client data from a webhook** and any override fields your response may include.

The webhook runs for a new inbound conversation on Twilio voice, Exotel, SIP trunk, WhatsApp, or Twilio SMS when initiation client data is not already present.

Outbound Twilio voice, Exotel, SIP, and WhatsApp calls trigger it only if the outbound request did not include `conversation_initiation_client_data`. Outbound WhatsApp messages never trigger it — pass dynamic variables on the outbound request instead.

It does not run for widget or SDK conversations, other messaging integrations, or resumed WhatsApp and SMS threads.

:::callout{intent="warning"}
Preview conversations started from the agent settings page do not trigger conversation initiation webhooks. Use the **Dynamic Variables** placeholders in the agent editor while testing in Preview. Those placeholders are not used in production inbound conversations.
:::

ElevenAgents sends caller context in the request body:

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

`caller_id` and `called_number` are phone numbers on Twilio, Exotel, SIP, and SMS. On inbound WhatsApp they are the WhatsApp user ID and your WhatsApp phone number ID. On outbound calls, `caller_id` is your number and `called_number` is the person being dialed. `call_sid` is the provider call SID on telephony and an empty string on WhatsApp and SMS. SIP calls may also include `call_id` and `sip_headers`.

Your response must use the `conversation_initiation_client_data` shape above. Include every custom dynamic variable the agent defines. Overrides are optional and must be enabled in **Security**. The HTTP response body must be 256 KB or smaller (262,144 bytes).

A failed or timed-out webhook can prevent the conversation from starting. For Twilio setup, see [Twilio personalization](/guides/elevenagents-customization-personalization-twilio-personalization). This webhook is separate from [post-call webhooks](/guides/elevenagents-workflows-post-call-webhooks).

## Choosing the Right Approach

| Method                               | Best For                                                                                                                                              | Implementation                                                                                  |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Dynamic Variables**                | Inserting user-specific data into templated content - Maintaining consistent agent behavior with personalized details - Personalizing tool parameters | Define variables with `{{ variable_name }}` and pass values at runtime                          |
| **Overrides**                        | Completely changing agent behavior per user - Switching languages or voices - Legacy applications (consider migrating to Dynamic Variables)           | Enable specific override permissions in security settings and pass complete replacement content |
| **Conversation initiation webhooks** | Personalizing inbound Twilio, SIP, WhatsApp, or SMS conversations from your server - Looking up caller context before the conversation starts         | Enable the webhook in Security settings and return `conversation_initiation_client_data`        |

## Learn More

- [Dynamic Variables Documentation](/guides/elevenagents-customization-personalization-dynamic-variables)
- [Overrides Documentation](/guides/elevenagents-customization-personalization-overrides)
- [Twilio personalization](/guides/elevenagents-customization-personalization-twilio-personalization)

## Related pages

- [Administration](./administration-index.md)
- [API reference](./api-reference-index.md)
- [Changelog](./changelog-index.md)
- [ElevenAgents](./elevenagents-index.md)
- [ElevenAPI](./elevenapi-index.md)
- [ElevenCreative](./elevencreative-index.md)
- [ElevenLabs Documentation Docs](../index.md)
- [General Troubleshooting FAQ](./troubleshooting-index.md)
- [General Website FAQ](./website-index.md)
- [Help Center](./help-center-2-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.