Dynamic variables

Dynamic variables are per-call string key/value pairs that let you personalise a single call without editing the shared agent. You set them when the call is created; the platform substitutes them into the agent's governing prompt at call start and exposes them to the agent's tools. They are the recommended way to inject per-call context (caller name, business name, account details, a call_action, etc.) into an otherwise-static agent that serves many concurrent calls.

1. Setting them at call creation

Pass a dynamic_variables object (string → string) on any call-creation request:

POST /v1/sip/calls/outbound
POST /v1/sip/calls/inbound
POST /v1/sip/calls/browser

json

POST /v1/sip/calls/outbound
{
  "agent_id": "…",
  "from_number": "+44…",
  "destination_number": "+44…",
  "dynamic_variables": {
    "business_name": "Acme Plumbing",
    "customer_name": "Ada",
    "call_action": "answer"
  }
}

Values MUST be strings. The sibling metadata field on the same requests is different: metadata is opaque JSON persisted to the call row and echoed on lifecycle webhook events — it is not substituted into the prompt.

If a per-tenant pre-connect admission hook is configured, its response may also return dynamic_variables, which are merged into the call's variable set before the room is created.

2. Substitution into the agent prompt

At call start, the pipeline resolves {{varName}} placeholders in the agent's governing prompt against the call's dynamic-variable set, then sends the resolved prompt to the model. For example, an agent prompt containing:

You are the receptionist for {{business_name}}. The caller is {{customer_name}}.

is spoken/reasoned against You are the receptionist for Acme Plumbing. The caller is Ada. for that call only. A placeholder with no matching variable is left intact (e.g. {{unknown}} stays literally {{unknown}}) — it never errors the call. Names match [a-zA-Z0-9_].

3. Availability to tools

The same variable set is available to the agent's function-calling tools in two ways:

{{varName}} templating in a ToolConfig's url, header value, and const-mode query parameters is resolved from the dynamic-variable store before each tool dispatch.
The call.vars snapshot in the tool-dispatch request envelope (see the Tool dispatch guide) carries the current dynamic-variable map, so the tool endpoint can read every variable in scope.

4. Extending the store mid-call (tool responses)

A tool can write new variables back into the store: ToolConfig.ResponseVars maps JSON dot-paths in the tool's response body to variable names, and the extracted scalar values (string/number/bool leaves) become dynamic variables available to subsequent {{varName}} substitutions and tool calls. This is how a mid-call lookup (e.g. an availability check) feeds later turns.

Lifecycle summary

create call (dynamic_variables) ─┐
  (+ admission-hook variables)   ├─▶ resolve {{var}} into the governing prompt at call start
                                 │
                                 ├─▶ tools: {{var}} in url/headers/query + call.vars snapshot
                                 │
tool response (ResponseVars) ────┴─▶ write new vars into the store for later turns

Notes: values are strings; unresolved placeholders are preserved verbatim; the set is scoped to the single call and is never shared across a tenant's concurrent calls.