Manage
- Dashboards
- Conversations
- Assistant analysis
- Test suite
- Call data
Build
- Conversation flow
- Knowledge base
- Variant management
- Agent
- Call handoffs
- SMS
- Flows
- Functions
- Speech recognition
- Configuration builder
Voice
- Configuration
- Audio management
- Response control
- Telephony
Configure
- Environments & versions
- Telephony
- User management
Troubleshoot
Legal
Conversation
The Conversation object, its attributes, and methods.
The Conversation object (conv) provides access to conversation data and tools for managing the agent’s behaviour. It handles state management, flow transitions, SMS interactions, environment details, and voice selection.
Attributes
Description: Unique identifier of the conversation.
Example:
print(conv.id)
Description: PolyAI account ID that owns this project.
Example:
log.info(f"Account: {conv.account_id}")
Description: Project ID of the current agent.
Example:
if conv.project_id == "proj_123":
print("Running in the main deployment")
Description: Current environment.
Values:
"sandbox""pre-release""live"
Example:
if conv.env == "live":
log.info("Production traffic")
Description: Dictionary of SIP headers (dict[str, str]) provided by the carrier.
Example:
source_ip = conv.sip_headers.get("X-Src-IP")
Description: Metadata passed from an external integration (dict[str, Any]).
Only available inside the start function.
Example:
source = conv.integration_attributes.get("lead_source")
Description: Caller’s phone number in E.164 format, or None on chat channels.
Example:
if conv.caller_number:
conv.send_sms(conv.caller_number, BUSINESS_NUMBER, "Thanks for calling!")
Description: Number dialled by the caller.
Example:
if conv.callee_number.endswith("1001"):
conv.state.branch = "Priority"
Description: Dictionary-like store that persists values across turns.
Example:
conv.state["attempts"] = conv.state.get("attempts", 0) + 1
Description: Name of the flow currently executing, or None.
Description: List of OutgoingSMS / OutgoingSMSTemplate objects queued for dispatch at turn end.
Description: List of custom metrics queued for analytics.
Description: Name of the active variant, or None.
Description: Dictionary of all variant definitions (dict[str, Variant]).
Description: Variant object for the active variant, or None.
Example:
if conv.variant:
print(conv.variant.description)
Description: Dictionary of SMS templates (dict[str, SMSTemplate]).
Example:
template_body = conv.sms_templates["booking_confirmation"].content
Description: Pending TTSVoice change requested this turn, or None.
Description: ISO-639 language code configured for the project (e.g. "en").
Description: Chronological list of UserInput and AgentResponse events so far.
Example:
for event in conv.history:
print(event.text)
Description: Dictionary of configured hand-off destinations (dict[str, HandoffConfig]).
Example:
if "support" in conv.handoffs:
print("Support line is available")
Description: List of ASR alternatives for the last user utterance.
Example:
print(conv.transcript_alternatives)
Description: Returns a dictionary of real-time configuration values defined in Configuration Builder.
Use this to read values like opening_hours, fallback_number, or flags for toggling logic between environments.
Example:
config = conv.real_time_config
if config.get("after_hours_enabled"):
conv.say("Our offices are currently closed.")
Description: Dictionary of memory fields previously stored for the caller, retrieved from Agent Memory.
Use conv.memory.get("key") to access previously saved values across conversations. You can store new fields by assigning them to conv.state if the field is listed in the Agent Memory config.
Example:
cheese = conv.memory.get("cheese_type")
if cheese:
conv.say(f"You're a fan of {cheese}, right?")
Methods
Description: Override the next utterance.
Example:
conv.say("I’ve made that change for you.")
Description: Randomly choose a voice based on weighted probabilities.
Example:
conv.randomize_voice([
VoiceWeighting(voice=Voices.en_male_calm, weight=70),
VoiceWeighting(voice=Voices.en_female_warm, weight=30),
])
Description: Transition to another flow at turn end.
Example:
conv.goto_flow("verification")
Description: Exit the current flow.
Example:
conv.exit_flow()
Description: Manually set the active variant.
Example:
conv.set_variant("evening")
Description: Log an external API response for analytics.
Example:
response = requests.get("https://api.example.com/user")
conv.log_api_response(response)
Description: Queue a plain-text SMS.
Example:
conv.send_sms(
to_number=conv.caller_number,
from_number="+441234567890",
content="Thanks for calling — here’s your link: https://…",
)
Description: Queue a pre-configured SMS template.
Example:
conv.send_sms_template(to_number=conv.caller_number, template="booking_confirmation")
Description: Write a custom metric to the analytics pipeline.
conv.write_metric("agent_handoff", 1)
Description: Transfer the call to a configured handoff destination.
This method supports optional reason and utterance fields:
| Parameter | Type | Description |
|---|---|---|
destination | str | Handoff target key (e.g. "BillingQueue"). Must be defined in your agent config. |
reason | str or None | Short code for escalation reason. Appears in Conversation Review and API. |
utterance | str or None | Spoken message just before transfer begins. Also appears in logs and Review. |
Example:
conv.call_handoff(
destination="BillingQueue",
reason="policy_violation",
utterance="Let me transfer you to a specialist who can help."
)
Where it shows up:
- In flows or actions using
builtin-handoff, the fields appear as config options. - In functions, you call
conv.call_handoff(...)directly. - In Conversation Review and the Conversations API, both fields appear for debugging and analytics.