Conversation

Comprehensive reference for the Conversation (conv) object, its attributes, and methods.

The Conversation object (conv) provides access to critical conversation data and utilities for controlling the assistant’s behavior during interactions. It centralizes functionality for managing states, flows, SMS communication, and the current environment.

Attributes

The following attributes are available in the conv object:

env

Description: Identifies the current environment in which the assistant 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("Assistant is live!")

sip_headers

Description: A dictionary mapping SIP headers to their corresponding values, such as caller metadata.

Example:

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

caller_number

Description: Returns the caller’s phone number.

Type: Optional string

Example:

import requests

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

user = response.json()
conv.state.user = user

callee_number

Description: Returns the phone number the caller dialed.

Type: Optional string

Example:

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

state

Description: A dictionary-like object for storing and persisting variables throughout the conversation. Use it to manage contextual data and share information between function calls. For more information visit, the function variable feature page.

Example:

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

# Increment call count and retrieve response
num_calls = conv.state.num_calls
conv.state.num_calls += 1
return conv.state.responses[num_calls]

current_flow

Description: Returns the name of the flow the conversation is currently in, or None if no flow is active.

Type: Optional string

Example:

if conv.current_flow != "support_flow":
    return "This function should only be used in 'support_flow'."

Methods

The following methods are available in the conv object:

goto_flow

Description: Transitions the assistant to a specified 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: Exits the current flow and resumes the assistant’s default behavior.

Example:

conv.exit_flow()

set_variant

Description: Sets the variant for the current conversation.

Args:

• variant_name (str): The name of the variant to set.

Example:

conv.set_variant("priority_customer_variant")

send_sms

Description: Sends an SMS message directly to the caller.

Args:

• phone_number (str): The recipient’s phone number.
• message (str): The content of the SMS.

Example:

conv.send_sms("[phone]", "Your appointment has been confirmed.")

send_sms_template

Description: Sends a predefined SMS template with optional dynamic values.

Args:

• template_name (str): The name of the SMS template.
• dynamic_values (dict): A dictionary of placeholders and their values.

Example:

conv.send_sms_template("order_confirmation", {"order_id": "12345", "delivery_date": "2025-01-20"})