Skip to main content
Dynamic variables let a managed agent use customer details and other values during a call. To use a variable in your agent’s text, write its name inside double braces. For example, set your agent’s initial message to:
When you supply 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.
Names are case-sensitive and can contain letters, numbers, and underscores, but cannot start with a number.

Where values come from

Values you supply

Pass dynamic_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
For batch calls, put values in each recipient’s 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:
Set the agent’s time zone with Time zone on the Advanced page in the Playground, or with config.timezone; it defaults to UTC.
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:
In the Playground, open the webhook tool and add these assignments: 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

  1. 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.
  2. Click Vars in the page header and set the preview value for customer_name to Jordan. If the Introduction uses a variable, Preview stays disabled until that variable has a preview value.
  3. Click Preview to start a test call with these sample values.
Variable picker in the Playground suggesting the custom variable customer_name

Typing {{ opens the variable picker.

Vars sheet in the Playground with a preview value for customer_name

The Vars sheet holds preview values.

Samples apply to previews in your browser and are saved when you click Publish. Production calls never use them. To set samples through the API, use 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, and false count as supplied values.
Assignments update values for the current call only. They do not change the agent’s saved configuration or supply values for the next call. In the Playground, open Calls and select a call to see its final variable values and assignments. These are also available through Get call.