Skip to main content
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 function calls like so: 
if conv.state.my_variable == 10:
    return "Well done you hit 10"

​
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:
KeyTypeDescription
from_strCaller’s phone number (note the trailing underscore — from is a Python reserved word)
tostrCalled number (callee)
call_sidstrUnique call session identifier
asr_lang_codestrActive ASR language code (e.g., "en-US")
tts_lang_codestrActive TTS language code (e.g., "en-US")
shared_idstrShared identifier for correlating conversations across systems
handoffobjectHandoff configuration object (destination, reason, SIP method)
disable_recordingsboolWhether call recording is disabled
stop_recordingboolWhether recording has been stopped mid-call
use_tts_for_responsesboolWhether to use TTS instead of pre-recorded audio
asr_providerstr or dictOverride the default ASR provider
asr_configdictCustom ASR configuration
listen_for_smsboolWhether 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 within function 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 function

Initialize state variables before the greeting plays.

Flows

Use variables to pass data across flow steps.
Last modified on April 10, 2026