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

# Variables dinámicas

Las **variables dinámicas** te permiten insertar valores de ejecución en los mensajes, prompts de sistema y herramientas de tu agente. Así puedes personalizar cada conversación con datos específicos del usuario sin crear varios agentes.

## Descripción general

Puedes integrar variables dinámicas en varios aspectos de tu agente:

* En los **prompts de sistema** para personalizar el comportamiento y el contexto
* En los **primeros mensajes** para personalizar los saludos
* En los **parámetros y encabezados de herramientas** para pasar datos específicos del usuario

Estos son algunos ejemplos en los que las variables dinámicas resultan útiles:

* **Personalizar saludos** con los nombres de los usuarios
* **Incluir detalles de la cuenta** en las respuestas
* **Pasar datos** a llamadas de herramientas
* **Personalizar el comportamiento** según los niveles de suscripción
* **Acceder a información del sistema** como el ID de conversación o la duración de la llamada

> **Info**
>
> Las variables dinámicas son ideales para insertar datos específicos del usuario que no deberían estar codificados de forma fija en la
> configuración de tu agente.

## Variables dinámicas del sistema

Tu agente tiene acceso a estas variables del sistema disponibles automáticamente:

* `system__agent_id` - Identificador único del agente que inició la conversación (se mantiene estable durante toda la conversación)
* `system__current_agent_id` - Identificador único del agente activo actualmente (cambia tras transferencias entre agentes)
* `system__caller_id` - Número de teléfono de quien llama (solo llamadas de voz)
* `system__called_number` - Número de teléfono de destino (solo llamadas de voz)
* `system__call_duration_secs` - Duración de la llamada en segundos
* `system__time_utc` - Hora UTC actual (formato ISO)
* `system__time` - Hora actual en la zona horaria especificada (formato legible, p. ej., "Friday, 12:33 12 December 2025")
* `system__timezone` - Zona horaria proporcionada por el usuario (debe ser válida para tzinfo)
* `system__conversation_id` - Identificador único de conversación de ElevenLabs
* `system__call_sid` - SID de la llamada (solo llamadas de twilio)
* `system__call_id` - Identificador único de la llamada del troncal SIP (solo llamadas de troncal SIP)
* `system__agent_turns` - Número total de turnos de conversación que ha realizado el agente durante esta conversación.
* `system__current_agent_turns` - Número de turnos de conversación que ha realizado el agente actual. Se restablece cada vez que la conversación se transfiere a otro agente.
* `system__current_subagent_turns` - Número de turnos de conversación que ha realizado el subagente actual. Se restablece cada vez que el workflow pasa a otro nodo.
* `system__is_text_only` - Verdadero si la conversación funciona en modo de solo texto; falso en caso contrario.
* `system__conversation_history` - Representación serializada en JSON del historial de conversación actual. Se evalúa de forma diferida en el momento en que se consulta. Consulta los [detalles del formato](#conversation-history-format) a continuación.

Las variables del sistema:

* Están disponibles sin configuración de ejecución
* Llevan el prefijo `system__` (prefijo reservado)
* Se actualizan automáticamente durante toda la conversación

> **Warning**
>
> Las variables dinámicas personalizadas no pueden usar el prefijo reservado `system__`.

### Formato del historial de conversación

La variable `system__conversation_history` contiene un objeto JSON con la siguiente estructura:

```json
{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}
```

Cada entrada incluye un `role` (`"user"`, `"agent"` o `"tool"`) y uno de los siguientes elementos:

* `message` — el contenido de texto del turno
* `tool_requests` — una matriz de llamadas a herramientas realizadas por el agente, con valores de parámetros resueltos
* `tool_results` — una matriz de respuestas de herramientas

Si el resultado o un parámetro de una herramienta contiene un historial de conversación anidado, se oculta con un marcador de posición (p. ej., `[conversation_history (5 turns)]`) para evitar una expansión recursiva sin límites.

Esta variable es útil para pasar el contexto de la conversación a herramientas (p. ej., webhooks o LLM personalizados) o para incluir el historial de conversación en los prompts de subagentes durante las transferencias.

## Variables dinámicas secretas

Las variables dinámicas secretas se rellenan igual que las variables dinámicas normales, pero indican a nuestros ElevenAgents que solo deben
usarse en encabezados de variables dinámicas y nunca enviarse a un proveedor de LLM como parte del prompt de sistema o del primer mensaje de un agente.

Te recomendamos usarlas para tokens de autenticación o ID privados que no deban enviarse a un LLM. Para crear una variable dinámica secreta, solo tienes que añadir el prefijo `secret__` a la variable dinámica.

> **Warning**
>
> Los valores secretos se devuelven ocultos como `<REDACTED>`, incluso en webhooks posteriores a la llamada y en la
> API de conversaciones. No uses el prefijo `secret__` para valores que necesites consultar después de la
> conversación. Pásalos como variables dinámicas normales o pasa un identificador no confidencial y busca
> el valor confidencial en tu propio sistema.

## Actualizar variables dinámicas desde herramientas

Las [llamadas a herramientas](https://elevenlabs.io/docs/eleven-agents/customization/tools) pueden crear o actualizar variables dinámicas si devuelven un objeto JSON válido. Para especificar qué se debe extraer, establece las rutas de objeto mediante notación de puntos. Si el campo o la ruta no existe, no se actualiza nada.

Ejemplo de un objeto de respuesta y notación de puntos:

* Status corresponde a la ruta: `response.status`
* El correo electrónico del primer usuario de la matriz users corresponde a la ruta: `response.users.0.email`

**`JSON`**

```JSON title="JSON"
{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}
```

Para actualizar una variable dinámica con el correo electrónico del primer usuario, configura la asignación así.

![Parámetros de consulta](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp)

Las asignaciones son un campo de cada herramienta de webhook, documentado [aquí](/docs/es/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments).

## Guía

### Requisitos previos

* Una [cuenta de ElevenLabs](https://elevenlabs.io)
* Un agente conversacional de ElevenLabs configurado ([crea uno aquí](/docs/es/eleven-agents/quickstart))

#### Define variables dinámicas en los prompts

Añade variables con llaves dobles `{{variable_name}}` en:

* Prompts de sistema
* Primeros mensajes
* Parámetros de herramientas

![Variables dinámicas en mensajes](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp)

![Variables dinámicas en mensajes](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp)

#### Define variables dinámicas en herramientas

También puedes definir variables dinámicas en la configuración de la herramienta.
Para crear una nueva variable dinámica, establece el tipo de valor como Variable dinámica y haz clic en el botón `+`.

![Configurar marcadores de posición](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp)

![Configurar marcadores de posición](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp)

#### Configura marcadores de posición

Configura valores predeterminados para hacer pruebas sin pasar variables durante la ejecución.

#### Actualizar desde el panel

Establece valores predeterminados para cada variable dinámica en el panel del agente.

![Configurar marcadores de posición](/docs/_fern-img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp)

#### Actualizar mediante la CLI

#### Descarga la configuración del agente

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Edita \`agent_configs/\<agent-name>.json\`

Establece `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders`. Cada clave es el nombre de la variable; el valor es el marcador de posición que se usa durante las pruebas:

```json
{
  "conversation_config": {
    "agent": {
      "dynamic_variables": {
        "dynamic_variable_placeholders": {
          "user_name": "Angelo",
          "account_type": "premium"
        }
      }
    }
  }
}
```

#### Envía tus cambios

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Actualizar mediante la API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "dynamic_variables": {
                "dynamic_variable_placeholders": {
                    "user_name": "Angelo",
                    "account_type": "premium",
                }
            }
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      dynamicVariables: {
        dynamicVariablePlaceholders: {
          user_name: "Angelo",
          account_type: "premium",
        },
      },
    },
  },
});
```

#### Pasa variables durante la ejecución

Al iniciar una conversación, proporciona las variables dinámicas en tu código:

> **Tip**
>
> Asegúrate de tener instalada la última versión del [SDK](/docs/es/eleven-agents/libraries/python).

**`Python`**

```python title="Python" focus={10-23} maxLines=25
import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

dynamic_vars = {
    "user_name": "Angelo",
}

config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)

conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Simple callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)

conversation.start_session()

signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())
```

**`JavaScript`**

```javascript title="JavaScript" focus={7-20} maxLines=25
import { Conversation } from '@elevenlabs/client';

class VoiceAgent {
  ...

  async startConversation() {
    try {
        // Request microphone access
        await navigator.mediaDevices.getUserMedia({ audio: true });

        this.conversation = await Conversation.startSession({
            agentId: 'agent_id_goes_here', // Replace with your actual agent ID

            dynamicVariables: {
                user_name: 'Angelo'
            },

            ... add some callbacks here
        });
    } catch (error) {
        console.error('Failed to start conversation:', error);
        alert('Failed to start conversation. Please ensure microphone access is granted.');
    }
  }
}
```

**`Swift`**

```swift title="Swift"
let dynamicVars: [String: DynamicVariableValue] = [
  "customer_name": .string("John Doe"),
  "account_balance": .number(5000.50),
  "user_id": .int(12345),
  "is_premium": .boolean(true)
]

// Create session config with dynamic variables
let config = SessionConfig(
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    dynamicVariables: dynamicVars
)

// Start the conversation
let conversation = try await Conversation.startSession(
    config: config
)
```

**`Widget`**

```html title="Widget"
<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>
```

## Integración con la página pública de conversación

La página pública de conversación admite variables dinámicas mediante parámetros de URL, lo que te permite personalizar las conversaciones al compartir enlaces de agentes. Esto resulta especialmente útil para insertar agentes personalizados en sitios web, correos electrónicos o campañas de marketing.

### Métodos de parámetros de URL

Hay dos métodos para pasar variables dinámicas a la página pública de conversación:

#### Método 1: JSON codificado en Base64

Pasa las variables como un objeto JSON codificado en Base64 mediante el parámetro `vars`:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
```

El parámetro `vars` contiene JSON codificado en Base64:

```json
{ "user_name": "John", "account_type": "premium" }
```

#### Método 2: Parámetros de consulta individuales

Pasa las variables mediante parámetros de consulta con el prefijo `var_`:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium
```

### Prioridad de parámetros

Cuando se usan ambos métodos a la vez, los parámetros individuales `var_` tienen prioridad sobre las variables codificadas en Base64 para evitar conflictos:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John
```

En este ejemplo, `user_name` será "John" (de `var_user_name`) en lugar de "Jane" (de `vars` codificado en Base64).

### Ejemplos de implementación

#### Generación de URL en JavaScript

```javascript
// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}

// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });

  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });

  return `${baseURL}?${params.toString()}`;
}

// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};

const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
```

#### Generación de URL en Python

```python
import base64
import json
from urllib.parse import urlencode, quote

def generate_talk_to_url(agent_id, variables):
    """Generate URL with base64-encoded variables"""
    base_url = "https://elevenlabs.io/app/talk-to"
    encoded_vars = base64.b64encode(json.dumps(variables).encode()).decode()
    return f"{base_url}?agent_id={agent_id}&vars={encoded_vars}"

def generate_talk_to_url_with_params(agent_id, variables):
    """Generate URL with individual var_ parameters"""
    base_url = "https://elevenlabs.io/app/talk-to"
    params = {"agent_id": agent_id}

    for key, value in variables.items():
        params[f"var_{key}"] = value

    return f"{base_url}?{urlencode(params)}"

# Usage
variables = {
    "user_name": "John Doe",
    "account_type": "premium",
    "session_id": "sess_123"
}

url_method1 = generate_talk_to_url("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
url_method2 = generate_talk_to_url_with_params("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
```

#### Construcción manual de URL

```
# Base64-encoded method
1. Create JSON: {"user_name": "John", "account_type": "premium"}
2. Encode to base64: eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
3. Add to URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

# Individual parameters method
1. Add each variable with var_ prefix
2. URL encode values if needed
3. Final URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium
```

## Tipos admitidos

Las variables dinámicas admiten estos tipos de valores:

#### Cadena

Valores de texto

#### Número

Valores numéricos

#### Booleano

Valores verdadero/falso

## Solución de problemas

#### Las variables no se sustituyen

Comprueba que:

* Los nombres de las variables coincidan exactamente (distinguen entre mayúsculas y minúsculas)
* Las variables usen llaves dobles: `{{ variable_name }}`
* Las variables estén incluidas en tu objeto dynamic_variables

#### Errores de tipo

Asegúrate de que:

* Los valores de las variables coincidan con el tipo esperado
* Los valores sean únicamente cadenas, números o booleanos