Skip to main content
This page requires Python familiarity. It is a reference for developers writing functions inside Agent Studio.
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

Description: Unique identifier of the conversation.Example:
log.info(f"Conversation ID: {conv.id}")
# Example output: "conv_abc123xyz789"
Description: PolyAI account ID that owns this project. This is the same account ID visible in your Studio URL: https://studio.poly.ai/account/{account_id}/...Example:
log.info(f"Account: {conv.account_id}")
# Example output: "acc_abc123"
Description: Project ID of the current agent. This is the same project ID visible in your Studio URL: https://studio.poly.ai/account/{account_id}/project/{project_id}/...Example:
log.info(f"Project ID: {conv.project_id}")
# Example output: "proj_abc123"

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.Possible values:
  • "VOICE" – Voice calls (telephony)
  • "sms" – SMS text messages
  • "sip.polyai" – SIP-based voice calls
  • Integration-specific identifiers (e.g., "webchat.polyai", "chat.polyai")
Example:
if conv.channel_type == "VOICE":
  log.info("Running a voice call")
elif conv.channel_type == "sms":
  log.info("Running an SMS conversation")
Description: List of file attachments received or queued for sending (list[Attachment]).Attachment object structure:
  • content_url (str) – URL where the file content is hosted
  • title (str) – Title or name of the attachment
  • preview_image_url (str, optional) – URL for a preview image of the attachment
  • call_to_action (str, optional) – Action label associated with the attachment (e.g., “View document”)
Example:
for file in conv.attachments:
  print(f"Title: {file.title}")
  print(f"URL: {file.content_url}")
  if file.preview_image_url:
    print(f"Preview: {file.preview_image_url}")
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]). These attributes are defined per project and per integration during setup.Supported integrations:
  • DNIs Pooling – Provides shared_id for correlating conversation outcomes
Best practice: Validate and extract required attributes in the start_function to handle missing data appropriately.Example:
# In start_function
if shared_id := conv.integration_attributes.get("shared_id"):
  conv.state.shared_id = shared_id
  log.info(f"Tracking with shared_id: {shared_id}")
else:
  # Handle missing integration data
  log.warning("No shared_id provided by integration")
Description: The caller’s identifier.For inbound calls: The phone number of the person calling in, in E.164 format (e.g., +14155551234 for USA numbers).For outbound calls: The phone number being called by the agent.For chat channels: This may be an email address or integration-provided user ID.Example:
identifier = conv.caller_number
log.info(f"Caller identity: {identifier}")
# Inbound example: "+14155551234"
# Chat example: "user@example.com"
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.role, event.text)

# Example output:
# user "I need to book a table"
# agent "I'd be happy to help you book a table"
# user "For 4 people at 7pm"
Description: Dictionary of configured hand-off destinations (dict[str, HandoffConfig]).Example:
if "support" in conv.handoffs:
  print("Support line is available")
Description: List of transcription alternatives (list[str]) for the last user utterance, including the primary transcription.Example:
for alt in conv.transcript_alternatives:
  print(f"Alternative: {alt}")

# Example output:
# Alternative: "book a table for two"
# Alternative: "book a table for too"
# Alternative: "book a table for to"
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.Customer identification: Memory is retrieved using caller_number for voice calls or the integration-provided user identifier for chat channels. This allows the agent to recognize returning customers and recall previous interactions.Example:
cheese = conv.memory.get("cheese_type")
if cheese:
  conv.say(f"You're a fan of {cheese}, right?")

# Check if this is a returning customer
if conv.memory.get("last_order_date"):
  conv.say("Welcome back!")
Description: Dictionary of entity validation results collected from the conversation (dict[str, EntityValidationResult]).Example:
if "email" in conv.entities:
  validated_email = conv.entities.email
Description: Executor for calling other functions defined in the project. Access functions using dot notation.Example:
result = conv.functions.lookup_order()
Description: Executor for calling configured API integrations. Access APIs using conv.api.{integration_name}.{operation_name}(). Example:
response = conv.api.salesforce.get_contact(user_id="123")
if response.status_code == 200:
  contact_data = response.json()
Description: List of external events initiated by generate_external_event. Each event contains ext_event_id, send_to_llm, created_at, data, and content_type.Example:
for event in conv.generic_external_events:
  if event.data:
    log.info(f"Received webhook data: {event.data}")
Description: Proxy for accessing localized translations. Access translation keys as attributes to get the translated text for the current language.Example:
greeting = conv.translations.welcome_message
conv.say(greeting)
Description: List of quick-reply suggestions for the next agent message. Only supported on webchat channels.Example:
for suggestion in conv.response_suggestions:
  print(suggestion)
Description: Agentic dial data for the conversation, used for advanced dialing scenarios.

​
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.Parameters:
  • voice_weightings (list[VoiceWeighting]) – list of VoiceWeighting objects, each containing a voice and weight.
Available voices: Import from polyai.voice module (e.g., ElevenLabsVoice, CartesiaVoice, PlayHTVoice, RimeVoice). See Voice classes for the full list of available voices and their IDs.Example:
from polyai.voice import VoiceWeighting, ElevenLabsVoice

conv.randomize_voice([
  VoiceWeighting(voice=ElevenLabsVoice(provider_voice_id="voice1"), weight=0.7), 
  VoiceWeighting(voice=ElevenLabsVoice(provider_voice_id="voice2"), weight=0.3)
])
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: Generates a unique external event ID linked to the current conversation. Use this ID to receive webhook data from an external provider via the /v1/external-events/webhook endpoint. The webhook payload is then accessible through conv.generic_external_events.Parameters:
  • send_to_llm (bool, keyword-only, optional) – if True, the webhook payload is also sent to the LLM as a system prompt. Default False.
