Copy page

Core Concepts

Template Variables

Template variables let you personalise every call without maintaining separate agent configurations. Variables in double curly braces ({{variable_name}}) are resolved at runtime against three layered sources:

1. System variables — auto-injected by the platform on every call. Reserved system__* namespace; you cannot supply these.
2. Agent variables — defaults defined on the agent itself in Agent Studio. Apply to every call this agent handles.
3. Dynamic variables — per-call values supplied at dial time (outbound) or via the inbound webhook (inbound). Override agent variables when both define the same name.

Resolution order at render time: dynamic > agent > system. If a {{name}} placeholder isn't found in any layer, the worker emits a structured warning to the call log and renders the literal placeholder.

Syntax

Code
{{variable_name}}

Works in: brain.instructions, first_message.text, timeout.warning_messages, transfer.destinations[].description, and any tool input that the agent passes to a function-call.

System Variables

Auto-injected by the platform — never pass these in dynamic_variables. The full catalog (21 entries) lives in shared_schemas/system_variables.py; the docs site mirrors it below.

The Available on column lists the channels each variable is populated on. Reading a variable on a channel where it's not available renders empty.

Variable	Available on	What it is
{{system__agent_id}}	all	UUID of the agent that started the conversation. Stable across handoffs.
{{system__current_agent_id}}	all	UUID of the currently active agent. Changes after handoffs.
{{system__agent_name}}	all	Display name of the current agent.
{{system__org_name}}	all	Display name of the organisation.
{{system__org_id}}	all	UUID of the organisation.
{{system__caller_id}}	phone, whatsapp_chat, whatsapp_voice, sms	Contact's phone number / WhatsApp ID in E.164.
{{system__called_number}}	all	The number that received or placed the call.
{{system__direction}}	all	"inbound" or "outbound".
{{system__channel}}	all	One of webrtc, phone, whatsapp_chat, whatsapp_voice, sms.
{{system__is_text_only}}	all	"true" on text channels, "false" on voice. Useful when one agent serves both modes.
{{system__time}}	all	Local time, human-readable (e.g. "Friday, 12:33 12 December 2025").
{{system__time_utc}}	all	UTC time in ISO 8601.
{{system__date}}	all	Local date in YYYY-MM-DD.
{{system__day}}	all	Local day of week (e.g. "Tuesday").
{{system__timezone}}	all	Agent's IANA timezone (e.g. "America/New_York").
{{system__conversation_id}}	all	UUID for this conversation thread.
{{system__call_sid}}	phone, whatsapp_voice	Provider-side call identifier — useful for correlating with carrier logs.
{{system__call_duration_secs}}	webrtc, phone, whatsapp_voice	Live counter — seconds elapsed since the call connected.
{{system__agent_turns}}	all	Number of turns the agent has taken so far in this call.
{{system__country_iso2}}	phone, whatsapp_chat, whatsapp_voice, sms	ISO 3166-1 alpha-2 country code derived from caller phone.
{{system__caller_region}}	phone, whatsapp_chat, whatsapp_voice, sms	Subnational region (state/province code) from caller phone, when available.

You can fetch the live catalog programmatically via the Python / Node SDK (client.types) or via the MCP tool get_system_variables_catalog.

Agent Variables

Defaults defined on the agent in Agent Studio (Conversation tab → Variables). Useful when the same value is needed on every call this agent handles — {{company_name}}, {{support_email}}, {{return_window_days}}. They're rendered into the prompt before each turn.

Override them on individual calls by passing the same name in dynamic_variables.

Dynamic Variables

Custom data passed at call dispatch time (outbound), via inbound webhook (inbound), or via tool returns (mid-call):

Code
{
  "agent_id": "agent_abc123",
  "to_number": "+14155551234",
  "dynamic_variables": {
    "customer_name": "Sarah",
    "account_tier": "Enterprise",
    "renewal_date": "May 15"
  }
}

Reference in instructions: {{customer_name}}, {{account_tier}}, {{renewal_date}}.

Example: Personalized Outbound Call

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",
      "renewal_date": "May 15",
      "plan": "Enterprise"
    }
  }'

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",
            "renewal_date": "May 15",
            "plan": "Enterprise"
        }
    }
)

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", renewal_date: "May 15", plan: "Enterprise" }
  })
});

With agent instructions: "You are calling {{customer_name}} about their {{plan}} plan renewal on {{renewal_date}}."

Preview Resolution

Test variable resolution before deploying using the Test panel in Agent Studio. Simulate a call with sample variables and verify all {{placeholder}} values resolve correctly. Unresolved variables appear highlighted.

Related

• Dynamic Variables Guide — outbound dispatch examples
• Inbound Variable Injection — webhook-driven variable population for inbound calls
• Tool Variable Writes — let function-calling tools mutate variables mid-conversation
• Outbound Campaigns — contact variables in campaigns
• Conversations — variables persist on the conversation thread across calls