Skip to main content
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

This feature is experimental and may change without warning.
Alternatively, 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. This follows the format of a handoff object: 
return {
  "handoff": {
    "type": "CALL_CENTER",
    "reason": "SPEAK_TO",
    "refer": {
      "phone_number": "12345"
    }
  }
}

​
invite

Hands the call off using a SIP INVITE. Configuration fields depend on project telephony integration requirements: 
return {
  "handoff": {
    "invite": {
      "phone_number": "<eg: 2222222>",
      "outbound_caller_id": conv.caller_number,
      "outbound_endpoint": "<ADD_YOUR_OUTBOUND_ENDPOINT_NAME>",
      "sip_headers": {
        "X-ANY_HEADER_NAME": "header"
      }
    }
  }
}

​
hangup

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

​
listen Return Object

Configures the agent to listen on the next turn.
To use asr.timeout, you must include an utterance. Without it, the timeout won’t apply.
return {
  "utterance": "Can I help you with anything else?",
  "listen": {
    "asr": {
      "timeout": 20
    }
  }
}
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: 
return {
  "variant": "orleans"
}