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

# Dynamische variabelen

**Dynamische variabelen** stellen je in staat runtimewaarden in de berichten, systeemprompts en tools van je agent in te voegen. Hiermee kun je elk gesprek personaliseren met gebruikersspecifieke gegevens zonder meerdere agents te maken.

## Overzicht

Dynamische variabelen kunnen worden geïntegreerd in verschillende onderdelen van je agent:

* **Systeemprompts** om gedrag en context aan te passen
* **Eerste berichten** om begroetingen te personaliseren
* **Toolparameters en headers** om gebruikersspecifieke gegevens door te geven

Hier zijn enkele voorbeelden waarin dynamische variabelen nuttig zijn:

* **Begroetingen personaliseren** met gebruikersnamen
* **Accountgegevens opnemen** in antwoorden
* **Gegevens doorgeven** aan tool calls
* **Gedrag aanpassen** op basis van abonnementsniveaus
* **Systeemgegevens raadplegen** zoals gespreks-ID of gespreksduur

> **Info**
>
> Dynamische variabelen zijn ideaal voor het invoegen van gebruikersspecifieke gegevens die je niet hardcoded in de
> configuratie van je agent wilt opnemen.

## Dynamische systeemvariabelen

Je agent heeft toegang tot deze automatisch beschikbare systeemvariabelen:

