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']
Last modified on March 22, 2026