个性化 | ElevenLabs Documentation

概述

个性化功能可针对每位用户调整智能体行为，让对话更自然、更贴合上下文。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 提供的联系人上下文合并。

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

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

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

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

{
  "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 个性化。此 webhook 与通话后 webhook 相互独立。

选择合适的方式

方式	最适用场景	实现方式
动态变量	在模板内容中插入用户专属数据 - 在保持智能体行为一致的同时添加个性化详情 - 个性化工具参数	使用 `{{ variable_name }}` 定义变量，并在运行时传递值
覆盖	按用户完全更改智能体行为 - 切换语言或音色 - 旧版应用（建议迁移至动态变量）	在安全设置中启用特定覆盖权限，并传递完整的替换内容
对话发起 webhook	从服务器个性化呼入 Twilio、SIP、WhatsApp 或 SMS 对话 - 在对话开始前查询来电者上下文	在安全设置中启用 webhook，并返回 `conversation_initiation_client_data`

概述

个性化方式

对话发起客户端数据结构

对话发起 webhook

选择合适的方式

了解更多