Conversation

The Conversation object, its attributes, and methods.

The Conversation object (conv) provides access to conversation data and tools for managing the agent’s behavior. It handles state management, flow transitions, SMS interactions, environment details, and voice selection.

Attributes

The conv object includes the following attributes:

env

Description: Identifies the current environment where the agent is running.

Values:

• "sandbox": For testing new features.
• "pre-release": For staging and quality assurance.
• "live": For production environments.

Example:

if conv.env == "live":
    print("Agent is live!")

sip_headers

Description: A dictionary of SIP headers with metadata about the caller.

Example:

caller_id = conv.sip_headers.get("From", "Unknown Caller")
print("Caller ID:", caller_id)

caller_number

Description: The caller’s phone number.

Type: Optional string

Example:

response = requests.get(f"https://api.example.com/users?number={conv.caller_number}")
user = response.json()
conv.state.user = user

callee_number

Description: The number the caller dialed.

Type: Optional string

Example:

if conv.callee_number == "[phone]":
    conv.state.branch = "Main Branch"
else:
    conv.state.branch = "Other Branch"

state

Description: A dictionary-like object for storing variables during the conversation. Use it to maintain context across function calls. See the variable feature page for details.

Example:

conv.state.num_calls = 1
conv.state.responses = {
    1: "This is your first call.",
    2: "This is your second call."
}

num_calls = conv.state.num_calls
conv.state.num_calls += 1
return conv.state.responses[num_calls]

Methods

The conv object includes the following methods:

randomize_voice

Description: Assigns a voice to the agent based on predefined weights. This allows an agent to use multiple voices, simulating a team of agents. For more information, visit the multi-voice guide.

Args:

• voices (list): A list of VoiceWeighting objects specifying the voices and their weights.

Example:

conv.randomize_voice([
    VoiceWeighting(
        voice=ElevenLabsVoice(
            voice_id="LcfCDJNUPlGQjkzn1xUU",
            similarity_boost=0.2,
            stability=0.4
        ),
        weight=0.5
    ),
    VoiceWeighting(
        voice=ElevenLabsVoice(
            voice_id="SOYHLrjzKX21zeoPC6cr",
            similarity_boost=0.7,
            stability=0.3
        ),
        weight=0.5
    )
])

goto_flow

Description: Moves the conversation to a specific flow.

Args:

• flow_name (str): The name of the target flow.

Example:

conv.goto_flow("support_flow")
if conv.state.should_switch_flow:
    conv.goto_flow("escalation_flow")

exit_flow

Description: Leaves the current flow and resumes the default behavior.

Example:

conv.exit_flow()