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

# Omgevingsvariabelen

Met omgevingsvariabelen kun je waarden per omgeving definiëren voor tool-URL's, secrets, headers en authenticatieverbindingen. Eén configuratie voor agent en tools werkt in al je omgevingen — URL's, API-sleutels en authenticatie worden dynamisch opgelost op basis van de omgeving die tijdens het gesprek is opgegeven.

## Overzicht

Zonder omgevingsvariabelen vereist het implementeren van een agent in meerdere omgevingen (development, staging, productie) dat je agents en tools voor elke omgeving dupliceert en hun configuraties vervolgens handmatig gesynchroniseerd houdt. Dit leidt tot:

* **Configuratieverschillen** tussen omgevingen
* **Versnipperde analytics** over gedupliceerde agent-ID's
* **Fricite bij promotie** bij de overgang van staging naar productie

Omgevingsvariabelen lossen dit op door een herbruikbare resource op workspace-niveau te introduceren die verschillende waarden per omgeving opslaat. Tools en MCP-servers verwijzen met templatesyntaxis naar deze variabelen en de juiste waarde wordt tijdens runtime opgelost op basis van de omgeving van het gesprek.

![Overzicht van omgevingsvariabelen](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## Kernconcepten

### Omgevingsvariabelen

Een omgevingsvariabele is een resource op workspace-niveau met een label en een set waarden per omgeving. Er zijn drie typen:

| Type                | Beschrijving                                               | Voorbeeld van gebruikssituatie                      |
| ------------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| **String**          | Platte tekstwaarden die per omgeving verschillen           | Basis-URL's, hostnamen, configuratiewaarden         |
| **Secret**          | Verwijzingen naar workspace-secrets, per omgeving opgelost | API-sleutels, bearer tokens, webhook-signingsecrets |
| **Auth connection** | Verwijzingen naar auth connections, per omgeving opgelost  | OAuth2-inloggegevens, JWT-configuraties             |

Elke omgevingsvariabele moet een waarde hebben voor de standaardomgeving `production`. Extra omgevingen (bijvoorbeeld `staging`, `development`) zijn optioneel.

### Templatesyntaxis

Verwijs in URL-velden naar omgevingsvariabelen met de syntaxis `{{system__env_<label>}}`:

```
https://{{system__env_api_host}}.example.com/v1/text-to-speech
```

Bij een omgevingsvariabele `api_host` met de waarden `api` (production) en `staging.api` (staging), wordt dit opgelost naar:

* In `production`: `https://api.example.com/v1/text-to-speech`
* In `staging`: `https://staging.api.example.com/v1/text-to-speech`

Deze syntaxis is consistent met [dynamische variabelen](/docs/nl/eleven-agents/customization/personalization/dynamic-variables) en werkt in URL-velden voor webhooktools en MCP-serververbindingen.

> **Note**
>
> Omgevingsvariabelen worden ook ondersteund in URL's en headers van **pre-call webhooks** (de
> Conversation Initiation Client Data Webhook) en in URL's van **post-call webhooks** die zijn geconfigureerd onder
> **Developers > Webhooks**. Templates worden opgelost met de omgeving van het gesprek, zodat dezelfde
> webhookconfiguratie verschillende endpoints per omgeving kan targeten. Voor pre-call webhooks kan de
> omgeving vooraf worden ingesteld op het telefoonnummer, of dynamisch worden teruggegeven in je webhook-
> respons (zie [Telephony](#telephony-twilio-and-sip-trunk) hieronder).

> **Note**
>
> URL's moeten beginnen met `https://` vóór verwijzingen naar omgevingsvariabelen. Bijvoorbeeld: `https://   {{ system__env_api_host }}.example.com/v1/data` is geldig, maar `{{ system__env_api_host }}/v1/data`
> niet. Dit is vereist voor validatie en beveiliging — waarden van omgevingsvariabelen kunnen het
> protocol niet bepalen.

### Oplossing en fallback

Wanneer een gesprek in een specifieke omgeving plaatsvindt, lost het systeem omgevingsvariabelen als volgt op:

1. Zoek de waarde voor de aangevraagde omgeving op (bijvoorbeeld `staging`)
2. Als er geen waarde voor die omgeving bestaat, **val dan terug op de waarde voor `production`**
3. Als de variabele niet kan worden opgelost, mislukt de toolcall met een configuratiefout

Dit fallbackgedrag betekent dat je alleen waarden hoeft te definiëren voor omgevingen die afwijken van productie.

## Omgevingsvariabelen maken

> **Note**
>
> Omgevingsvariabelen kunnen nog niet worden beheerd via de ElevenLabs CLI — gebruik het dashboard of de SDK.

#### Maken via het dashboard

Ga in het ElevenLabs-dashboard naar **Developers > Environment Variables**.

#### Een omgeving maken

Definieer omgevingen die overeenkomen met je implementatiefasen (bijvoorbeeld `eu`, `india`, `staging`). De omgeving `production` is standaard altijd beschikbaar.

#### Een variabele maken

Klik op **Add variable** en kies het type variabele:

* **String**: Voer een label in en stel een waarde in voor elke omgeving
* **Secret**: Selecteer voor elke omgeving een bestaand workspace-secret
* **Auth connection**: Selecteer voor elke omgeving een bestaande auth connection

![Variabele maken](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Maken via de API

#### String

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="api_host",
    type="string",
    values={
        "production": "api",
        "staging": "staging.api",
        "development": "dev.api",
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "api_host",
  type: "string",
  values: {
    production: "api",
    staging: "staging.api",
    development: "dev.api",
  },
});
```

#### Secret

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_api_key",
    type="secret",
    values={
        "production": {"secret_id": "your-production-secret-id"},
        "staging": {"secret_id": "your-staging-secret-id"},
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_api_key",
  type: "secret",
  values: {
    production: { secretId: "your-production-secret-id" },
    staging: { secretId: "your-staging-secret-id" },
  },
});
```

#### Auth connection

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_oauth_connection",
    type="auth_connection",
    values={
        "production": {"auth_connection_id": "your-production-auth-connection-id"},
        "staging": {"auth_connection_id": "your-staging-auth-connection-id"},
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_oauth_connection",
  type: "auth_connection",
  values: {
    production: { authConnectionId: "your-production-auth-connection-id" },
    staging: { authConnectionId: "your-staging-auth-connection-id" },
  },
});
```

## Omgevingsvariabelen gebruiken

### In URL's van webhooktools

Gebruik de templatesyntaxis in het URL-veld van een [webhooktool](/docs/nl/eleven-agents/customization/tools/webhook-tools) om de basis-URL per omgeving te laten oplossen.

![Omgevingsvariabele in tool-URL](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

Een tool-URL die bijvoorbeeld als volgt is geconfigureerd:

```
https://{{system__env_api_host}}.example.com/v1/weather?lat={latitude}&lon={longitude}
```

wordt in productie omgezet naar `https://api.example.com/v1/weather?lat=40.7&lon=-74.0` en in staging naar `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0`.

Je kunt meerdere omgevingsvariabelen en letterlijke segmenten combineren in één URL:

```
https://{{system__env_api_host}}.example.com/{{system__env_api_version}}/weather
```

#### API-voorbeeld

**`Python`**

```python title="Python"

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

agent = client.conversational_ai.agents.create(
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "prompt": {"prompt": "You are a helpful assistant."},
        },
        "tools": [
            {
                "type": "webhook",
                "name": "get_data",
                "description": "Fetches data from the API",
                "api_schema": {
                    "url": "https://{{system__env_api_host}}.example.com/v1/data",
                    "method": "GET",
                },
            }
        ],
    },
)
```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      prompt: { prompt: "You are a helpful assistant." },
    },
    tools: [
      {
        type: "webhook",
        name: "get_data",
        description: "Fetches data from the API",
        apiSchema: {
          url: "https://{{system__env_api_host}}.example.com/v1/data",
          method: "GET",
        },
      },
    ],
  },
});
```

### In headers van webhooktools

Geheime omgevingsvariabelen kunnen in requestheaders worden gebruikt. Verwijs in plaats van een geheime ID hard te coderen naar een omgevingsvariabele, zodat per omgeving verschillende geheimen worden gebruikt. Selecteer bij het configureren van een toolheader in het dashboard een omgevingsvariabele in plaats van een statisch geheim. Tijdens runtime wordt de headerwaarde omgezet naar het geheim dat voor de huidige omgeving is opgeslagen.

#### API-voorbeeld

Geef een verwijzing naar een omgevingsvariabele door in het veld `request_headers`:

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "request_headers": {
      "X-Api-Key": { "env_var_label": "my_api_key" }
    }
  }
}
```

