# Transfer tool

Configure transfer destinations and conditions with `transfer_conversation`. The Channel determines whether Reecall executes the transfer over SIP or delegates it to your WebRTC client.

## What is the transfer tool?

The `transfer_conversation` System Tool transfers ongoing calls to external destinations. The Assistant selects a destination based on the conversation and your configured conditions.

<Mermaid chart={`flowchart LR
    subgraph Assistant
        LLM[LLM Decision]
        TT[Transfer Tool]
    end
    
    User([Caller]) --> Assistant
    LLM --> |"trigger"| TT
    TT --> |"transfer"| Dest([Destination])`} />

The `transfer_conversation` tool is configured with a list of possible transfer destinations, each with:

* `destination`: the target phone number or SIP address
* `condition`: when the Assistant should transfer to this destination
* `preTransferSentence` (optional): what the Assistant says before initiating the transfer

***

## Setting up the transfer tool

The API paths below are relative to `https://newprd.reecall.io/data_next`.

### Step 1: fetch the transfer tool definition

Retrieve the `transfer_conversation` Tool Definition ID:

```http
GET /ai/toolDefinitions?where={"name":"transfer_conversation"}
```

Use the `id` from the response as `definitionId` when creating the Tool:

```json
[
  {
    "id": "9de0f15e-6873-4428-a08f-b29e8c906b05",
    "name": "transfer_conversation",
    "description": "Transfer the conversation ...",
    "configuration": {},
    "createdAt": "2025-12-15T08:58:49.942Z",
    "updatedAt": "2025-12-15T08:58:49.942Z"
  } 
]
```

### Step 2: create the transfer tool

Create a Tool instance with your transfer configuration:

```http
POST /ai/tools
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "assistantId": "your-assistant-id",
  "definitionId": "9de0f15e-6873-4428-a08f-b29e8c906b05",
  "configuration": {
    "transfers": [
      {
        "destination": "+33612345678",
        "condition": "The caller wants to speak with sales",
        "preTransferSentence": "I'll transfer you to our sales team now."
      },
      {
        "destination": "+33698765432",
        "condition": "The caller needs technical support",
        "preTransferSentence": "Let me connect you with our technical team."
      }
    ]
  }
}
```

***

## Configuration reference

The `transfers` array contains the available transfer destinations:

| Field                 | Required | Description                                                          |
| --------------------- | -------- | -------------------------------------------------------------------- |
| `destination`         | Yes      | Phone number in E.164 format (e.g., `+33612345678`) or SIP address   |
| `condition`           | Yes      | Natural language description of when to transfer to this destination |
| `preTransferSentence` | No       | Message the Assistant speaks before initiating the transfer          |

### Example configurations

**Single destination:**

```json
{
  "transfers": [
    {
      "destination": "+33612345678",
      "condition": "The caller explicitly asks to speak with a human agent"
    }
  ]
}
```

**Multiple destinations with routing logic:**

```json
{
  "transfers": [
    {
      "destination": "+33611111111",
      "condition": "The caller has a billing question or payment issue",
      "preTransferSentence": "I'll connect you with our billing department."
    },
    {
      "destination": "+33622222222",
      "condition": "The caller needs help with their order or delivery",
      "preTransferSentence": "Transferring you to our orders team."
    },
    {
      "destination": "+33633333333",
      "condition": "The caller wants to cancel their subscription",
      "preTransferSentence": "I'll transfer you to our retention team."
    }
  ]
}
```

***

## Behaviour

### Condition evaluation

The Assistant evaluates transfer conditions based on the conversation context. The `condition` field is a natural language description that the LLM interprets during the conversation.

When multiple conditions could apply, the Assistant selects the most appropriate destination based on the conversation flow and caller intent.

### Pre-transfer message

If `preTransferSentence` is provided, the Assistant speaks it before initiating the transfer. Use it to tell the caller where they are being transferred.

## SIP vs WebRTC transfer comparison

| Aspect           | SIP Transfer               | WebRTC Transfer                          |
| ---------------- | -------------------------- | ---------------------------------------- |
| Transfer method  | Cold (SIP REFER)           | Delegated to client                      |
| Execution        | Direct via LiveKit API     | Via RPC to your application              |
| Hold audio       | No dedicated hold music    | Your application can provide hold audio |
| Context handoff  | Not supported              | Optional conversation summary sent   |
| Transfer outcome | Determined by SIP response | Determined by your application           |
| Failure handling | Based on SIP status codes  | Based on your `reason` field             |

<br />

## What's next

- [WebRTC transfer](/docs/webrtc-transfer)
- [SIP transfer](/docs/sip-transfer)
