SIP transfer
Use transfer_conversation to transfer SIP calls to phone numbers or SIP addresses. Configure destinations with the 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.
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
Code
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 |