Skip to main content
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: Type of channel the conversation is taking place on. Values: “voice”, “webchat”, “whatsapp”, “sms”, “api” Example:
if conv.channel_type == "webchat":
  log.info("Running a webchat session")
Description: List of file attachments received or queued for sending (list[Attachment]). Example:
for file in conv.attachments:
  print(file.filename)
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: Combined payload of integration metadata and attributes (dict[str, Any]). Example:
crm_id = conv.integration_data.get("contact_id")
Description: Caller’s phone number in E.164 format, or None on chat channels. For inbound calls, this is the customer’s number; for outbound calls, the target number. 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: Step name currently executing within the active flow. Example:
log.info(f"Current step: {conv.current_step}")
Description: List of OutgoingSMS / OutgoingSMSTemplate objects queued for dispatch at turn end.
Description: List of custom metrics queued for analytics.
Description: List of metric event objects queued for analytics. Example:
for metric in conv.metric_events:
  print(metric.name, metric.value)
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.speaker, event.timestamp, 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. 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. The identifier used to retrieve memory is typically caller_number for voice or the integration key for chat. 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. See Voice Selection docs for available voices. 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: Attach one or more files to the current conversation record. Example:
conv.add_attachments([{"url": "https://example.com/invoice.pdf", "filename": "invoice.pdf"}])
Description: Prevents saving the current call recording, e.g. when sensitive data is detected. Example:
if conv.state.get("contains_pii"):
  conv.discard_recording()
Description: Sends a structured webhook event to the configured external endpoint. Example:
conv.generate_external_events("booking_completed", payload={"id": "1234"})
Description: Logs an external API response for visibility in Conversation Review → Diagnosis and the analytics pipeline. Example:
response = requests.get("https://api.example.com/user")
conv.log_api_response(response)
Description: Sends an email using the configured outbound mail service (SMTP or SES). Example:
conv.send_email(
  to="user@example.com",
  subject="Your booking",
  body="<p>Thanks for your reservation — see you soon!</p>",
  cc=["manager@example.com"],
  bcc=["support@example.com"],
  attachments=["/mnt/data/invoice.pdf"]
)
Description: Sends a WhatsApp message via the configured WhatsApp Business API integration. Example:
conv.send_whatsapp(to="+441234567890", content="Hello from PolyAI!")
Description: Sends a WhatsApp or SMS template message defined in your content templates. Example:
conv.send_content_template(to="+441234567890", template="order_update", parameters={"order_id": "12345"})
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. Example:
conv.write_metric("agent_handoff", 1)
Description: Transfer the call to a configured handoff destination. Parameters: destination (str) – handoff target key; reason (str or None) – escalation reason; utterance (str or None) – message before transfer. 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 using builtin-handoff or via functions; visible in Conversation Review and API.
Description: Provides helper functions for extracting structured data from user input, such as postal addresses, names, or city references. Example:
address = conv.utils.extract_address(country="US")
See Conversation utilities for the full list of available helpers.