Dynamic call transfers

Overview

Dynamic call transfers enable intelligent routing by determining transfer destinations in real-time based on conversation context, customer data, or external system information. Unlike static transfers with predefined destinations, dynamic transfers make routing decisions on-the-fly during the call.

Key capabilities:

• Real-time destination selection based on conversation analysis
• Integration with CRM systems, databases, and external APIs
• Conditional routing logic for departments, specialists, or geographic regions
• Context-aware transfers with conversation summaries
• Custom business logic execution before completing the transfer
• Programmatic transfer control via Vapi’s Call Control API

Prerequisites

• A Vapi account
• A server or cloud function that can receive webhooks from Vapi
• (Optional) CRM system or customer database for enhanced routing logic

How It Works

Dynamic transfers with live call control use a server-controlled pattern that gives you maximum flexibility:

1. User initiates transfer: The user requests a transfer in natural language during the conversation
2. Vapi triggers custom tool: Vapi fires your custom tool to your HTTP server
3. Server receives control URL: The tool payload includes message.call.monitor.controlUrl for live call control
4. Execute business logic: Your server performs any necessary operations:
   • Update CRM records with call summaries
   • Extract and store conversation data
   • Query databases for routing decisions
   • Enrich destination systems with context
5. Complete transfer: Your server makes a POST request to the controlUrl with the transfer destination
6. Call connected: Vapi transfers the call to the specified SIP or PSTN destination

Available context: Your server receives the full conversation transcript, custom parameters, call metadata, and the control URL, allowing you to make informed routing decisions and execute the transfer programmatically.

Sequence diagram

Quick Implementation Guide

1
import express from 'express';
2
import axios from 'axios';
3
4
const app = express();
5
app.use(express.json());
6
7
app.post('/webhook', async (req, res) => {
8
  try {
9
    const { message } = req.body;
10
11
    // Extract control URL from the call monitor
12
    const controlUrl = message?.call?.monitor?.controlUrl;
13
    
14
    // Extract tool call from toolWithToolCallList
15
    const toolWithToolCall = message?.toolWithToolCallList?.[0];
16
    const toolCall = toolWithToolCall?.toolCall;
17
18
    if (!controlUrl || !toolCall) {
19
      return res.status(400).json({ error: 'Missing required data' });
20
    }
21
22
    // Extract parameters from the tool call
23
    const { department, reason, urgency } = toolCall.function.arguments;
24
25
    // Execute business logic (optional)
26
    console.log(`Transfer request: ${department} - ${reason} (${urgency})`);
27
28
    // Determine destination based on department
29
    let destination;
30
    if (department === 'support') {
31
      destination = {
32
        type: "number",
33
        number: "+1234567890"
34
      };
35
    } else if (department === 'sales') {
36
      destination = {
37
        type: "number",
38
        number: "+1987654321"
39
      };
40
    } else {
41
      destination = {
42
        type: "number",
43
        number: "+1555555555"
44
      };
45
    }
46
47
    // Execute transfer via Live Call Control
48
    await axios.post(`${controlUrl}/control`, {
49
      type: "transfer",
50
      destination: destination,
51
      content: `Transferring you to ${department} now.`
52
    }, {
53
      headers: { 'Content-Type': 'application/json' }
54
    });
55
56
    // Respond to Vapi (optional acknowledgment)
57
    res.json({ success: true });
58
59
  } catch (error) {
60
    console.error('Transfer error:', error);
61
    res.status(500).json({ error: 'Transfer failed' });
62
  }
63
});
64
65
app.listen(3000, () => {
66
  console.log('Webhook server running on port 3000');
67
});

1
{
2
  "type": "transfer",
3
  "destination": {
4
    "type": "sip",
5
    "sipUri": "sip:+1234567890@sip.telnyx.com"
6
  },
7
  "content": "Transferring your call now."
8
}

Routing Patterns

Common Use Cases

• Customer support routing - Route based on issue type, customer tier, agent availability, and interaction history. Enterprise customers and critical issues get priority routing to specialized teams.

• Geographic routing - Direct calls to regional offices based on customer location and business hours. Automatically handle time zone differences and language preferences.

• Load balancing - Distribute calls across available agents to optimize wait times and agent utilization. Route to the least busy qualified agent.

• Escalation management - Implement intelligent escalation based on conversation tone, issue complexity, and customer history. Automatically route urgent issues to senior agents.

Transfer Configuration

1. Warm transfers provide context to receiving agents with AI-generated conversation summaries, ensuring smooth handoffs with full context.

2. Cold transfers route calls immediately with predefined context messages, useful for simple departmental routing.

3. Conditional transfers apply different transfer modes based on routing decisions, such as priority handling for enterprise customers.

4. Destination types include phone numbers for human agents, SIP endpoints for VoIP systems, and Vapi assistants for specialized AI agents.

Troubleshooting

• Tool call not received: Verify your server URL is correctly configured in the custom tool and is publicly accessible. Check your server logs for incoming requests.
• Transfer not executing: Make sure that you are sending a valid destination object (type number or sip). See API reference here.
• Invalid destination format: For phone numbers, use "type": "number" with E.164 format. For SIP, use "type": "sip" with a valid SIP URI.
• Transfer fails silently: Check your server logs for errors in the axios/httpx request.

Related Documentation

• Call Forwarding - Static transfer options and transfer plans
• Webhooks - Webhook security and event handling patterns
• Custom Tools - Build custom tools for advanced routing logic