Transfer Action

Transfer the call to another phone number.

Action Structure

{
  "type": "transfer",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_phone_number": "+1234567890",
  "caller_id_name": "Support Department",
  "caller_id_number": "+1234567890"
}

Fields

Field	Type	Required	Description
type	string	Yes	Always "transfer"
session_id	string (UUID)	Yes	Session identifier from event
target_phone_number	string	Yes	Phone number to transfer to (E.164 format recommended)
caller_id_name	string	Yes	Caller ID name to display
caller_id_number	string	Yes	Caller ID number to display

Examples

Python

@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if event['type'] == 'user_speak':
        user_text = event['text'].lower()

        if 'sales' in user_text:
            return jsonify({
                'type': 'transfer',
                'session_id': event['session']['id'],
                'target_phone_number': '+1234567890',
                'caller_id_name': 'Sales Department',
                'caller_id_number': '+1234567890'
            })

Node.js

app.post('/webhook', (req, res) => {
  const event = req.body;

  if (event.type === 'user_speak') {
    const userText = event.text.toLowerCase();

    if (userText.includes('sales')) {
      return res.json({
        type: 'transfer',
        session_id: event.session.id,
        target_phone_number: '+1234567890',
        caller_id_name: 'Sales Department',
        caller_id_number: '+1234567890'
      });
    }
  }
});

Go

if strings.Contains(text, "sales") {
    action := map[string]interface{}{
        "type":              "transfer",
        "session_id":        session["id"],
        "target_phone_number": "+1234567890",
        "caller_id_name":    "Sales Department",
        "caller_id_number":   "+1234567890",
    }
    json.NewEncoder(w).Encode(action)
}

Phone Number Format

Use E.164 format (recommended):

• ✅ +1234567890
• ✅ +491234567890
• ❌ 123-456-7890 (not recommended)

Use Cases

• Route to departments - Sales, support, billing
• Escalate to human - When AI can't help
• Specialized services - Connect to experts
• Emergency routing - Urgent situations

Best Practices

1. Announce transfer - Tell user before transferring
2. Use E.164 format - International phone numbers
3. Set caller ID - Identify the source
4. Log transfers - Track routing decisions

Next Steps

• Hangup Action - End the call
• Event Types - What triggers actions
• Event Flow - Understand the complete flow