> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecrew.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Warm Transfers

> Hand off calls to humans with full context

# Warm Transfers

A warm transfer connects a caller to a human agent while providing context about the conversation. Unlike cold transfers, the receiving agent knows who's calling and why before the connection is made.

## How Warm Transfers Work

```
1. AI Agent decides to transfer
          ↓
2. Caller placed on hold with music/message
          ↓
3. AI dials destination number
          ↓
4. AI briefs receiving agent
          ↓
5. Receiving agent accepts/declines
          ↓
6. All parties connected (or caller returned to AI)
```

## Configuring Warm Transfers

### Basic Configuration

```json theme={null}
{
  "transfer": {
    "type": "warm",
    "destination": "+14155551234",
    "brief_template": "Incoming call from {{caller.name}} regarding {{intent}}. They've been on the line for {{call_duration}}.",
    "hold_music": "default",
    "timeout": 30
  }
}
```

### Brief Templates

Customize what the AI tells the receiving agent:

```json theme={null}
{
  "brief_template": "Hi, I have {{caller.name}} on the line. They're calling about {{intent}}. Key details: {{conversation.summary}}. Ready to connect?"
}
```

#### Available Variables

| Variable                   | Description             |
| -------------------------- | ----------------------- |
| `{{caller.name}}`          | Caller's name if known  |
| `{{caller.phone}}`         | Caller's phone number   |
| `{{intent}}`               | Detected call intent    |
| `{{conversation.summary}}` | AI-generated summary    |
| `{{call_duration}}`        | Time caller has been on |
| `{{data.field_name}}`      | Any collected data      |

### Hold Experience

Configure what callers hear while waiting:

```json theme={null}
{
  "hold": {
    "type": "music",
    "source": "default",
    "message_interval": 30,
    "message": "Thank you for holding. A team member will be with you shortly."
  }
}
```

#### Hold Options

| Type       | Description            |
| ---------- | ---------------------- |
| `music`    | Play hold music        |
| `message`  | Play custom message    |
| `silence`  | Muted hold             |
| `ringback` | Standard ringing sound |

## Transfer Flow Options

### Accept/Decline

The receiving agent can accept or decline:

```json theme={null}
{
  "transfer": {
    "accept_key": "1",
    "decline_key": "2",
    "prompt": "Press 1 to accept this call, or 2 to send to voicemail."
  }
}
```

### Auto-Connect

Connect immediately without confirmation:

```json theme={null}
{
  "transfer": {
    "auto_connect": true,
    "whisper": "Incoming transfer regarding {{intent}}"
  }
}
```

### Voicemail Fallback

If the transfer is declined or times out:

```json theme={null}
{
  "fallback": {
    "action": "voicemail",
    "message": "I wasn't able to reach someone directly. Please leave a message and we'll call you back."
  }
}
```

## Multi-Destination Transfers

### Sequential Dialing

Try destinations in order:

```json theme={null}
{
  "transfer": {
    "type": "warm",
    "destinations": [
      {
        "number": "+14155551111",
        "timeout": 20
      },
      {
        "number": "+14155552222",
        "timeout": 20
      },
      {
        "number": "+14155553333",
        "timeout": 20
      }
    ],
    "fallback": {
      "action": "voicemail"
    }
  }
}
```

### Simultaneous Ring

Ring multiple destinations at once:

```json theme={null}
{
  "transfer": {
    "type": "warm",
    "strategy": "simultaneous",
    "destinations": [
      "+14155551111",
      "+14155552222"
    ],
    "first_responder_wins": true
  }
}
```

## Skill-Based Routing

Route based on agent skills:

```json theme={null}
{
  "transfer": {
    "type": "warm",
    "routing": {
      "skill": "billing",
      "priority": "high"
    }
  }
}
```

### Skill Groups

Define skill groups for routing:

```json theme={null}
{
  "skill_groups": {
    "billing": {
      "agents": [
        { "number": "+14155551111", "priority": 1 },
        { "number": "+14155552222", "priority": 2 }
      ]
    },
    "technical": {
      "agents": [
        { "number": "+14155553333", "priority": 1 }
      ]
    }
  }
}
```

## Screen Pop Integration

Send caller information to the receiving agent's screen:

```json theme={null}
{
  "transfer": {
    "screen_pop": {
      "enabled": true,
      "url": "https://crm.yourcompany.com/call?caller={{caller.phone}}&account={{caller.account_id}}",
      "data": {
        "caller_name": "{{caller.name}}",
        "intent": "{{intent}}",
        "summary": "{{conversation.summary}}",
        "collected_data": "{{data}}"
      }
    }
  }
}
```

## Transfer Events

Monitor transfer status via webhooks:

| Event                | Description         |
| -------------------- | ------------------- |
| `transfer.initiated` | Transfer started    |
| `transfer.ringing`   | Destination ringing |
| `transfer.answered`  | Recipient answered  |
| `transfer.briefed`   | Brief delivered     |
| `transfer.accepted`  | Transfer accepted   |
| `transfer.declined`  | Transfer declined   |
| `transfer.completed` | Parties connected   |
| `transfer.failed`    | Transfer failed     |

### Event Payload

```json theme={null}
{
  "event": "transfer.completed",
  "call_id": "call_abc123",
  "transfer_id": "transfer_xyz789",
  "destination": "+14155551234",
  "duration_to_connect": 12.5,
  "brief_delivered": true,
  "context": {
    "caller_name": "John Smith",
    "intent": "billing_question"
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep briefs concise">
    Receiving agents are busy. Aim for 10-15 seconds of context, not a full recap.
  </Accordion>

  <Accordion title="Set appropriate timeouts">
    30 seconds is typical. Too short and agents can't answer; too long and callers abandon.
  </Accordion>

  <Accordion title="Always have a fallback">
    If no one answers, route to voicemail or offer a callback.
  </Accordion>

  <Accordion title="Use whisper for quick context">
    If auto-connecting, a whisper gives agents heads-up without delay.
  </Accordion>

  <Accordion title="Monitor transfer success rates">
    High decline rates indicate staffing or routing issues.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Transfers failing

1. Verify destination number is correct
2. Check if receiving agents are available
3. Ensure timeout isn't too short
4. Verify telephony connection is working

### Callers abandoning during hold

1. Reduce timeout duration
2. Improve hold music/messaging
3. Add position-in-queue announcements
4. Consider callback option

### Context not appearing

1. Verify brief template syntax
2. Check if variables are being collected
3. Test screen pop URL separately
4. Review webhook deliverability

## Next Steps

* [Call Routing](/voice/call-routing) — Configure routing rules
* [Integrations](/integrations/twilio) — Set up telephony
* [Webhooks](/integrations/webhooks) — Handle transfer events