Personalización

Descubre cómo personalizar el comportamiento de tu agente con variables dinámicas y sustituciones.

Descripción general

La personalización te permite adaptar el comportamiento de tu agente a cada usuario, para lograr conversaciones más naturales y relevantes según el contexto. ElevenLabs ofrece varios métodos de personalización:

Variables dinámicas: inserta valores en tiempo de ejecución en prompts y mensajes
Sustituciones: reemplaza por completo los prompts o mensajes del sistema
Webhooks de inicio de conversación: obtén esos datos de tu servidor cuando empiece una conversación

Métodos de personalización

Variables dinámicas

Define valores en tiempo de ejecución con la sintaxis {{ var_name }} para personalizar los mensajes, prompts del sistema y herramientas de tu agente.

Sustituciones

Reemplaza por completo los prompts del sistema, los primeros mensajes, el idioma o la configuración de voz de cada conversación.

Webhooks de inicio de conversación

Obtén variables dinámicas y sustituciones de tu servidor para conversaciones entrantes.

Estructura de datos del cliente para el inicio de conversación

El objeto conversation_initiation_client_data define qué se puede personalizar al iniciar una conversación. Los clientes pueden enviarlo directamente. Un webhook de inicio de conversación devuelve el mismo objeto.

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

Las variables dinámicas del sistema (las que tienen el prefijo system__) no se pueden enviar ni sustituir en la carga útil de inicio del cliente. Solo puedes establecer variables dinámicas personalizadas mediante el campo dynamic_variables.

Webhooks de inicio de conversación

Para telefonía y mensajería entrantes, ElevenAgents puede obtener estos datos de inicio de tu servidor en lugar de recibirlos del cliente. Cuando el webhook está habilitado, ElevenAgents envía una solicitud POST y aplica el JSON que devuelvas.

Configura la URL del webhook y los secretos de cabecera en la configuración de Agents. En la pestaña Seguridad del agente, habilita Obtener datos de inicio del cliente desde un webhook y los campos de sustitución que pueda incluir tu respuesta.

El webhook se ejecuta para una nueva conversación entrante en Twilio Voice, Exotel, troncal SIP, WhatsApp o SMS de Twilio cuando los datos de inicio del cliente aún no están presentes. También se ejecuta para sesiones de Amazon Connect, donde tu respuesta se combina con el contexto de contacto que proporciona Amazon Connect.

Las llamadas salientes de Twilio Voice, Exotel, SIP y WhatsApp solo lo activan si la solicitud saliente no incluía conversation_initiation_client_data. Los mensajes salientes de WhatsApp nunca lo activan; pasa las variables dinámicas en la solicitud saliente.

No se ejecuta para conversaciones con widgets o SDK, otras integraciones de mensajería ni hilos reanudados de WhatsApp y SMS.

Las conversaciones de vista previa iniciadas desde la página de configuración del agente no activan los webhooks de inicio de conversación. Usa los marcadores de posición de Variables dinámicas en el editor del agente mientras pruebas en Vista previa. Esos marcadores de posición no se utilizan en las conversaciones entrantes de producción.

ElevenAgents envía el contexto de la persona que llama en el cuerpo de la solicitud:

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

caller_id y called_number son números de teléfono en Twilio, Exotel, SIP y SMS. En WhatsApp entrante, son el ID de usuario de WhatsApp y el ID de tu número de teléfono de WhatsApp. En llamadas salientes, caller_id es tu número y called_number es la persona a la que se llama. call_sid es el SID de llamada del proveedor en telefonía y una cadena vacía en WhatsApp, SMS y Amazon Connect. Las llamadas SIP también pueden incluir call_id y sip_headers. Las sesiones de Amazon Connect incluyen call_id establecido como el ID de contacto.

Tu respuesta debe usar la estructura de conversation_initiation_client_data anterior. Incluye todas las variables dinámicas personalizadas que defina el agente. Las sustituciones son opcionales y deben estar habilitadas en Seguridad. El cuerpo de la respuesta HTTP debe tener un tamaño máximo de 256 KB (262.144 bytes).

Un webhook que falle o agote el tiempo de espera puede impedir que se inicie la conversación. Para la configuración de Twilio, consulta personalización de Twilio. Este webhook es independiente de los webhooks posteriores a la llamada.

Elegir el enfoque adecuado

Método	Ideal para	Implementación
Variables dinámicas	Insertar datos específicos del usuario en contenido con plantillas - Mantener un comportamiento coherente del agente con detalles personalizados - Personalizar parámetros de herramientas	Define variables con `{{ variable_name }}` y pasa valores en tiempo de ejecución
Sustituciones	Cambiar por completo el comportamiento del agente para cada usuario - Cambiar de idioma o voz - Aplicaciones heredadas (considera migrar a Variables dinámicas)	Habilita permisos específicos de sustitución en la configuración de seguridad y pasa contenido de reemplazo completo
Webhooks de inicio de conversación	Personalizar conversaciones entrantes de Twilio, SIP, WhatsApp o SMS desde tu servidor - Consultar el contexto de quien llama antes de que se inicie la conversación	Habilita el webhook en la configuración de Seguridad y devuelve `conversation_initiation_client_data`

Descripción general

Métodos de personalización

Estructura de datos del cliente para el inicio de conversación

Webhooks de inicio de conversación

Elegir el enfoque adecuado

Más información