Conversation

log.info(f"Conversation ID: {conv.id}")
# Example output: "conv_abc123xyz789"

log.info(f"Account: {conv.account_id}")
# Example output: "acc_abc123"

log.info(f"Project ID: {conv.project_id}")
# Example output: "proj_abc123"

if conv.project_id == "proj_123":
  print("Running in the main deployment")

if conv.env == "live":
  log.info("Production traffic")

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")

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}")

source_ip = conv.sip_headers.get("X-Src-IP")

# 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")

identifier = conv.caller_number
log.info(f"Caller identity: {identifier}")
# Inbound example: "+14155551234"
# Chat example: "user@example.com"

if conv.callee_number.endswith("1001"):
  conv.state.branch = "Priority"

# Writes are equivalent
conv.state["is_verified"] = True
conv.state.is_verified = True

# Reads differ for missing keys
conv.state["is_verified"]        # raises KeyError if missing
conv.state.is_verified           # returns None if missing
conv.state.get("is_verified")    # returns None if missing

# Manual state
conv.state["attempts"] = conv.state.get("attempts", 0) + 1

# Auto-synced entity, available as a native int
if conv.state.party_size > 15:
  flow.goto_step("Group Booking")

# Guarding a function on a verification flag
if not conv.state.get("is_verified"):
  conv.state.original_topic = "check_account_balance"
  conv.goto_flow("Identify & Verify User")
  return

log.info(f"Current step: {conv.current_step}")

# 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)

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 "{}")

template_body = conv.sms_templates["booking_confirmation"].content

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"

if "support" in conv.handoffs:
  print("Support line is available")

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"

config = conv.real_time_config
if config.get("after_hours_enabled"):
  conv.say("Our offices are currently closed.")

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!")

if "email" in conv.entities:
  validated_email = conv.entities.email.value  # str

# Numeric entity as a native int
party_size = conv.state.party_size

result = conv.functions.lookup_order()

response = conv.api.salesforce.get_contact(user_id="123")
if response.status_code == 200:
  contact_data = response.json()

# 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()

from polyai.webchat import ChatCallAction

if conv.channel_type == "webchat.polyai":
  conv.webchat.set_chat_call_actions([
    ChatCallAction(contact_number="+15551234567", title="Call support")
  ])

for event in conv.generic_external_events:
  if event.data:
    log.info(f"Received webhook data: {event.data}")

greeting = conv.translations.welcome_message
conv.say(greeting)

for suggestion in conv.response_suggestions:
  print(suggestion)

conv.say("I've made that change for you.")

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)
])

conv.goto_flow("verification")

conv.exit_flow()

conv.set_variant("evening")

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"
  )
])

if conv.state.get("contains_pii"):
  conv.discard_recording()

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

response = requests.get("https://api.example.com/user")
conv.log_api_response(response)
# Response will appear in Conversation Review → Diagnosis

conv.send_whatsapp(
  to_number=conv.caller_number,
  from_number="+441234567890",
  content_id="HX5678efgh",
)

conv.send_content_template(
  messaging_service_id="MG1234abcd",
  to_number="+441234567890",
  content_id="HX5678efgh",
  whatsapp=True,
  content_variables={"1": "12345", "2": "shipped"}
)

conv.send_sms(to_number=conv.caller_number, from_number="+441234567890", content="Thanks for calling – here's your link: https://…")

conv.send_sms_template(to_number=conv.caller_number, template="booking_confirmation")

conv.write_metric("agent_handoff", 1)
conv.write_metric("call_outcome", "resolved", write_once=True)

conv.call_handoff(
  destination="BillingQueue",
  reason="policy_violation",
  utterance="Let me transfer you to a specialist who can help."
)

api_key = conv.utils.get_secret("stripe_api_key")
address = conv.utils.extract_address(country="US")

from polyai.voice import ElevenLabsVoice
conv.set_voice(ElevenLabsVoice(provider_voice_id="abc123"))

conv.set_language("es-US")

conv.set_asr_biasing(
  keywords=["reservation", "booking", "cancel"],
  custom_biases={"reservation": 3.0, "cancellation": 2.5}
)

conv.clear_asr_biasing()

if conv.state.get("ivr_intent") == "billing_handled":
  conv.disable_kb_topics(["refund_policy", "billing_dispute"])

conv.clear_disabled_kb_topics()

if conv.state.get("call_completed"):
  conv.goto_csat_flow()

if conv.state.get("contains_pii"):
  conv.set_csat_eligibility(False, reason="PII detected")

real_caller = conv.sip_headers.get("X-Real-Caller")
if real_caller:
  conv.set_csat_phone_number(real_caller)

conv.set_csat_survey_entered()

conv.send_email(
  to="customer@example.com",
  body="Thank you for your order!",
  subject="Order Confirmation"
)

conv.set_response_suggestions(["Yes, confirm", "No, cancel", "More options"])