call-transfers

Transfer calls from your AI assistant to human agents, other departments, or external numbers using SIP trunks or the built-in transfer tool.

Transfer Methods

1. Assistant-Initiated Transfer (Transfer Tool)

Let your AI assistant decide when to transfer based on the conversation.

2. API-Initiated Transfer (Call Control)

Transfer calls programmatically via the API.

Setting Up Assistant Transfers

Step 1: Add Transfer Tool

Add the transfer tool to your assistant's configuration:

Step 2: Guide the Assistant

Update your system prompt to guide when to transfer:

{
  "messages": [
    {
      "role": "system",
      "content": "You are a customer service agent. You can answer most questions yourself, but transfer to:\n- Sales: for questions about pricing, quotes, or new products\n- Technical support: for technical issues you cannot resolve\n- Billing: for specific billing questions\n\nAlways try to help first before transferring."
    }
  ]
}

Transfer Tool Schema

Field	Type	Required	Description
`type`	string	Yes	`transfer_call`
`destinations`	array	Yes	List of transfer destinations
`destinations[].type`	string	Yes	`number`
`destinations[].number`	string	Yes	Phone number in E.164 format
`destinations[].description`	string	Yes	When to use this destination (for LLM)
`destinations[].message`	string	No	Message spoken before transfer

API-Initiated Transfers

Transfer an active call via the Call Control API:

Transfer Command Fields

Field	Type	Required	Description
`type`	string	Yes	`transfer`
`destination`	string	Yes	Phone number or SIP URI
`message`	string	No	Message before transfer

Using SIP Trunks

For transfers via your own phone system, configure a SIP trunk.

Step 1: Create SIP Trunk

Step 2: Assign to Phone Number

Now transfers from this number will route through your SIP trunk.

Transfer Best Practices

Clear descriptions - Help the assistant know exactly when to transfer

Informative messages - Tell callers where they're being transferred

Avoid over-transferring - Train your assistant to handle common questions

Test destinations - Verify all transfer numbers are working

Monitor transfers - Track transfer rates to identify training opportunities

Example: Complete Transfer Setup

{
  "name": "Support Assistant",
  "first_message": "Welcome to Acme support, how can I help you?",
  "llm_config": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a support agent for Acme. Help customers with questions about products and services. Transfer only if:\n1. The customer explicitly asks for a human\n2. You cannot answer a question after 2 attempts\n3. There is a complaint that requires escalation"
      }
    ],
    "tools": [
      {
        "type": "transfer_call",
        "destinations": [
          {
            "type": "number",
            "number": "+31612345678",
            "description": "Human support assistant for complex issues or when customer explicitly requests a human",
            "message": "I'm transferring you to one of my colleagues, one moment please."
          }
        ]
      },
      {
        "type": "end_call"
      }
    ]
  }
}

See Call Control API and SIP Trunks API for complete details.

Transfer Methods#

1. Assistant-Initiated Transfer (Transfer Tool)#

2. API-Initiated Transfer (Call Control)#

Setting Up Assistant Transfers#

Step 1: Add Transfer Tool#

Step 2: Guide the Assistant#

Transfer Tool Schema#

API-Initiated Transfers#

Transfer Command Fields#

Using SIP Trunks#

Step 1: Create SIP Trunk#

Step 2: Assign to Phone Number#

Transfer Best Practices#

Example: Complete Transfer Setup#