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

# Route Calls to Human Operators

> Transfer Dasha BlackBox voice agent calls to human operators or other systems. Warm transfers brief operators with context first. Cold transfers provide direct routing for speed. HTTP transfers use webhook-based dynamic routing for intelligent assignment.

Route calls to human operators when needed. Choose warm transfers (with context briefing), cold transfers (direct routing), or HTTP transfers (dynamic webhook-based routing).

**What you'll learn:** Transfer type comparison, configuration basics, effectiveness metrics, and troubleshooting patterns.

***

## What is a call transfer?

A call transfer hands the conversation from your AI agent to a human operator or another system. The agent recognizes when it can't resolve an issue — complex requests, escalation demands, or specialized queries — and routes the caller to someone who can help.

**When agents should transfer:**

* Customer explicitly requests a human ("I want to talk to a person")
* Issue exceeds agent's knowledge or authority
* Sensitive situations requiring human judgment
* Complex multi-step problems needing real-time troubleshooting

***

## Transfer types

Dasha BlackBox offers three transfer methods. Choose based on your needs:

| Transfer Type | Pros | Cons | Best For |
| - | - | - | - |
| **Warm Transfer** | • Operator receives context before speaking with caller • Caller doesn't re-explain situation • Agent verifies operator availability • Agent can resume if operator disconnects | • More complex to configure • Takes longer (agent briefs operator first) • Uses more resources during handoff • Requires operator to answer and engage | Personalized escalations, complex customer issues, high-value calls, situations requiring context handoff |
| **Cold Transfer** | • Simplest to configure • Fastest transfer method • Agent freed immediately • Works well for automated systems | • No spoken operator briefing • Caller may need to explain details unless the destination reads SIP context • No operator availability verification • Less personalized experience | Simple routing, IVR/menu systems, general department transfers, high-volume basic escalations |
| **HTTP Transfer** | • Dynamic routing based on real-time data • CRM and system integration • Skill-based/intelligent assignment • Custom business logic • Workforce management integration | • Requires webhook development • Most complex to implement • Depends on external system reliability • Adds latency for webhook call • More potential failure points | Dynamic routing based on availability, skill-based assignment, CRM-integrated routing, complex business rules |

## Transfer Methods

Learn about each transfer type:

* **[Warm Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/warm-transfer.md)** - Agent briefs operator before connecting caller
* **[Cold Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/cold-transfer.md)** - Direct routing without operator briefing
* **[HTTP Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/http-transfer.md)** - Webhook-based dynamic routing

> [accordion] Quick Start: Configure Transfer via API
>
> This example shows the transfer-related fields. The PUT endpoint requires the full agent configuration including `name`, `config.primaryLanguage`, `config.ttsConfig`, and `config.llmConfig`.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X PUT "https://blackbox.dasha.ai/api/v1/agents/{agentId}" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Your Agent Name",
>     "config": {
>       "primaryLanguage": "en-US",
>       "ttsConfig": { ... },
>       "llmConfig": { ... },
>       "features": {
>         "transfer": {
>           "type": "warm",
>           "description": "Transfer when customer requests human agent or issue is complex",
>           "endpointDestination": "+15550100",
>           "callerIdMode": "userPhoneNumber",
>           "interactionWithOperator": {
>             "type": "smartV1",
>             "additionalInstructions": "Brief operator in under 10 seconds with issue summary"
>           },
>           "sayPhraseToCustomer": "Let me connect you with a specialist. One moment please.",
>           "continueAfterOperatorDisconnected": true,
>           "failoverBehavior": {
>             "continueConversation": true,
>             "staticPhrase": "All representatives are busy. Let me try to help you directly."
>           }
>         }
>       }
>     }
>   }'
> ```

## Send lead data with a transfer

Cold and warm transfers support `sipUui` and `sipHeaders` under
`config.features.transfer`. In **Features → Call transfer**, choose cold or warm transfer,
then fill in **Transfer SIP headers**. Leave these fields empty to keep the existing behavior.

This example shows only the transfer-related configuration; include the full agent configuration when updating an agent.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "config": {
    "features": {
      "transfer": {
        "type": "cold",
        "isEnabled": true,
        "description": "Transfer callers who ask for sales",
        "endpointDestination": "sip:queue@yourcompany.sip.talkdesk.com",
        "sipUui": "lead-{{leadId}}",
        "sipHeaders": {
          "X-Lead-ID": "{{leadId}}",
          "X-Caller": "{{sip_endpoint}}"
        }
      }
    }
  }
}
```

