Skip to main content
This page requires Python familiarity. It covers the return interface for functions written in Python.
Return a string or dictionary to control the agent’s next action.

​
String return

You can return a simple string, which will be used as the system prompt for the virtual agent: 
return "Tell the user that you cannot assist with their request"

​
Dictionary return

You can return a dictionary to specify more detailed and deterministic instructions. The following fields can be used individually or in combination.

​
content

Equivalent to returning a string, this field specifies the system prompt: 
return {
  "content": "Tell the user that you cannot assist with their request"
}

​
utterance

Specifies the exact phrase the virtual agent will deliver after executing the function (spoken for voice, displayed for webchat): 
return {
  "utterance": "I cannot assist with your request."
}
Note: If both content and utterance are returned:
  • The agent will stream the utterance to the user and end the turn.
  • The content rules will apply to the next turn.

​
handoff

Initiates a call handoff after the function executes. The type and reason fields match your configured handoff destination. The nested object specifies the SIP method.
Transfers the call and drops PolyAI from it:
return {
  "handoff": {
    "type": "CALL_CENTER",
    "reason": "SPEAK_TO",
    "refer": {
      "phone_number": "12345"
    }
  }
}
You can also trigger handoffs using conv.call_handoff(), which supports dynamic destination, reason, and utterance parameters. Use the dictionary return for fine-grained SIP control; use conv.call_handoff() for simpler routing.

​
hangup

Ends the conversation after the function executes. For voice, this disconnects the call; for webchat, this closes the session: 
return {
  "hangup": True
}

​
listen

Configures the agent to listen on the next turn. Must be combined with an utterance for ASR timeout settings to take effect. 
return {
  "utterance": "Can I help you with anything else?",
  "listen": {
    "asr": {
      "timeout": 20
    }
  }
}
The listen object supports these configuration keys:
KeyTypeDescription
listenboolWhether to listen for input (default True)
delayed_responseboolEnable delayed response mode — the client sends an empty input to retrieve the response
asrdictASR configuration: timeout, keywords, custom_biases, fields, corrections
dtmfdictDTMF configuration: num_digits, first_digit_timeout, inter_digit_timeout, finish_on_key, early_listening, is_pii
channelstrInput channel: "SPEECH" (default), "DTMF", or "SPEECH_AND_DTMF"
barge_indictBarge-in configuration: is_enabled, interruption_window
smart_vaddictSmart VAD configuration: is_enabled, max_extensions, max_extension_duration
interjectiondictInterjection configuration: enable, frequency (seconds)
Example with DTMF: 
return {
  "utterance": "Please enter your 6-digit code followed by the hash key.",
  "listen": {
    "channel": "SPEECH_AND_DTMF",
    "dtmf": {
      "num_digits": 6,
      "finish_on_key": "#",
      "first_digit_timeout": 5,
      "inter_digit_timeout": 2,
      "is_pii": True
    }
  }
}
ASR timeout doesn’t apply to DTMF-only input. If using both channels, make sure you include an utterance so the ASR settings take effect.

​
variant

Switches the conversation to a different variant. The value must match an existing variant name configured in variant management. This is useful for routing callers to location-specific or segment-specific conversation flows mid-call. 
return {
  "variant": "orleans"
}
You can combine variant with utterance to confirm the switch to the user: 
return {
  "utterance": "Let me connect you with the Orleans location.",
  "variant": "orleans"
}

​
Combining return fields

You can return multiple fields together. Common combinations:

utterance + handoff

Say something before transferring — the most common handoff pattern:
return {
  "utterance": "Let me transfer you to a specialist who can help with that.",
  "handoff": {
    "type": "CALL_CENTER",
    "reason": "SPEAK_TO",
    "refer": { "phone_number": "12345" }
  }
}
Say a closing message before ending the call:
return {
  "utterance": "Thanks for calling, have a great day!",
  "hangup": True
}
Deliver a specific phrase now and set instructions for the next turn:
return {
  "utterance": "I've updated your reservation.",
  "content": "The reservation has been changed. Ask if there's anything else you can help with."
}
Last modified on March 22, 2026