Concepts

Variables

Personalize prompts and tool configs per session without duplicating agents

Dynamic variables are named placeholders in an agent’s prompt, first message, and webhook tool configs. You supply concrete values at session start, so one agent definition serves many customers, tenants, or contexts — you change the values, not the agent.

To set them up, see Add variables.

Types

TypeSemantics
stringPlain text, interpolated verbatim with {{key}}.
numberNumeric, rendered as its decimal form.
booleantrue or false.
jsonAny valid JSON value. Use {{key|json}} to inject safely inside JSON tool bodies.

Interpolation

Reference a variable with double braces in the prompt, first message, or webhook tool config (URL, headers, body):

  • {{key}} — plain interpolation. Numbers and booleans are stringified; json values render as their JSON text.
  • {{key|json}} — JSON-encoded. The value is serialized (quoted and escaped), so it’s safe inside a JSON body.

Inside a JSON tool body, always use the |json form. Without it, a value like alice"malicious breaks the surrounding JSON:

1{ "customer_email": "{{customer_email}}" }    // → "alice"malicious"   ✗ broken
2{ "customer_email": {{customer_email|json}} }  // → "alice\"malicious"  ✓ safe

Reserved system variables

The platform populates these at session start. You can’t define or override them — any key starting with system__ is rejected.

KeyDescription
system__caller_idThe caller for this session. Empty for anonymous widget sessions.
system__called_numberDestination number for inbound SIP calls. Empty otherwise.
system__languageBCP-47 language code from the agent config.
system__agent_idThe agent driving this session.
system__conversation_idThe current conversation.
system__current_timeServer-side UTC timestamp at session start (ISO 8601).
system__memoryThe rendered memory block (empty when memory is off or the caller is anonymous).

GET /v1/agents/{id}/variables returns system_variables — the same catalog — so an editor UI can list them without hard-coding.

Precedence

When the platform resolves a variable at session start, later sources win:

  1. Agent default — the default on the variable definition.
  2. Session override — values in dynamic_variables on the conversation or session create call.
  3. Reserved system__* — platform values always win and can’t be shadowed.

Limits

ConstraintValue
Max variables per agent20
Key pattern[a-zA-Z0-9_]+
Reserved prefixsystem__ (rejected in the catalog and in overrides)
Missing variableRenders as an empty string — never an error

A typo in a template reference never breaks dispatch — the token resolves to an empty string. Use GET /v1/agents/{id}/variables to confirm the keys your prompt references exist.

Coming soon: tool-response assignment will let a variable update mid-call from data a tool returns, accumulating context across turns.