Analyze
- Dashboards
- Conversations
- Assistant analysis
- Call data
Build
- Conversation flow
- Knowledge base
- Call handoffs
- SMS
- Flows
- Functions
- Speech recognition
- Response control
- About
Configure
- Audio management
- Environments & versions
- Voice
- Variant management
- Telephony
- User management
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)
Methods
Description: Change the assistant voice for future replies.
Example:
conv.set_voice(voice=Voices.en_female_warm)
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.