### In authverbindingen van webhooktools

Authverbindingen (OAuth2, JWT, Basic Auth) kunnen ook per omgeving worden omgezet. Dit is handig wanneer je staging- en productieomgevingen verschillende OAuth-clients of tokenendpoints gebruiken.

![Authverbinding voor omgevingsvariabele](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

Selecteer in de toolconfiguratie een omgevingsvariabele van het type `auth_connection` in plaats van rechtstreeks een authverbinding te selecteren. Tijdens runtime wordt de juiste authverbinding voor de huidige omgeving omgezet.

#### API-voorbeeld

Verwijs naar een omgevingsvariabele in het veld `auth_connection`:

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "auth_connection": { "env_var_label": "my_oauth_connection" }
  }
}
```

### In MCP-serververbindingen

Omgevingsvariabelen werken met verbindingen van [MCP-servers](/docs/nl/eleven-agents/customization/tools/mcp) op dezelfde manier als met webhooktools. Je kunt ze gebruiken in:

* **Server-URL**: Gebruik een template voor de MCP-server-URL om per omgeving naar verschillende servers te verwijzen
* **Requestheaders**: Gebruik geheime omgevingsvariabelen voor authenticatieheaders
* **Authverbindingen**: Gebruik omgevingsvariabelen voor authverbindingen voor OAuth-gebaseerde MCP-servers

Een MCP-server-URL die bijvoorbeeld als volgt is geconfigureerd:

```
https://{{system__env_mcp_host}}.example.com/mcp
```

wordt afhankelijk van de omgeving omgezet naar verschillende MCP-serverendpoints.

### In aangepaste LLM-configuraties

Wanneer je een [aangepaste LLM](/docs/nl/eleven-agents/customization/llm/custom-llm) gebruikt, kunnen omgevingsvariabelen een template bieden voor de API-sleutel en requestheaders. Zo kun je verschillende modelendpoints en inloggegevens gebruiken in verschillende omgevingen.

Het URL-veld voor de aangepaste LLM ondersteunt dezelfde templatesyntaxis `{{system__env_<label>}}`. Het veld `api_key` accepteert een verwijzing naar een omgevingsvariabele, zodat per omgeving verschillende API-sleutels worden gebruikt.

#### API-voorbeeld

```json
{
  "conversation_config": {
    "agent": {
      "prompt": { "prompt": "You are a helpful assistant." },
      "llm": {
        "custom_llm": {
          "url": "https://{{system__env_llm_host}}.example.com/v1/chat/completions",
          "model_id": "my-model",
          "api_key": { "env_var_label": "llm_api_key" }
        }
      }
    }
  }
}
```

## De omgeving opgeven

De omgeving wordt ingesteld bij het starten van een gesprek en blijft gedurende het hele gesprek behouden. Als er geen omgeving is opgegeven, is de standaardwaarde `production`.

Selecteer bij het testen in het dashboard de omgeving in de dropdown in het agentvoorbeeld:

![Omgevingskiezer in agentvoorbeeld
](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

Geef de queryparameter `environment` door wanneer je verbinding maakt met de WebSocket voor gesprekken:

```
wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<agent_id>&environment=staging
```

### WebRTC (ondertekende URL / token)

Geef bij gebruik van WebRTC de parameter `environment` door wanneer je een gesprekstoken aanvraagt:

**`Python`**

```python title="Python"
from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

