# Assistant transfer tool

Use `transfer_to_assistant` to hand a call to another Assistant without asking the caller to start over. The target receives the conversation history and any details you configure the source to collect.

## Overview

Transfer a call to:

* An Assistant dedicated to billing, appointments, technical support, or another task.
* An Assistant speaking another language.
* An Assistant with a different LLM, voice, or set of tools.

The source Assistant has the transfer tool. The target Assistant takes over the call.

Each `transfer_to_assistant` tool defines one destination. Set:

* `descriptionOverride` to specify when to transfer.
* `assistantId` to select the target Assistant.
* `parameters` to define the details the source must collect and pass on.

The target takes over in the same call, with its own configuration: instructions, tools, MCP servers, voice and models. Call-level settings such as the input noise filter and local VAD sensitivity remain those of the Assistant that answered the call. It knows the conversation so far and the details collected, so the caller does not have to repeat themselves.

:::info{title="Transferring to a phone number or a human?"}

This tool moves the call between Reecall Assistants. To transfer the call to a phone number, a SIP address or a human agent, use the [Transfer tool](/docs/transfer-tool) (`transfer_conversation`).

:::

***

## Naming and describing the tool

`nameOverride` and `descriptionOverride` are set when you attach the tool to the source Assistant. They tell it who the target is and when to transfer.

| Field                 | Type   | Required | Description                                                                                          |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `nameOverride`        | string | No       | Name of the transfer, e.g. `transfer_to_billing`. Letters, digits, `_` and `-`, up to 64 characters. |
| `descriptionOverride` | string | No       | When the source Assistant should transfer to this target. Supports `{variable}` placeholders.        |

Add `descriptionOverride` to the Tool object alongside `assistantId` and `configuration`. State the condition for transferring:

```json
"descriptionOverride": "Transfer the caller to the billing team when their question is about an invoice, a payment or a refund."
```

***

## Configuration

| Field         | Type   | Required | Description                                                            |
| ------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `assistantId` | string | Yes      | ID of a different Assistant in the same Project and Organisation as the source.         |
| `parameters`  | object | Yes      | JSON Schema of the details to collect and pass on.                     |

### `parameters`

A [JSON Schema](https://json-schema.org/) (draft 2020-12) of type `object` listing the details the source Assistant must collect before transferring. Use `description` on each property to say what to collect and in which format, and `required` for the details the transfer cannot happen without.

The collected values are checked against `parameters` before transferring. If they do not match, the call is not transferred and the source Assistant asks the caller again.

***

## What the target Assistant receives

* **The conversation so far.** Only the messages are passed on, not the source Assistant's tool calls and results: if the target needs data the source obtained through a tool, declare it in `parameters`.
* **The collected details**, as `{{placeholders}}` of the same name in the target's `instructions` and `firstMessage`, alongside your [variables](/docs/variables).

**Example:** with `customer_name = "Jane Doe"` collected by the source Assistant:

```text
firstMessage: Thanks {{customer_name}}, I'm taking over your billing question.
spoken:       Thanks Jane Doe, I'm taking over your billing question.
```

On its first visit during the call, the target plays its `firstMessage` if one is configured. A return visit skips that greeting. Write it as the continuation of a call already in progress, not as a fresh greeting.

***

## Exchange

A transferred call produces a single Exchange, attached to the Assistant that answered the call.

Each Assistant that took part in the call is listed in the [resources](/docs/resources), in order:

```json
[
  { "key": "assistant_id.1", "value": "8b1f0c2e-...-reception", "type": "string" },
  { "key": "assistant_id.2", "value": "3d9a7e41-...-billing", "type": "string" }
]
```

Each transfer is recorded in the [events](/docs/events):

| Event Type                  | Data fields                                                    |
| --------------------------- | -------------------------------------------------------------- |
| `assistant_transfer`        | `from_assistant_id`, `to_assistant_id`, `tool_name`            |
| `assistant_transfer_failed` | `from_assistant_id`, `to_assistant_id`, `tool_name`, `reason`  |

[Data extraction](/docs/conversational-data-extraction) uses the extraction schema of the last Assistant that took the call, falling back to the initial Assistant's schema if the last Assistant has none.

***

## Full example

This example lets a reception Assistant transfer callers to a billing Assistant.

### Step 1: fetch the tool definition

```http
GET https://newprd.reecall.io/data_next/ai/toolDefinitions?where={"name":"transfer_to_assistant"}
Authorization: Bearer {token}
```

Note the `id` of the returned definition.

### Step 2: attach the tool to the source Assistant

```http
POST https://newprd.reecall.io/data_next/ai/tools
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "definitionId": "<transfer_to_assistant-definitionId>",
  "assistantId": "<reception-assistantId>",
  "nameOverride": "transfer_to_billing",
  "descriptionOverride": "Transfer the caller to the billing team when their question is about an invoice, a payment or a refund.",
  "configuration": {
    "assistantId": "<billing-assistantId>",
    "parameters": {
      "type": "object",
      "properties": {
        "customer_name": {
          "type": "string",
          "description": "Full name of the caller"
        },
        "issue": {
          "type": "string",
          "description": "The caller's request, in one sentence"
        }
      },
      "required": ["customer_name", "issue"]
    }
  }
}
```

The billing Assistant can then use `{{customer_name}}` and `{{issue}}` in its `instructions` and `firstMessage`.
