Handoffs¶

Handoffs configure SIP call transfers for voice agents. They define how and where a call should be transferred, or whether it should be ended.

Handoffs are used when an agent needs to escalate, transfer, or terminate a voice interaction in a controlled way.

Location¶

Handoffs are defined in:

config/handoffs.yaml

They are listed under the handoffs key.

What a handoff contains¶

Each handoff includes the following fields:

Field	Description
`name`	Identifier for the handoff. Referenced in rules as `{{ho:handoff_name}}`.
`description`	Explains what the handoff does.
`is_default`	Whether this is the default handoff.
`sip_config`	Transfer method configuration.
`sip_headers`	Optional custom SIP headers as key/value pairs.

SIP config types¶

A handoff uses one of three SIP methods:

Method	Use	Fields
`invite`	Start an outbound new call	`phone_number`, `outbound_endpoint`, `outbound_encryption`
`refer`	Transfer an existing call	`phone_number`
`bye`	End the call	No extra fields

Notes¶

phone_number should use E.164 format
outbound_encryption can be TLS/SRTP or UDP/RTP

Example¶

handoffs:
  - name: escalation_handoff
    description: Transfer to a live agent for complex issues
    is_default: false
    sip_config:
      method: refer
      phone_number: "+15551234567"
    sip_headers:
      - key: X-Reason
        value: escalation

  - name: end_call
    description: End the call gracefully
    is_default: false
    sip_config:
      method: bye

How handoffs are used¶

In code

Call a handoff directly with conv.call_handoff(...).
In rules

Refer to a handoff using {{ho:handoff_name}}.
In topics and flows

Instruct the model to call a function that performs the handoff.

In code¶

You can trigger a handoff directly in code:

conv.call_handoff(destination="handoff_name", reason="transfer_reason")

In rules¶

A handoff can be referenced in rules.txt using:

{{ho:handoff_name}}

This is useful when rules need to explain when escalation or transfer should happen.

In topics and flows¶

Topics and flows should generally not perform raw transfer logic directly in prompt text. Instead, they should guide the model toward calling a function that performs the handoff.

For example:

Use {{fn:transfer_call}} when the user needs to be transferred to a specialist.

Best practices¶

use clear, descriptive handoff names
use E.164 format for phone numbers
create one handoff definition per transfer purpose
keep sip_headers minimal
only add custom SIP headers when the receiving system actually requires them

One purpose per handoff

Avoid reusing a single handoff for multiple destinations or business cases. Clear handoff names make rules and code easier to understand.

Functions

See how handoffs are typically triggered from deterministic logic. Open functions
Agent settings

Learn how handoffs are referenced in rules. Open agent settings