Returns: str – the generated external event ID (expires after 1 hour).Example:
event_id = conv.generate_external_event(send_to_llm=True)
# Pass event_id to an external provider, which can POST data back via the webhook
Description: Logs an external API response for visibility in Conversation Review → Diagnosis and the analytics pipeline.Where logs appear:
  • Conversation Review: View API responses in the Diagnosis tab for debugging
  • Analytics pipeline: API response data is available for reporting and analysis
Example:
response = requests.get("https://api.example.com/user")
conv.log_api_response(response)
# Response will appear in Conversation Review → Diagnosis
Description: Sends a WhatsApp or SMS template message via Twilio’s Content API. Requires the content template to be pre-approved in your Twilio account.
WhatsApp messaging requires a configured Twilio integration and is not a native PolyAI channel. Contact your PolyAI representative for setup.
Parameters:
  • messaging_service_id (str) – Twilio messaging service ID.
  • to_number (str) – recipient phone number.
  • content_id (str) – alphanumeric ID of the approved message template.
  • content (str, optional) – text content. Default "".
  • whatsapp (bool, optional) – set to True to send over WhatsApp. Default False.
  • content_variables (dict, optional) – variables to pass to the message template.
Example:
conv.send_content_template(
  messaging_service_id="MG1234abcd",
  to_number="+441234567890",
  content_id="HX5678efgh",
  whatsapp=True,
  content_variables={"1": "12345", "2": "shipped"}
)
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.Parameters:
  • name (str) – metric key, as defined in your project’s metrics configuration.
  • value (str, int, float, bool, or None) – the metric value. Must match the type defined in the metric spec.
  • write_once (bool, optional) – if True, the metric can only be written once per conversation. Subsequent calls with the same name are ignored. Default False.
Example:
conv.write_metric("agent_handoff", 1)
conv.write_metric("call_outcome", "resolved", write_once=True)
Description: Transfer the call to a configured handoff destination.Parameters:
  • destination (str) – handoff target key, as defined in your handoff configuration.
  • reason (str, optional) – escalation reason. Defaults to the destination name.
  • utterance (str, optional) – message for the agent to say before transferring.
  • sip_headers (dict[str, str], optional) – SIP headers to pass through. Merged with any headers configured in the handoff config, with passed headers taking precedence.
  • route (str, optional) – phone number or route to override the configured route.
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 using functions; visible in Conversation Review and API.
Description: Provides helper functions for extracting data, validating entities, and accessing secrets.Available utilities:
  • get_secret(name) – Retrieve a stored secret by name
  • extract_address() – Extract postal addresses from user input
  • extract_city() – Extract city references from user input
  • prompt_llm() – Perform a standalone LLM request
  • validate_entity() – Validate a value against an entity config (email, phone, date, etc.)
  • geocode_address() – Geocode a full address string
Note: Some utilities require activation. If a method raises a NotImplementedError, contact your PolyAI representative to enable it for your account.Example:
api_key = conv.utils.get_secret("stripe_api_key")
address = conv.utils.extract_address(country="US")
See Conversation utilities for the full list of available helpers and detailed documentation.
Description: Change the TTS voice for the current conversation moving forward.Parameters: voice (TTSVoice) – the voice configuration to use.Example:
from polyai.voice import ElevenLabsVoice
conv.set_voice(ElevenLabsVoice(provider_voice_id="abc123"))
Description: Change the language for the current conversation moving forward.Parameters: language (str) – ISO 639 language code (e.g., “en-US”, “es-ES”, “fr-FR”).Example:
conv.set_language("es-US")
Description: Dynamically configure ASR keywords and custom biases for improved speech recognition. Biasing persists across turns until cleared. Parameters:
  • keywords (list[str], optional) – list of keywords to bias ASR recognition toward.
  • custom_biases (dict[str, float], optional) – dictionary mapping phrases to bias weights. Example:
conv.set_asr_biasing(
  keywords=["reservation", "booking", "cancel"],
  custom_biases={"reservation": 3.0, "cancellation": 2.5}
)
Description: Clear any previously set ASR biasing for future turns.Example:
conv.clear_asr_biasing()
Description: Trigger a transition to the CSAT (Customer Satisfaction) survey flow for voice calls.Example:
if conv.state.get("call_completed"):
  conv.goto_csat_flow()
Description: Send an email from the function.
This function sends outbound emails from within a conversation (e.g., confirmations or notifications). Email is not a supported inbound channel for PolyAI agents.
SMTP configuration: Emails are sent through a managed delivery service. For custom email delivery requirements, contact your PolyAI representative.Delivery considerations:
  • Emails are sent asynchronously after the turn completes
  • Delivery failures are logged but do not interrupt the conversation
  • For high-volume sending, consider rate limits and reputation management
Parameters:
  • to (str) – recipient email address.
  • body (str) – raw body of the email.
  • subject (str) – subject line.
Example:
conv.send_email(
  to="customer@example.com",
  body="Thank you for your order!",
  subject="Order Confirmation"
)
Description: Set quick-reply suggestions that appear as clickable options for the user. Only supported on webchat channels. Parameters: suggestions (list[str]) – list of suggested responses. Example:
conv.set_response_suggestions(["Yes, confirm", "No, cancel", "More options"])
Last modified on March 24, 2026