customer_name as Jordan, the agent says “Hi Jordan, how can I help you today?”
Custom values come from your call request or a webhook tool response. Cartesia provides system variables, such as {{system__caller_id}}, automatically.
Where values can be inserted
Where values can be inserted
Where values come from
Values you supply
Passdynamic_variables in your outbound call request. Use the agent with the initial message above, along with your own phone number ID and destination:
POST /agents/calls
dynamic_variables. For browser WebSocket calls, include them in the server-side create WebSocket session request before the browser connects.
Values can be text, numbers, or true/false values.
System variables
Cartesia provides call context automatically. For example,system__caller_id contains the caller’s phone number, and system__time contains the current local time:
config.timezone; it defaults to UTC.
Available system variables
Available system variables
Phone numbers and call direction are empty when unavailable, including in browser previews. Time values update during the call.
Tool responses
A webhook tool can save values from its response for the rest of the call. Add an assignment to choose which response field to save and which variable to update. Suppose an order lookup returns:
After the lookup succeeds,
{{order_status}} becomes shipped in instructions and tool descriptions. Other webhook tools can use order_id as a parameter value.
For inbound calls, start with an initial message that works before you know the caller, such as “Thanks for calling. How can I help?” In your lookup tool, set the phone-number parameter to use system__caller_id, then add assignments to save the returned customer details. Instruct the agent when to call the lookup tool. Those details become available after the tool finishes, not before the initial message.
Try it in the Playground
- Add
Hi {{customer_name}}, how can I help?to the Introduction. As you type a variable name between{{and}}, the editor suggests custom and system variables. - Click Vars in the page header and set the preview value for
customer_nametoJordan. If the Introduction uses a variable, Preview stays disabled until that variable has a preview value. - Click Preview to start a test call with these sample values.

Typing {{ opens the variable picker.

The Vars sheet holds preview values.
config.dynamic_variable_placeholders.
Important behavior
- Any custom variables used in the initial message must be available before the call starts.
- If a webhook or phone transfer needs a missing or invalid value, the agent receives a tool error. No request or transfer is made.
- Empty text,
0, andfalsecount as supplied values.