Use `"type": "warm"` with the same fields for a warm transfer. Both fixed and AI-generated
operator briefings support them. Headers also follow route retries and the warm transfer's
cold fallback.

Values use the same `{{variableName}}` templates as the agent's prompts:

* Non-null registered-call `additionalData` overrides the agent's `additionalData` for the same key.
  For example, `additionalData: {"leadId": "42"}` renders `lead-{{leadId}}` as `lead-42`.
* `{{sip_endpoint}}` is the current caller endpoint (a phone number or SIP address).
* `{{call_id}}` is the BlackBox call ID.
* `{{transfer_reason}}` is the reason passed to this transfer's `transferDecision` tool call.

Templates are evaluated when the agent starts the transfer, in the caller's context.
Tool results are not automatically turned into template variables. Supply required lead
fields in `additionalData` before the call starts.

BlackBox converts the UUI text to uppercase UTF-8 hex and appends `;encoding=hex`. For example,
`lead-42` becomes `User-to-User: 6C6561642D3432;encoding=hex`. Cold transfers put the header
inside the REFER's `Refer-To` SIP URI; warm transfers send it on the operator leg's INVITE.
Use a SIP route that preserves those headers through every hop. A PSTN route may discard them,
and a `tel:` transfer destination cannot carry URI headers.

Header names must start with `X-` (case insensitive) and contain only letters, digits, hyphens or underscores
(maximum 64 characters). Configure at most 16 headers, with no duplicate names ignoring case.
UUI and header templates are limited to 1024 characters. Control characters and pipes are
rejected in configuration; rendered CR, LF and pipes are removed before sending.
Keep the rendered UUI within 256 UTF-8 bytes (128 or fewer for broader carrier compatibility).
Longer UUI payloads are truncated with a warning.

> [!NOTE]
>
> TalkDesk needs a BYOC SIP route and a Studio flow that reads UUI.

### Twilio to TalkDesk

Use a **Programmable Voice SIP Domain**, dial it over SIP, and have its voice webhook read
`SipHeader_User-to-User`. Twilio documents this UUI support for Programmable Voice SIP calls;
[BYOC trunks discard incoming custom headers before the webhook](https://www.twilio.com/docs/voice/api/sending-sip#advanced-features).
Your TwiML must re-stamp the UUI value on the next SIP leg:

```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
<Response>
  <Dial>
    <Sip>sip:queue@yourcompany.sip.talkdesk.com?User-to-User=6C6561642D3432%3Bencoding%3Dhex</Sip>
  </Dial>
</Response>
```

Percent-encode `;`, `=` and `&` in the header value. Keep the SIP URI under 255 characters
and its header part under 1024. See Twilio's [SIP header documentation](https://www.twilio.com/docs/voice/twiml/sip#custom-headers).

## Measuring Transfer Effectiveness

Track these metrics:

* **Transfer rate**: Percentage of calls resulting in transfer
* **Transfer reason analysis**: Why are customers being transferred?
* **Transfer success rate**: Percentage of completed vs. failed transfers
* **Post-transfer satisfaction**: Are transferred customers satisfied?
* **First-call resolution impact**: How do transfers affect resolution rates?

High transfer rates may indicate:

* Agent needs more training or knowledge
* Knowledge base needs expansion
* Complex scenarios require human handling
* Transfer criteria are too broad

## Troubleshooting

### Problem: Transfers Fail Frequently

**Solution:** Verify destination numbers are correct and answering. Check network connectivity. Review failover logs for error patterns.

### Problem: Agent Transfers Too Often

**Solution:** Refine transfer description to be more specific about when transfers are appropriate. Expand knowledge base. Update system prompt with problem-solving guidance.

### Problem: Callers Drop During Transfer

**Solution:** Add hold media to maintain engagement. Set clear expectations before transfer. Reduce transfer connection time if possible.

## Next steps

> [card] [Warm Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/warm-transfer.md)
>
> Brief operators with context first

> [card] [Cold Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/cold-transfer.md)
>
> Direct routing for speed

> [card] [HTTP Transfer](https://blackbox.dasha.ai/docs/advanced-features/call-transfers/http-transfer.md)
>
> Webhook-based dynamic routing

> [card] [Maximum Call Duration](https://blackbox.dasha.ai/docs/advanced-features/max-call-duration.md)
>
> Control transferred call length


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.