token = client.conversational_ai.conversation.get_token(
agent_id="your-agent-id",
environment="staging",
)

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const token = await client.conversationalAi.conversation.getToken({
    agentId: "your-agent-id",
    environment: "staging",
});
```

**`cURL`**

```bash title="cURL"
curl "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=<agent_id>&environment=staging" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

### Telefonie (Twilio en SIP-trunk)

Telefoonnummers kunnen worden vastgezet op een specifieke omgeving en een specifieke [agentbranch](/docs/nl/eleven-agents/operate/versioning), zodat je een testtelefoonnummer eenvoudig kunt doorsturen naar een dev-branch van een agent waarvan de tools op een dev-API worden uitgevoerd.

![Omgevings- en branchkiezers voor
telefoonnummers](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

Voor inkomende gesprekken wordt de omgeving in deze volgorde omgezet:

1. De waarde `environment` die wordt teruggestuurd door je [webhook voor gespreksinitiatie](/docs/nl/eleven-agents/customization/personalization#conversation-initiation-webhooks), als je server er dynamisch één per gesprek levert
2. De omgeving die op het **telefoonnummer** zelf is opgeslagen
3. `production` als standaard

Dezelfde prioriteit geldt voor `branch_id`. URL's en headers van webhooks vóór het gesprek, en URL's van webhooks na het gesprek, zetten vervolgens de templates `{{system__env_*}}` om met de gekozen omgeving.

Zet een telefoonnummer vast op een omgeving en branch (vereist `elevenlabs` Python SDK ≥ 2.47.0 of `@elevenlabs/elevenlabs-js` ≥ 2.47.0):

**`Python`**

```python title="Python"
import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs

load_dotenv()

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

elevenlabs.conversational_ai.phone_numbers.update(
    phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj",
    environment="staging",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
)
```

**`JavaScript`**

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  environment: "staging",
  branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
  }'
```

Geef voor uitgaande gesprekken het veld `environment` door wanneer je het gesprek start via de uitgaande endpoints voor Twilio of SIP-trunk.

### React SDK

Geef de optie `environment` door in de hook `useConversation` of wanneer je een sessie start:

```tsx
import { useConversation } from "@11labs/react";

function Agent() {
  const conversation = useConversation();

  const connect = async () => {
    await conversation.startSession({
      agentId: "your-agent-id",
      environment: "staging",
    });
  };

  return <button onClick={connect}>Start conversation</button>;
}
```

## Voorbeeld: agent voor meerdere omgevingen

Dit voorbeeld toont een volledige configuratie met één agent die verschillende API-backends en inloggegevens gebruikt voor ontwikkeling, staging en productie.

#### Omgevingsvariabelen maken

Maak drie omgevingsvariabelen in het dashboard of via de API:

| Label         | Type           | Ontwikkeling    | Staging             | Productie        |
| ------------- | -------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | String         | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Geheim         | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Authverbinding | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Tools configureren met verwijzingen naar omgevingsvariabelen

Stel je webhooktools in met templatesyntaxis:

* **URL**: `https://{{system__env_api_host}}.example.com/v1/orders`
* **Headers**: Verwijs naar de omgevingsvariabele `api_key` voor de header `X-Api-Key`
* **Auth**: Verwijs naar de omgevingsvariabele `oauth_creds` voor OAuth-authenticatie

#### Omgeving opgeven bij het starten van een gesprek

Geef bij het starten van een gesprek de doelomgeving door:

**`Ontwikkeling`**

```python title="Ontwikkeling"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="development",
)
```

**`Staging`**

```python title="Staging"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)
```

**`Productie (standaard)`**

```python title="Productie (standaard)"
# No environment parameter needed — defaults to production
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
)
```

#### Filteren op omgeving

De omgeving wordt bijgehouden voor elk gesprek. Filter je analysedashboards en gespreksgeschiedenis op omgeving om statistieken per implementatiefase te onderscheiden.

![Analyse filteren op omgeving](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Gespreksgeschiedenis filteren op omgeving](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### Naamgevingsbeperkingen

* **Labels**: Alleen alfanumerieke tekens en underscores (bijv. `base_url`, `api_key_v2`)
* **Omgevingsnamen**: Moeten met een kleine letter beginnen en mogen alleen kleine letters, cijfers, underscores en koppeltekens bevatten, met een maximum van 64 tekens (bijv. `production`, `staging`, `dev-us-east`)
* Elke omgevingsvariabele moet een waarde voor `production` hebben

## Volgende stappen

#### [Webhooktools](/docs/nl/eleven-agents/customization/tools/webhook-tools)

Configureer webhooktools met omgevingsbewuste URL's en authenticatie

#### [MCP-servers](/docs/nl/eleven-agents/customization/tools/mcp)

Verbind MCP-servers met configuratie per omgeving

#### [Aangepaste LLM](/docs/nl/eleven-agents/customization/llm/custom-llm)

Gebruik verschillende modelendpoints in verschillende omgevingen

#### [Versiebeheer](/docs/nl/eleven-agents/operate/versioning)

Combineer omgevingsvariabelen met branches en verkeerssplitsing