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

# 个性化

## 概述

个性化功能可针对每位用户调整智能体行为，让对话更自然、更贴合上下文。ElevenLabs 提供多种个性化方式：

1. **动态变量**：在提示词和消息中注入运行时值
2. **覆盖**：完全替换系统提示词或消息
3. **对话发起 webhook**：在对话开始时从服务器获取数据

## 个性化方式

#### [动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)

使用 `{{ var_name }}` 语法定义运行时值，个性化智能体的消息、系统提示词和工具。

#### [覆盖](/docs/zh/eleven-agents/customization/personalization/overrides)

为每次对话完全替换系统提示词、首条消息、语言或音色设置。

#### [对话发起 webhook](/docs/zh/eleven-agents/customization/personalization#conversation-initiation-webhooks)

为呼入对话从服务器获取动态变量和覆盖设置。

## 对话发起客户端数据结构

`conversation_initiation_client_data` 对象定义了发起对话时可自定义的内容。客户端可直接发送此对象。对话发起 webhook 也会返回相同的对象。

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

> **Warning**
>
> 系统动态变量（以 `system__` 为前缀）无法通过客户端发起载荷发送或覆盖。只能通过
> `dynamic_variables` 字段设置自定义动态变量。

## 对话发起 webhook

对于呼入电话和消息，ElevenAgents 可从服务器而非客户端获取这些发起数据。启用 webhook 后，ElevenAgents 会发送 `POST` 请求并应用返回的 JSON。

在 [智能体设置](https://elevenlabs.io/app/agents/settings) 中配置 webhook URL 和请求头密钥。在智能体的 **安全** 标签页中，启用 **从 webhook 获取发起客户端数据** 以及响应中可能包含的所有覆盖字段。

当尚未提供发起客户端数据时，Twilio 语音、Exotel、SIP 中继、WhatsApp 或 Twilio SMS 的新呼入对话会运行此 webhook。它也会用于 [Amazon Connect](/docs/zh/eleven-agents/phone-numbers/c-caa-s-integrations/amazon-connect#dynamic-variables) 会话，此时响应会与 Amazon Connect 提供的联系人上下文合并。

仅当外呼请求未包含 `conversation_initiation_client_data` 时，Twilio 语音、Exotel、SIP 和 WhatsApp 外呼才会触发它。WhatsApp 外发消息绝不会触发它，请改为在外发请求中传递动态变量。

它不会用于 widget 或 SDK 对话、其他消息集成，也不会用于恢复的 WhatsApp 和 SMS 会话线程。

> **Warning**
>
> 从智能体设置页面发起的预览对话不会触发对话发起 webhook。在预览中测试时，请使用智能体编辑器中的 **动态变量** 占位符。
> 这些占位符不会用于生产环境的呼入对话。

ElevenAgents 会在请求正文中发送来电者上下文：

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

在 Twilio、Exotel、SIP 和 SMS 中，`caller_id` 和 `called_number` 是电话号码。对于呼入 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 个性化](/docs/zh/eleven-agents/customization/personalization/twilio-personalization)。此 webhook 与 [通话后 webhook](/docs/zh/eleven-agents/workflows/post-call-webhooks) 相互独立。

## 选择合适的方式

<thead>
  <tr>
    <th>
      方式
    </th>

    <th>
      最适用场景
    </th>

    <th>
      实现方式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      **动态变量**
    </td>

    <td>
      * 在模板内容中插入用户专属数据 - 在保持智能体行为一致的同时添加个性化详情 - 个性化工具参数
    </td>

    <td>
      使用 

      `{{ variable_name }}`

       定义变量，并在运行时传递值
    </td>
  </tr>

  <tr>
    <td>
      **覆盖**
    </td>

    <td>
      * 按用户完全更改智能体行为 - 切换语言或音色 - 旧版应用（建议迁移至动态变量）
    </td>

    <td>
      在安全设置中启用特定覆盖权限，并传递完整的替换内容
    </td>
  </tr>

  <tr>
    <td>
      **对话发起 webhook**
    </td>

    <td>
      * 从服务器个性化呼入 Twilio、SIP、WhatsApp 或 SMS 对话 - 在对话开始前查询来电者上下文
    </td>

    <td>
      在安全设置中启用 webhook，并返回 `conversation_initiation_client_data`
    </td>
  </tr>
</tbody>

## 了解更多

* [动态变量文档](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)
* [覆盖文档](/docs/zh/eleven-agents/customization/personalization/overrides)
* [Twilio 个性化](/docs/zh/eleven-agents/customization/personalization/twilio-personalization)