Skip to main content

​
Transfer Call

The Transfer Call tool lets your voice agent hand off a live call to a human agent, a specific department, or an external phone number. You can use cold transfers (immediate switch) or warm transfers (agent briefs the human before connecting).

​
Transfer Types

​
Cold Transfer

The AI agent connects the caller to the destination immediately. The caller hears ringing and then the human picks up. 
Caller: "I need to speak to a manager."
Agent: "Of course, I'll transfer you now. One moment please."
→ Call transfers to +14155551234

​
Warm Transfer

The AI agent first calls the destination, briefs the human on the caller’s issue, then connects all parties. 
Caller: "I have a billing dispute."
Agent: "Let me connect you with our billing team. One moment."
→ Agent calls billing team, provides summary
→ Caller is connected to the billing agent

​
Configuration

​
Via the Dashboard

  1. Open your agent and scroll to Voice Settings.
  2. Enable Transfer Call.
  3. Configure transfer destinations:
SettingDescription
Default destinationPhone number for general transfers
Department routingMap keywords to specific numbers
Transfer typeCold or warm transfer
Hold messageWhat the caller hears while being transferred
FallbackWhat happens if the transfer fails (voicemail, retry, etc.)

​
Via the API

curl -X PATCH https://api.thinnest.ai/agents/agent_abc123 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_tools": {
      "transfer_call": {
        "enabled": true,
        "type": "cold",
        "default_destination": "+14155551234",
        "department_routing": {
          "billing": "+14155552222",
          "sales": "+14155553333",
          "support": "+14155554444"
        },
        "hold_message": "Please hold while I transfer you.",
        "fallback_action": "voicemail"
      }
    }
  }'

​
System Prompt Guidance

Tell your agent when and how to transfer calls: 
If the caller asks to speak to a human, sales, billing, or support team,
transfer the call to the appropriate department:
- Sales inquiries → transfer to sales
- Billing questions → transfer to billing
- Technical issues you cannot resolve → transfer to support
- "Speak to a manager" → transfer to the default number

Before transferring, briefly summarize the caller's issue so the human
agent has context.

​
Department Routing

You can route transfers based on conversation context. Configure department-to-number mappings, and the AI agent will automatically route to the right destination based on the caller’s needs. 
{
  "department_routing": {
    "sales": "+14155551111",
    "billing": "+14155552222",
    "technical_support": "+14155553333",
    "manager": "+14155554444",
    "scheduling": "+14155555555"
  }
}

​
Transfer Failures

If the destination doesn’t answer, thinnestAI handles it gracefully:
Fallback ActionBehavior
voicemailLeave a voicemail at the destination
retryTry the transfer again after a short delay
callbackCollect caller’s number and schedule a callback
return_to_agentBring the caller back to the AI agent