Return values

When creating functions, you can specify return values to control the agent’s behavior dynamically. The return value can either be a string or a dictionary containing specific fields to guide the virtual agent.

​

String return

You can return a simple string, which will be used as the system prompt for the virtual agent:

return "Tell the caller that you cannot assist with their request"

​

Dictionary return

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 caller that you cannot assist with their request"
}

​

utterance

Specifies the exact phrase the virtual agent will speak after executing the function:

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 call after the function executes:

return {
  "hangup": True
}

​

listen Return Object

Configures the agent to listen on the next turn.

return {
  "utterance": "Can I help you with anything else?",
  "listen": {
    "asr": {
      "timeout": 20
    }
  }
}

​

variant

Switches the conversation to a different variant:

return {
  "variant": "orleans"
}