* `system__agent_id` - Unieke identificatiecode van de agent die het gesprek heeft gestart (blijft gedurende het hele gesprek hetzelfde)
* `system__current_agent_id` - Unieke identificatiecode van de momenteel actieve agent (wijzigt na agenttransfers)
* `system__caller_id` - Telefoonnummer van de beller (alleen spraakoproepen)
* `system__called_number` - Telefoonnummer van de bestemming (alleen spraakoproepen)
* `system__call_duration_secs` - Gespreksduur in seconden
* `system__time_utc` - Huidige UTC-tijd (ISO-indeling)
* `system__time` - Huidige tijd in de opgegeven tijdzone (leesbare indeling, bijvoorbeeld "vrijdag, 12:33 12 december 2025")
* `system__timezone` - Door de gebruiker opgegeven tijdzone (moet geldig zijn voor tzinfo)
* `system__conversation_id` - Unieke gespreksidentificatiecode van ElevenLabs
* `system__call_sid` - Call SID (alleen Twilio-oproepen)
* `system__call_id` - Unieke identificatiecode voor de SIP-trunkoproep (alleen SIP-trunkoproepen)
* `system__agent_turns` - Het totale aantal gespreksbeurten dat de agent tijdens dit gesprek heeft gehad.
* `system__current_agent_turns` - Het aantal gespreksbeurten dat de huidige agent heeft gehad. Wordt gereset wanneer het gesprek naar een andere agent wordt overgedragen.
* `system__current_subagent_turns` - Het aantal gespreksbeurten dat de huidige subagent heeft gehad. Wordt gereset wanneer de workflow naar een andere node overgaat.
* `system__is_text_only` - True als het gesprek alleen in tekstmodus plaatsvindt, anders false.
* `system__conversation_history` - JSON-geserialiseerde weergave van de huidige gespreksgeschiedenis. Wordt pas geëvalueerd op het moment dat ernaar wordt verwezen. Zie hieronder de [indelingsdetails](#conversation-history-format).

Systeemvariabelen:

* Zijn beschikbaar zonder runtimeconfiguratie
* Hebben het voorvoegsel `system__` (gereserveerd voorvoegsel)
* Worden tijdens het gesprek automatisch bijgewerkt

> **Warning**
>
> Aangepaste dynamische variabelen kunnen niet het gereserveerde voorvoegsel `system__` gebruiken.

### Indeling van de gespreksgeschiedenis

De variabele `system__conversation_history` bevat een JSON-object met de volgende structuur:

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

Elke invoer bevat een `role` (`"user"`, `"agent"` of `"tool"`) en een van de volgende:

* `message` — de tekstinhoud van de beurt
* `tool_requests` — een array met tool calls die de agent heeft gedaan, met opgeloste parameterwaarden
* `tool_results` — een array met toolantwoorden

Als een toolresultaat of parameter een geneste gespreksgeschiedenis bevat, wordt deze geredigeerd tot een placeholder (bijvoorbeeld `[conversation_history (5 turns)]`) om onbegrensde recursieve uitbreiding te voorkomen.

Deze variabele is nuttig om gesprekscontext door te geven aan tools (bijvoorbeeld webhooks, aangepaste LLM's) of om tijdens overdrachten gespreksgeschiedenis op te nemen in prompts voor subagents.

## Geheime dynamische variabelen

Geheime dynamische variabelen worden op dezelfde manier ingevuld als gewone dynamische variabelen, maar geven aan onze ElevenAgents aan dat deze
alleen in headers voor dynamische variabelen mogen worden gebruikt en nooit als onderdeel van de systeemprompt of het eerste bericht van een agent naar een LLM-provider mogen worden gestuurd.

We raden aan deze te gebruiken voor authenticatietokens of privé-ID's die niet naar een LLM mogen worden gestuurd. Om een geheime dynamische variabele te maken, geef je de dynamische variabele eenvoudig het voorvoegsel `secret__`.

> **Warning**
>
> Geheime waarden worden geredigeerd teruggegeven als `<REDACTED>`, ook in webhooks na gesprekken en de
> conversations API. Gebruik het voorvoegsel `secret__` niet voor waarden die je na het
> gesprek moet kunnen uitlezen. Geef die door als gewone dynamische variabelen of geef een niet-gevoelige identificatiecode door en zoek
> de gevoelige waarde op in je eigen systeem.

## Dynamische variabelen bijwerken vanuit tools

[Tool calls](https://elevenlabs.io/docs/eleven-agents/customization/tools) kunnen dynamische variabelen maken of bijwerken als ze een geldig JSON-object retourneren. Geef met puntnotatie de objectpaden op die moeten worden geëxtraheerd. Als het veld of pad niet bestaat, wordt er niets bijgewerkt.

Voorbeeld van een response-object en puntnotatie:

* Status komt overeen met het pad: `response.status`
* Het e-mailadres van de eerste gebruiker in de users-array komt overeen met het pad: `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"
      }
    ]
  }
}
```

Om een dynamische variabele bij te werken naar het e-mailadres van de eerste gebruiker, stel je de toewijzing als volgt in.

![Queryparameters](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp)

Toewijzingen zijn een veld van elke webhooktool, zoals [hier](/docs/nl/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments) gedocumenteerd.

## Handleiding

### Vereisten

* Een [ElevenLabs-account](https://elevenlabs.io)
* Een geconfigureerde ElevenLabs Conversational Agent ([maak er hier een](/docs/nl/eleven-agents/quickstart))

#### Dynamische variabelen in prompts definiëren

Voeg variabelen met dubbele accolades `{{variable_name}}` toe aan je:

* Systeemprompts
* Eerste berichten
* Toolparameters

![Dynamische variabelen in berichten](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp)

![Dynamische variabelen in berichten](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp)

#### Dynamische variabelen in tools definiëren

Je kunt dynamische variabelen ook in de toolconfiguratie definiëren.
Om een nieuwe dynamische variabele te maken, stel je het waardetype in op Dynamic variable en klik je op de knop `+`.

![Placeholders instellen](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp)

![Placeholders instellen](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp)

#### Placeholders instellen

Configureer standaardwaarden om te testen zonder variabelen tijdens runtime door te geven.

#### Bijwerken via het dashboard

Stel standaardwaarden in voor elke dynamische variabele in het dashboard van de agent.

![Placeholders instellen](/docs/_fern-img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp)

#### Bijwerken via de CLI

#### De agentconfiguratie ophalen

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

#### \`agent\_configs/\<agent-name>.json\` bewerken

Stel `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders` in. Elke sleutel is de variabelenaam; de waarde is de placeholder die tijdens het testen wordt gebruikt:

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

#### Je wijzigingen pushen

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

#### Bijwerken via de 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",
        },
      },
    },
  },
});
```

#### Variabelen tijdens runtime doorgeven

Geef de dynamische variabelen in je code op wanneer je een gesprek start:

> **Tip**
>
> Zorg dat je de nieuwste [SDK](/docs/nl/eleven-agents/libraries/python) hebt geïnstalleerd.

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

## Integratie met openbare Talk-to-pagina

De openbare Talk-to-pagina ondersteunt dynamische variabelen via URL-parameters, zodat je gesprekken kunt personaliseren wanneer je agentlinks deelt. Dit is vooral nuttig om gepersonaliseerde agents in websites, e-mails of marketingcampagnes in te sluiten.

### Methoden voor URL-parameters

Er zijn twee methoden om dynamische variabelen door te geven aan de openbare Talk-to-pagina:

#### Methode 1: Base64-gecodeerde JSON

Geef variabelen door als een base64-gecodeerd JSON-object met de parameter `vars`:

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

De parameter `vars` bevat base64-gecodeerde JSON:

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

#### Methode 2: Afzonderlijke queryparameters

Geef variabelen door met queryparameters met het voorvoegsel `var_`:

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

### Parameterprioriteit

Wanneer beide methoden tegelijkertijd worden gebruikt, krijgen afzonderlijke `var_`-parameters voorrang boven de base64-gecodeerde variabelen om conflicten te voorkomen:

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

In dit voorbeeld is `user_name` "John" (van `var_user_name`) in plaats van "Jane" (van de base64-gecodeerde `vars`).

### Implementatievoorbeelden

#### JavaScript-URL genereren

```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);
```

#### Python-URL genereren

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

#### URL handmatig samenstellen

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

## Ondersteunde typen

Dynamische variabelen ondersteunen deze waardetypen:

#### String

Tekstwaarden

#### Number

Numerieke waarden

#### Boolean

True/false-waarden

## Problemen oplossen

#### Variabelen worden niet vervangen

Controleer het volgende:

* Variabelenamen komen exact overeen (hoofdlettergevoelig)
* Variabelen gebruiken dubbele accolades: `{{ variable_name }}`
* Variabelen zijn opgenomen in je object dynamic\_variables

#### Typefouten

Zorg dat:

* Variabelewaarden overeenkomen met het verwachte type
* Waarden alleen strings, getallen of booleans zijn