Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

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:
  • "sip.polyai" – Voice calls (telephony/SIP)
  • "webchat.polyai" – Webchat widget
  • "chat.polyai" – Agent Studio in-browser chat
  • "sms.twilio" – SMS text messages
Use .startswith() for broader matching (e.g., conv.channel_type.startswith("sms")) when you don’t need to distinguish between SMS sub-types.
Example:
if conv.channel_type == "sip.polyai":
  log.info("Running a voice call")
elif conv.channel_type.startswith("sms"):
  log.info("Running an SMS conversation")
elif conv.channel_type == "webchat.polyai":
  log.info("Running a webchat conversation")
Description: List of file attachments received or queued for sending (list[Attachment]).Attachment object structure:
  • content_url (str) – URL to the main content of the attachment
  • content_type (str) – The type of the attachment ("image", "weblink", or "unspecified")
  • title (str, optional) – Title of the attachment
  • preview_image_url (str, optional) – URL to a preview image for the attachment
  • call_to_action (str, optional) – Text for the call-to-action button or link
Example:
for file in conv.attachments:
  print(f"Type: {file.content_type}")
  print(f"URL: {file.content_url}")
  if file.title:
    print(f"Title: {file.title}")
  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 in 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]). Each key is the variant name and each value is a Variant object whose attributes match the columns defined in Build > Variant management.Example:
# Iterate variants to find one matching a custom attribute
for variant_name, variant in conv.variants.items():
  log.info(f"{variant_name}: {variant.phone_number}")

# Build a lookup from a variant attribute to variant name
callee_map = {
    variant.callee: name
    for name, variant in conv.variants.items()
}
matched = callee_map.get(conv.callee_number)
if matched:
    conv.set_variant(matched)
Description: Variant object for the active variant, or None if no variant has been set. Attribute values are returned as strings (the storage type used by Variant management) — parse them yourself if you need structured data. Reading an attribute that doesn’t exist on the active variant returns None, not an AttributeError.Example:
if conv.variant:
  print(conv.variant.description)

  # Attribute values are strings — parse JSON yourself if needed
  import json
  hours = json.loads(conv.variant.opening_hours_json or "{}")
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: Language code configured for the project, which may include a locale suffix (e.g. “en-US”, “en-GB”, “es-ES”).
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 lets the agent 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: Executor for calling pre-built third-party integrations (e.g., OpenTable, Tripleseat) configured from Configure > Integrations. Access using conv.integrations.{integration_name}.{method}().
conv.integrations is for integrations PolyAI has built and maintains (proxied through Paragon). For custom HTTP APIs you define yourself in the APIs tab, use conv.api.
Example:
# OpenTable
response = conv.integrations.opentable.get_reservation(confirmation_number="ABC123")

# Tripleseat
response = conv.integrations.tripleseat.create_lead(
  public_key=conv.utils.get_secret("tripleseat_public_key"),
  first_name="Jane",
  last_name="Smith",
  phone_number=conv.caller_number,
  location_id="12345",
)
if response.status_code == 200:
  lead_data = response.json()
See Integrations for the list of available integrations and setup instructions.
Description: Webchat-specific interface for functionality that only applies on webchat.polyai channels. Access webchat-only methods via conv.webchat.{method}().Available methods:
  • set_chat_call_actions(actions) – attach click-to-call buttons to the next agent message.
Example:
from polyai.webchat import ChatCallAction

if conv.channel_type == "webchat.polyai":
  conv.webchat.set_chat_call_actions([
    ChatCallAction(contact_number="+15551234567", title="Call support")
  ])
Calling webchat methods on non-webchat channels has no effect on the conversation, but you should still gate them on conv.channel_type for clarity.
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 visual tiles (images or web links) to the conversation. Only supported on webchat channels.Parameters: attachments (list[Attachment]) – list of Attachment objects.Attachment fields:
  • content_url (str) – URL to the main content of the attachment
  • content_type (str) – The type of the attachment ("image", "weblink", or "unspecified")
  • title (str, optional) – Title of the attachment
  • preview_image_url (str, optional) – URL to a preview image for the attachment
  • call_to_action (str, optional) – Text for the call-to-action button or link
Attachment types:
  • "weblink" – Displays the title, preview image, and call-to-action text. Clicking navigates the user to content_url.
  • "image" – Displays the title (if present), but no call-to-action. preview_image_url should be a lower resolution image, and content_url should be the full resolution image. Clicking shows the higher resolution version.
  • "unspecified" – No specific rendering behaviour is applied.
Example:
from polyai.attachments import Attachment

conv.add_attachments([
  Attachment(
    content_url="https://example.com/menu",
    content_type="weblink",
    title="View our menu",
    preview_image_url="https://example.com/menu-preview.jpg",
    call_to_action="Open menu"
  ),
  Attachment(
    content_url="https://example.com/logo.png",
    content_type="image"
  )
])
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 through 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 message through a Twilio subaccount. Both the sender phone number and the message template must be pre-approved by Meta. Once approved, Twilio provides a content_id that must be referenced when sending.
WhatsApp messaging requires a configured Twilio integration and is not a native PolyAI channel. Contact your PolyAI representative for setup.
Parameters:
  • to_number (str) – recipient phone number.
  • from_number (str) – sender phone number (must be WhatsApp-enabled in Twilio).
  • content_id (str) – alphanumeric ID of the approved WhatsApp message template.
  • content (str, optional) – text content. Default "".
  • retry_count (int, optional) – number of retries to attempt on failure.
Example:
conv.send_whatsapp(
  to_number=conv.caller_number,
  from_number="+441234567890",
  content_id="HX5678efgh",
)
For richer templating with variables, use send_content_template with whatsapp=True.
Description: Sends a WhatsApp or SMS template message through 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.)
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: Override whether the conversation is eligible for a CSAT survey. When eligible=False, the conversation is excluded from CSAT regardless of call type, percentage rollout, or weekly caps. When eligible=True or this method isn’t called, normal CSAT logic applies.Parameters:
  • eligible (bool) – whether the conversation is eligible for CSAT.
  • reason (str, optional) – reason for the decision (logged for debugging).
Example:
if conv.state.get("contains_pii"):
  conv.set_csat_eligibility(False, reason="PII detected")
Description: Override the phone number used for CSAT SMS surveys. Useful when the real caller number is delivered via a SIP header (e.g., behind an IVR) rather than as the caller ID.Parameters:
  • phone_number (str) – phone number to send the CSAT SMS to, in E.164 format.
Example:
real_caller = conv.sip_headers.get("X-Real-Caller")
if real_caller:
  conv.set_csat_phone_number(real_caller)
Description: Mark that the caller entered the CSAT survey flow. This is used internally by the platform’s voice CSAT flow for analytics and is not typically called from custom functions.Example:
conv.set_csat_survey_entered()
Description: Send an email from the function.This function sends outbound emails during 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 May 1, 2026