Copy page

Guides

Dynamic Variables

Dynamic variables are per-call values you supply to personalise every conversation. They're one of three layers the platform renders agent prompts against — see Template Variables for the full catalog of system__* variables and the resolution order.

This guide covers the three places dynamic variables can come from:

1. Outbound dispatch: passed in the voice_sessions.outbound request body
2. Inbound webhook: returned from your inbound webhook on every incoming call (see Inbound Variable Injection)
3. Tool returns: written by function-calling tools mid-call (see Tool Variable Writes)

Syntax

Wrap variable names in double curly braces:

Code
{{variable_name}}

Variables can appear in: brain.instructions, first_message.text, timeout.warning_messages, transfer destination descriptions, and any tool input the agent passes to a function-call.

Reserved namespace

Names starting with system__ are reserved for the platform — passing them in dynamic_variables is rejected with a structured warning. Use the catalog values listed in Template Variables → System Variables by reference; never set them yourself.

Passing Dynamic Variables on Outbound Calls

Include dynamic_variables in your outbound call request:

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/outbound \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "to_number": "+14155551234",
    "dynamic_variables": {
      "customer_name": "Sarah",
      "account_number": "ACC-9981",
      "balance_due": "$127.50",
      "due_date": "April 15"
    }
  }'

Code
import httpx

httpx.post(
    "https://api.neuratel.ai/v1/voice-sessions/outbound",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
    json={
        "agent_id": "agent_abc123",
        "to_number": "+14155551234",
        "dynamic_variables": {
            "customer_name": "Sarah",
            "account_number": "ACC-9981",
            "balance_due": "$127.50",
            "due_date": "April 15"
        }
    }
)

Code
await fetch("https://api.neuratel.ai/v1/voice-sessions/outbound", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    to_number: "+14155551234",
    dynamic_variables: {
      customer_name: "Sarah",
      account_number: "ACC-9981",
      balance_due: "$127.50",
      due_date: "April 15"
    }
  })
});

Agent Configuration with Variables

Configure your agent's instructions to use the variables:

Code
{
  "name": "Collections Agent",
  "brain": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "instructions": "You are calling {{customer_name}} from Acme Corp collections. Account {{account_number}} has a balance of {{balance_due}} due on {{due_date}}. Your goal is to arrange payment. Be professional and empathetic."
  },
  "conversation": {
    "first_message": {
      "enabled": true,
      "text": "Hello, may I speak with {{customer_name}}?"
    }
  }
}

Variables in Campaigns

When running campaigns, contact variables are automatically injected from each contact's record. Define custom fields on your contacts to pass additional data:

Code
{
  "phone_number": "+14155551234",
  "first_name": "Sarah",
  "company": "Acme Corp",
  "dynamic_variables": {
    "product": "Enterprise Plan",
    "renewal_date": "May 1",
    "discount": "20%"
  }
}

The agent's instructions can then reference: {{contact.first_name}}, {{contact.company}}, {{product}}, {{renewal_date}}, {{discount}}.

Preview Variable Resolution

Before running a campaign, test your template resolves correctly. In the dashboard:

1. Go to the agent's Brain tab in Agent Studio
2. Use the Test panel to simulate a call with sample variables
3. Check that all {{variable}} placeholders resolve as expected

Unresolved variables appear highlighted so you can catch typos before going live.

Related

• Template Variables — full system variable catalog + agent vs dynamic vs system layers
• Inbound Variable Injection — webhook-driven population for inbound calls
• Tool Variable Writes — let function-calling tools mutate variables mid-call
• Outbound Campaigns — variables in bulk dialing
• Per-Call Config Override — combine variables with agent_override
• Agents — configure the prompt template