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

# Variáveis dinâmicas

**Variáveis dinâmicas** permitem inserir valores em tempo de execução nas mensagens, nos prompts de sistema e nas ferramentas do seu agente. Assim, você pode personalizar cada conversa com dados específicos do usuário sem criar vários agentes.

## Visão geral

As variáveis dinâmicas podem ser integradas a diversos aspectos do seu agente:

* **Prompts de sistema** para personalizar o comportamento e o contexto
* **Primeiras mensagens** para personalizar as saudações
* **Parâmetros e cabeçalhos de ferramentas** para transmitir dados específicos do usuário

Veja alguns exemplos em que as variáveis dinâmicas são úteis:

* **Personalizar saudações** com nomes de usuários
* **Incluir detalhes da conta** nas respostas
* **Transmitir dados** para chamadas de ferramentas
* **Personalizar o comportamento** com base nos níveis de assinatura
* **Acessar informações do sistema** como ID da conversa ou duração da chamada

> **Info**
>
> As variáveis dinâmicas são ideais para inserir dados específicos do usuário que não devem ser codificados diretamente na
> configuração do seu agente.

## Variáveis dinâmicas do sistema

Seu agente tem acesso a estas variáveis de sistema disponíveis automaticamente:

* `system__agent_id` - Identificador único do agente que iniciou a conversa (permanece estável durante toda a conversa)
* `system__current_agent_id` - Identificador único do agente ativo no momento (muda após transferências de agente)
* `system__caller_id` - Número de telefone de quem ligou (somente chamadas de voz)
* `system__called_number` - Número de telefone de destino (somente chamadas de voz)
* `system__call_duration_secs` - Duração da chamada em segundos
* `system__time_utc` - Hora atual em UTC (formato ISO)
* `system__time` - Hora atual no fuso horário especificado (formato legível, por exemplo, "Friday, 12:33 12 December 2025")
* `system__timezone` - Fuso horário fornecido pelo usuário (deve ser válido para tzinfo)
* `system__conversation_id` - Identificador único da conversa da ElevenLabs
* `system__call_sid` - SID da chamada (somente chamadas twilio)
* `system__call_id` - Identificador único da chamada de tronco SIP (somente chamadas de tronco SIP)
* `system__agent_turns` - Número total de turnos de conversa realizados pelo agente nesta conversa.
* `system__current_agent_turns` - Número de turnos de conversa realizados pelo agente atual. É redefinido sempre que a conversa é transferida para outro agente.
* `system__current_subagent_turns` - Número de turnos de conversa realizados pelo subagente atual. É redefinido sempre que o workflow faz a transição para outro nó.
* `system__is_text_only` - Verdadeiro se a conversa funcionar no modo somente texto; falso caso contrário.
* `system__conversation_history` - Representação serializada em JSON do histórico da conversa atual. Avaliada de forma preguiçosa no momento em que é referenciada. Veja os [detalhes do formato](#conversation-history-format) abaixo.

Variáveis do sistema:

* Estão disponíveis sem configuração em tempo de execução
* Têm o prefixo `system__` (prefixo reservado)
* São atualizadas automaticamente durante toda a conversa

> **Warning**
>
> Variáveis dinâmicas personalizadas não podem usar o prefixo reservado `system__`.

### Formato do histórico da conversa

A variável `system__conversation_history` contém um objeto JSON com a seguinte estrutura:

```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 inclui um `role` (`"user"`, `"agent"` ou `"tool"`) e um dos itens a seguir:

* `message` — o conteúdo de texto do turno
* `tool_requests` — um array de chamadas de ferramentas feitas pelo agente, com valores de parâmetros resolvidos
* `tool_results` — um array de respostas de ferramentas

Se o resultado ou um parâmetro de uma ferramenta contiver um histórico de conversa aninhado, ele será ocultado por um marcador (por exemplo, `[conversation_history (5 turns)]`) para evitar expansão recursiva ilimitada.

Essa variável é útil para transmitir o contexto da conversa a ferramentas (por exemplo, webhooks, LLMs personalizados) ou para incluir o histórico da conversa nos prompts de subagentes durante transferências.

## Variáveis dinâmicas secretas

As variáveis dinâmicas secretas são preenchidas da mesma forma que as variáveis dinâmicas normais, mas indicam aos nossos ElevenAgents que elas devem
ser usadas apenas em cabeçalhos de variáveis dinâmicas e nunca enviadas a um provedor de LLM como parte do prompt de sistema ou da primeira mensagem de um agente.

Recomendamos usá-las para tokens de autenticação ou IDs privados que não devem ser enviados a um LLM. Para criar uma variável dinâmica secreta, basta prefixar a variável dinâmica com `secret__`.

> **Warning**
>
> Os valores secretos são retornados ocultos como `<REDACTED>`, inclusive em webhooks pós-chamada e na
> API de conversas. Não use o prefixo `secret__` para valores que você precisa consultar após a
> conversa. Passe-os como variáveis dinâmicas normais ou transmita um identificador não sensível e consulte
> o valor sensível no seu próprio sistema.

## Atualizar variáveis dinâmicas por ferramentas

As [chamadas de ferramentas](https://elevenlabs.io/docs/eleven-agents/customization/tools) podem criar ou atualizar variáveis dinâmicas se retornarem um objeto JSON válido. Para especificar o que deve ser extraído, defina o(s) caminho(s) do objeto usando notação de ponto. Se o campo ou caminho não existir, nada será atualizado.

Exemplo de objeto de resposta e notação de ponto:

* Status corresponde ao caminho: `response.status`
* O e-mail do primeiro usuário no array de usuários corresponde ao caminho: `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 atualizar uma variável dinâmica com o e-mail do primeiro usuário, defina a atribuição da seguinte forma.

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

As atribuições são um campo de cada ferramenta de webhook, documentado [aqui](/docs/pt/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments).

## Guia

### Pré-requisitos

* Uma [conta da ElevenLabs](https://elevenlabs.io)
* Um agente conversacional da ElevenLabs configurado ([crie um aqui](/docs/pt/eleven-agents/quickstart))

#### Definir variáveis dinâmicas nos prompts

Adicione variáveis usando chaves duplas `{{variable_name}}` em:

* Prompts de sistema
* Primeiras mensagens
* Parâmetros de ferramentas

![Variáveis dinâmicas nas mensagens](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp)

![Variáveis dinâmicas nas mensagens](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp)

#### Definir variáveis dinâmicas nas ferramentas

Você também pode definir variáveis dinâmicas na configuração da ferramenta.
Para criar uma nova variável dinâmica, defina o tipo de valor como Dynamic variable e clique no botão `+`.

![Definir marcadores](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp)

![Definir marcadores](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp)

#### Definir marcadores

Configure valores padrão para testar sem transmitir variáveis em tempo de execução.

#### Atualizar pelo painel

Defina valores padrão para cada variável dinâmica no painel do agente.

![Definir marcadores](/docs/_fern-img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp)

#### Atualizar pela CLI

#### Baixar a configuração do agente

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

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

Defina `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders`. Cada chave é o nome da variável; o valor é o marcador usado durante os testes:

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

#### Enviar suas alterações

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

#### Atualizar pela 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",
        },
      },
    },
  },
});
```

#### Transmitir variáveis em tempo de execução

Ao iniciar uma conversa, forneça as variáveis dinâmicas no seu código:

> **Tip**
>
> Verifique se você tem o [SDK](/docs/pt/eleven-agents/libraries/python) mais recente instalado.

**`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>
```

## Integração com a página pública de conversa

A página pública de conversa é compatível com variáveis dinâmicas por meio de parâmetros de URL, permitindo personalizar conversas ao compartilhar links de agentes. Isso é especialmente útil para incorporar agentes personalizados em sites, e-mails ou campanhas de marketing.

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

Há dois métodos para transmitir variáveis dinâmicas à página pública de conversa:

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

Transmita variáveis como um objeto JSON codificado em base64 usando o parâmetro `vars`:

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

O parâmetro `vars` contém JSON codificado em base64:

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

#### Método 2: Parâmetros individuais de consulta

Transmita variáveis usando parâmetros de consulta com o prefixo `var_`:

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

### Precedência de parâmetros

Quando os dois métodos são usados simultaneamente, os parâmetros individuais `var_` têm precedência sobre as variáveis codificadas em base64 para evitar conflitos:

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

Neste exemplo, `user_name` será "John" (de `var_user_name`) em vez de "Jane" (do `vars` codificado em base64).

### Exemplos de implementação

#### Geração de URL em 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);
```

#### Geração de URL em 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)
```

#### Criação 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 compatíveis

As variáveis dinâmicas são compatíveis com estes tipos de valor:

#### String

Valores de texto

#### Number

Valores numéricos

#### Boolean

Valores verdadeiro/falso

## Solução de problemas

#### Variáveis não substituídas

Verifique se:

* Os nomes das variáveis correspondem exatamente (diferenciam maiúsculas de minúsculas)
* As variáveis usam chaves duplas: `{{ variable_name }}`
* As variáveis estão incluídas no seu objeto dynamic_variables

#### Erros de tipo

Verifique se:

* Os valores das variáveis correspondem ao tipo esperado
* Os valores são apenas strings, números ou booleanos