# SIP transfer

Use `transfer_conversation` to transfer SIP calls to phone numbers or SIP addresses. Configure destinations with the [Transfer tool](/docs/transfer-tool).

## How SIP transfer works

On a SIP Channel, `transfer_conversation` executes the transfer through LiveKit's SIP API. This is a cold or blind transfer. The Assistant does not bridge the call or pass conversation context to the destination, which may ring before the transfer completes.

<Mermaid chart={`sequenceDiagram
    participant Caller
    participant Assistant
    participant LiveKit as LiveKit SIP Gateway
    participant Target as Transfer Destination

    Caller->>Assistant: Conversation
    Note over Assistant: LLM decides to transfer
    Assistant->>Caller: Pre-transfer message (optional)
    Assistant->>LiveKit: TransferSIPParticipant API
    LiveKit->>Target: SIP REFER
    Target-->>LiveKit: REFER accepted
    LiveKit-->>Assistant: Transfer successful
    Note over Caller,Target: Direct connection established
    Note over Assistant: Session ends`} />

<br />

### Assistant behaviour

| Phase                | Assistant Behaviour                                          |
| -------------------- | ------------------------------------------------------------ |
| Pre-transfer         | Says `preTransferSentence` if configured, waits for playout  |
| Transfer initiated   | Calls LiveKit's `TransferSIPParticipant` API with SIP REFER  |
| Transfer successful  | Session ends, caller is connected to destination             |
| Transfer failed      | Returns error message, conversation may continue             |

***

## Cold transfer (SIP REFER)

SIP transfers with Reecall use the **cold transfer** method. The Assistant sends a SIP REFER request through LiveKit, instructing the caller's SIP endpoint to establish a new call to the destination. The Assistant does not stay on the line or introduce the caller to the transfer target.

### Characteristics

- The transfer allows up to 25 seconds for ringing and has a 30-second overall timeout.
- The destination receives a new call without conversation context or a prior consultation call with the Assistant.
- The Assistant's session ends once the transfer succeeds.
- The caller may hear ringing or silence briefly during the REFER handshake.

***

## Destination format

The `destination` field in your transfer configuration accepts multiple formats:

| Format       | Example                    | Description                          |
| ------------ | -------------------------- | ------------------------------------ |
| E.164        | `+33612345678`             | International phone number format    |
| tel: URI     | `tel:+33612345678`         | Explicit telephone URI               |
| sip: URI     | `sip:user@domain.com`      | Direct SIP address                   |

Phone numbers without a prefix are automatically converted to `tel:` format before the transfer.

### Configuration example

```json
{
  "transfers": [
    {
      "destination": "+33612345678",
      "condition": "The caller wants to speak with sales",
      "preTransferSentence": "I'll transfer you to our sales team now."
    },
    {
      "destination": "sip:support@company.com",
      "condition": "The caller needs technical support",
      "preTransferSentence": "Connecting you with technical support."
    }
  ]
}
```

***

## Transfer outcomes

### Successful transfer

When LiveKit confirms the transfer succeeded, the Assistant's session ends. The caller is connected to the destination and no longer interacts with the Assistant.

### Failed transfer

A transfer can fail because the destination is unavailable, rejects the call, or times out. The tool returns a failure message and logs SIP details such as `sip_status_code` and `sip_status` when available. If the caller is still connected, the Assistant explains that the transfer failed and resumes the conversation.

Common SIP failure codes:

| SIP Code | Meaning                    | Typical Cause                           |
| -------- | -------------------------- | --------------------------------------- |
| 404      | Not Found                  | Invalid destination number              |
| 480      | Temporarily Unavailable    | Destination not answering               |
| 486      | Busy Here                  | Destination is busy                     |
| 503      | Service Unavailable        | Network or carrier issue                |
