Variables

This page requires Python familiarity. Variables are set and read in Python functions.

Variables are defined by setting a property on the conv.state object within a function. You can choose a name for your variable and update its value to anything you want like so:

conv.state.my_variable = 1
conv.state.my_other_variable = {
    "property": "value"
}

These variables will retain their state between turns of the conversation and can be referenced in subsequent tool calls like so:

if conv.state.my_variable == 10:
    return "Well done you hit 10"

Reading variables that haven’t been set

Reading a conv.state variable that was never assigned returns Python None – it does not raise AttributeError or KeyError. Both attribute and dictionary access are supported and equivalent:

conv.state.foo            # None if never set
conv.state["foo"]         # None if never set
conv.state.get("foo")     # None if never set (with optional default)

This enables a few common patterns: Defensive defaults with or – use when any falsy value should be replaced:

attempts = conv.state.verification_attempts or 0
intent = conv.state.call_intent or "other"

Note: or cannot distinguish “never set” from a stored falsy value (0, "", False, None). Explicit unset check with is None – use when the variable is intentionally initialized to None in the start tool as a marker that no value has been collected yet:

def start_function(conv: Conversation):
    conv.state.booking_time = None   # explicit "not yet collected" marker
    conv.state.customer_id = None

# later, in a flow step
if conv.state.booking_time is None:
    return "What time would you like to book?"

Strict “key was assigned at all” check with in – use when you must distinguish “never assigned” from a stored None:

if "booking_time" in conv.state:
    ...

Initializing variables to None (or a sensible default like "" or 0) in start_function is recommended whenever a variable is referenced in a prompt template or read in a flow step before it is guaranteed to be set, so template references and conditional checks always resolve predictably.

Built-in state keys

The conv.state object comes pre-populated with system-managed keys. These are set automatically by the platform and available in every conversation:

Key	Type	Description
`from_`	str	Caller’s phone number (note the trailing underscore – `from` is a Python reserved word)
`to`	str	Called number (callee)
`call_sid`	str	Unique call session identifier
`asr_lang_code`	str	Active ASR language code (e.g., `"en-US"`)
`tts_lang_code`	str	Active TTS language code (e.g., `"en-US"`)
`shared_id`	str	Shared identifier for correlating conversations across systems
`handoff`	object	Handoff configuration object (destination, reason, SIP method)
`disable_recordings`	bool	Whether call recording is disabled
`stop_recording`	bool	Whether recording has been stopped mid-call
`use_tts_for_responses`	bool	Whether to use TTS instead of pre-recorded audio
`asr_provider`	str or dict	Override the default ASR provider
`asr_config`	dict	Custom ASR configuration
`listen_for_sms`	bool	Whether SMS listening is enabled (default `False`)

handoff_reason and handoff_number are deprecated. Use the handoff object instead, which supports structured SIP configurations (REFER, INVITE, BYE).

You can read these values in any function:

log.info(f"Caller: {conv.state.from_}, Callee: {conv.state.to}")
log.info(f"ASR language: {conv.state.asr_lang_code}")

Prompt templating

Variables can be used inside tool calls and injected dynamically into prompts shown to the LLM. To inject a variable’s value into your prompt, use the syntax $variable_name. The system will replace this placeholder with the variable’s value wherever it matches. Example: In your start function, you can write:

from datetime import datetime

def start_function(conv: Conversation):
    conv.state.current_date = datetime.now().strftime("%B %d, %Y")

…then in your prompting: The current date is $current_date. …becomes: The current date is September 06, 2024. When using variable templating, ensure the stored value is readable by the LLM. Complex objects like dictionaries or datetime will be stringified automatically.

Environment configuration

You can use the conv.env property to define environment-specific functions and activate test features in sandbox or pre-release environments. For example:

if conv.env == "sandbox":
    # enable early feedback flow
    pass
elif conv.env == "pre-release":
    # activate staging tools
    pass
elif conv.env == "live":
    # run production features
    pass

Dynamic updates

The value templated into the prompt is always kept up to date, so any updates will be reflected in the next turn sent to the LLM. Example:

from datetime import datetime

def set_fake_date(conv: Conversation):
    conv.state.current_date = datetime(1995, 3, 22).date().strftime("%B %d, %Y")

After running this function, the resulting prompt would display: The current date is March 22, 1995. …in the next turn.

Deleting a variable

To delete a variable, remove it from the state within a function:

del conv.state['variable_name']

Variables in the Conversations API

All conv.state variables – both built-in keys and custom variables your agent writes – are returned in the state field of the Conversations API response. This means you can retrieve any state variable programmatically after a call ends. For details on the API response structure, see the Conversations API overview.

conv object

Full reference for conv.state and other conversation properties.

Start tool

Initialize state variables before the greeting plays.

Flows

Use variables to pass data across flow steps.

Get started

Studio Assistant

Analytics

Conversations

Custom Dashboards

Behavior

Knowledge

Flows

Tools

Extend with code

Testing

Real-time config

Voice

Messaging

Integrations

Deployments

Widgets

Account

Reading variables that haven’t been set

Built-in state keys

Prompt templating

Environment configuration

Dynamic updates

Deleting a variable

Variables in the Conversations API

conv object

Start tool

Flows

​Reading variables that haven’t been set

​Built-in state keys

​Prompt templating

​Environment configuration

​Dynamic updates

​Deleting a variable

​Variables in the Conversations API

​Related pages

conv object

Start tool

Flows

Reading variables that haven’t been set

Built-in state keys

Prompt templating

Environment configuration

Dynamic updates

Deleting a variable

Variables in the Conversations API

Related pages