# Transfer to a person

Hand a call from your agent to a colleague or a support desk.

While your WebSocket agent is on a call, it can transfer the caller to a person, for example a colleague or a support desk. Vonyx calls that person's phone. When they answer, the caller and the person are connected directly and your agent leaves the call. If the person doesn't answer, your agent stays on the call and Vonyx tells it why, so it can let the caller know.

Transfers work on calls you [place with `/v1/calls`](/docs/call-api) and on [inbound calls to your agent](/docs/call-api/inbound-websocket). In this guide, the **caller** is whoever your agent is talking to on the call, also on calls that you placed.

```text
Your agent sends a transfer request                          (section 2)
  <- Vonyx replies "dialing" and calls the person            (section 3)
     your agent stays with the caller while the phone rings  (section 4)
then either
  the person answers
    -> the caller and the person are connected,
       and Vonyx closes your agent's WebSocket               (section 5)
or
  the person does not join (no answer, busy, ...)
    <- Vonyx tells your agent why; your agent is still on the call (section 6)
```

## 1. Before you start

The transfer uses the WebSocket your agent already has for the call. All messages are JSON text messages. There is nothing to set up.

- The person needs a 10-digit Indian phone number.
- The call to the person is a new outbound call from your Vonyx number. Like any call you place, it counts towards your channels (calls at the same time) and your calls-per-second limit, and your balance must be above zero. A call you placed with `POST /v1/calls` already uses one channel, so transferring it needs a second free channel.
- This is a direct transfer. The person is connected to the caller the moment they answer, and your agent does not speak to them first. If the person needs context, send it to them through your own systems when you start the transfer.

## 2. Start the transfer

Your agent sends:

```json
{
  "event": "conference",
  "action": "add",
  "phoneNumber": "9876543210"
}
```

<TypeTable
  type={{
    event: { type: '"conference"', description: 'The message type.', required: true },
    action: { type: '"add"', description: 'Start a transfer.', required: true },
    phoneNumber: {
      type: 'string',
      description:
        "The person's number: a 10-digit Indian number, digits only. A leading 91 or 0 is accepted (919876543210, 09876543210). No +, spaces or dashes.",
      required: true,
    },
    webhookUrl: {
      type: 'string',
      description:
        "Where Vonyx sends the transfer's status webhooks (section 10). Default: the call's own webhook_url. If you set it, use the same URL on every transfer request of a call.",
    },
  }}
/>

Send one transfer request at a time, then wait for its outcome (sections 5 and 6) before you send another. A second request while the person's phone is still ringing calls them again.

A transfer can only be started while your agent is connected to the call.

## 3. The reply: `result`

Vonyx replies once to every transfer request, usually within a second:

```json
{
  "event": "conference",
  "action": "result",
  "roomId": "7c9e2a41-5b3d-4f8e-a6c2-1d0b9e8f7a35",
  "results": [
    {
      "number": "9876543210",
      "call_id": "b5d18f60-2e7a-4c39-8f41-6a0c3d92e4b7",
      "status": "dialing"
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `roomId` | The id of the transfer. It stays the same for every transfer request of one call, and the webhooks carry it as `RoomID`. |
| `results` | One entry, for the number you sent. |
| `number` | The number, as your agent sent it. |
| `call_id` | The id of the call to the person. The same id is `call_id` in `member_update`, `CallUUID` in the webhooks, and `call_id` in the [call details API](/docs/call-api/call-details). |
| `status` | `dialing`: Vonyx is calling the person. Any other value: the person is not being called (table below). |

| `status` | Meaning | What your agent can do |
| --- | --- | --- |
| `dialing` | Vonyx is calling the person. | Stay with the caller while the phone rings (section 4). |
| `invalid_number` | The number is not a 10-digit Indian number. | Check the number. |
| `client_channels` | All your channels are in use. | Tell the caller no one can be reached right now, or try again later. |
| `client_cps` | Calls were started faster than your calls-per-second limit. | Try again after a second or two. |
| `no_balance` | Your balance was below zero when Vonyx last checked it. | Tell the caller no one can be reached right now. [Top up](/docs/console/wallet). |
| `pool_busy` | No line became free within 25 seconds on the network your number uses. | Try again later, or tell the caller. |
| `room_ending` | The call is ending. | Nothing. |
| any other value | The person could not be called at this moment. | Try again after a few seconds, or tell the caller. If it keeps happening, contact support. |

When all lines are busy on the network your number uses, Vonyx waits up to 25 seconds for a free line before it replies. The reply is then `dialing`, or `pool_busy` if no line became free. A request over your own limits is answered at once.

If the request itself can't be used, the reply has a `status` and no `results`:

```json
{ "event": "conference", "action": "result", "status": "invalid_request" }
```

`invalid_request` means the message is not a valid transfer request, for example `phoneNumber` is missing or contains characters other than digits. Any other status in this form also means that no one is being called.

## 4. While the person's phone rings

- Your agent stays connected to the caller, and Vonyx keeps sending the caller's audio as usual. Vonyx plays no ringing tone or music to the caller. Your agent can play its own hold music if you want some.
- Vonyx sends nothing while the phone rings. Your agent hears next when the person answers (section 5) or does not join (section 6).
- The phone rings for up to **60 seconds**.
- Your agent should keep the caller company. If the caller says something, it can answer briefly and say that it is still connecting them.
- Don't end the call while the phone rings. A hangup (section 7) ends the call for the caller and also stops the call to the person.
- Keep your WebSocket open. If it closes, the caller waits in silence. They are connected if the person answers; otherwise the call ends.

## 5. If the person answers

Vonyx connects the caller and the person directly.

At the same moment, Vonyx closes your agent's WebSocket with a normal close (code `1000`, reason `Call ended`). No message is sent before the close. Audio that has not been played yet is dropped.

Your agent's part of the call is over. Don't reconnect, and don't send anything more. The call goes on between the caller and the person. When either of them hangs up, the call ends for both.

Vonyx closes the WebSocket the same way when the caller hangs up while the person's phone is ringing. To tell the two cases apart, use the status webhook (`conference_leg_answered`, section 10) or the [call details API](/docs/call-api/call-details).

## 6. If the person does not join: `member_update`

Vonyx sends:

```json
{
  "event": "conference",
  "action": "member_update",
  "roomId": "7c9e2a41-5b3d-4f8e-a6c2-1d0b9e8f7a35",
  "number": "9876543210",
  "call_id": "b5d18f60-2e7a-4c39-8f41-6a0c3d92e4b7",
  "status": "no-answer",
  "still_ringing": 0
}
```

| Field | Description |
| --- | --- |
| `roomId`, `number`, `call_id` | The same values as in the `result`. |
| `status` | Why the person did not join (table below). |
| `still_ringing` | Always `0` for a transfer: no one else is being called. You can ignore it. |

| `status` | Meaning |
| --- | --- |
| `no-answer` | The person did not answer. This includes Vonyx ending the call after 60 seconds of ringing. |
| `busy` | The person was on another call or declined it, or their network was busy. |
| `invalid-number` | The number does not exist or can't be reached. |
| `cancelled` | The call to the person was stopped before they answered. |
| `fail` | The call to the person failed for another reason. Treat any value you don't recognise as `fail`. |

When it arrives:

- `no-answer`: after the ringing time, so about 60 seconds after the phone starts ringing, and at most 90 seconds after dialing.
- `busy` and the others: as soon as the person's network reports the outcome, usually within a few seconds. When the person declines the call, some networks take 10 to 15 seconds to report it.

A `member_update` always comes after the `result` of its request. It is sent only while your agent is on the call. A number whose `result` was not `dialing` gets no `member_update`, because the result already said why.

After a `member_update`, your agent is still on the call with the caller. It can:

- tell the caller that the person isn't available, and offer to take a message or help in another way;
- try again by sending a new transfer request, to the same number or another one;
- end the call with `hangup` (section 7).

If your agent does nothing, the call simply continues with your agent.

## 7. Ending the call: `hangup`

```json
{ "event": "hangup", "hangupType": "completed" }
```

<TypeTable
  type={{
    event: { type: '"hangup"', description: 'The message type.', required: true },
    hangupType: {
      type: 'string',
      description:
        'Why your agent ended the call, for example completed or transfer_not_answered. Letters, digits, _ and -, at most 64 characters. It comes back as HangupSource in the call status webhook. A hangup without hangupType does not end the call.',
      required: true,
    },
  }}
/>

Vonyx ends the call at once, and audio that has not been played yet is cut off. To let the caller hear your agent's last sentence, send a [checkpoint](/docs/call-api/websocket#checkpoints) first and hang up when its `playedStream` arrives.

While the person's phone rings, a hangup also stops the call to the person.

<Callout type="warn" title="Send hangup, don't just close">
  Vonyx treats a closed WebSocket as a dropped connection and connects to your `websocket_url` again.
</Callout>

## 8. Interruptions: `clearAudio`

```json
{ "event": "clearAudio" }
```

`clearAudio` stops your agent's speech at once: all audio you have sent that has not been played yet is dropped. Vonyx plays the audio you send in order and buffers up to about a minute of it. It does not stop your agent by itself when the caller speaks. Send `clearAudio`:

- when the caller starts talking over your agent (barge-in);
- when a transfer outcome arrives while your agent is still in the middle of an earlier sentence, for example "please hold while I connect you". Clear it first, so the caller hears the outcome straight away.

## 9. Programming your agent

### Give your agent a transfer tool

Give your agent a tool, for example `transfer_to_person`, that sends the transfer request (section 2).

- The tool should return at once with a neutral result, such as "Calling your colleague now. You will get a notice if they don't join." The tool's return value must not say whether the transfer worked. The outcome comes later, from Vonyx.
- If the agent uses the tool again while the phone is ringing, don't send a second request. Return "Your colleague is still being called. Keep the caller on the line."

When a message from Vonyx arrives, add a short notice to the agent's conversation (for example as a system message), and let the agent respond to it:

| Vonyx message | Notice to your agent |
| --- | --- |
| `result`, `dialing` | Your colleague's phone is ringing. Stay with the caller. If they speak, tell them you are still connecting them. Don't say goodbye and don't end the call. |
| `result`, any other status | Your colleague could not be called right now. Tell the caller, and offer another way to help. |
| `member_update`, `no-answer` | Your colleague did not answer and will not join the call. |
| `member_update`, `busy` | Your colleague is busy and will not join the call. |
| `member_update`, any other status | Your colleague could not be reached and will not join the call. |
| WebSocket closed | None. The call has moved to your colleague, or it has ended. |

### Example instructions for your agent

```text
Transferring the caller to a colleague:
- Before you transfer, tell the caller in one short sentence that you are connecting
  them, then use the transfer tool.
- While your colleague's phone rings, stay on the line. If the caller speaks, answer
  briefly and tell them you are still connecting them.
- Do not say goodbye, do not end the call, and do not say your colleague is unavailable
  until you receive a notice that says so.
- When a notice says your colleague did not answer, is busy or could not be reached,
  tell the caller they are not available right now. Offer to take a message, to try
  again, or to help with something else.
- You will not be told when your colleague answers: the call moves to them and your
  part of the call ends.
```

Keep the sentence before the transfer short. If the person answers quickly, your agent's audio stops at that moment.

### Example code

A sketch in Python. `notify_agent()` stands for whatever your agent framework uses to add a system message to the conversation and make the agent respond.

```python
import json

NOTICES = {
    "no-answer": "Your colleague did not answer and will not join the call.",
    "busy": "Your colleague is busy and will not join the call.",
}
NOT_REACHED = "Your colleague could not be reached and will not join the call."

transfer_ringing = False

async def transfer_to_person(ws, number):
    """The agent's transfer tool."""
    global transfer_ringing
    if transfer_ringing:
        return "Your colleague is still being called. Keep the caller on the line."
    transfer_ringing = True
    await ws.send(json.dumps({"event": "conference", "action": "add", "phoneNumber": number}))
    return "Calling your colleague now. You will get a notice if they don't join."

async def on_message(ws, msg):
    """Call it for every JSON text message from Vonyx."""
    global transfer_ringing
    if msg.get("event") != "conference":
        return  # media, dtmf, playedStream: handled by the rest of your agent
    if msg.get("action") == "result":
        results = msg.get("results") or []
        if results and results[0].get("status") == "dialing":
            notify_agent("Your colleague's phone is ringing. Stay with the caller. "
                         "If they speak, tell them you are still connecting them.")
        else:
            transfer_ringing = False
            notify_agent("Your colleague could not be called right now. "
                         "Tell the caller, and offer another way to help.")
    elif msg.get("action") == "member_update":
        transfer_ringing = False
        notify_agent(NOTICES.get(msg.get("status"), NOT_REACHED))
```

## 10. Status webhooks (optional)

Vonyx sends the status of the call to the person to the `webhookUrl` of the transfer request or, without one, to the call's own `webhook_url`. If there is neither, no webhooks are sent. Your agent does not need them: they are for your own systems.

Reply with HTTP `200` within 10 seconds. Any other status, `204` included, counts as a failure, and the webhook is sent again, up to 3 times in total. One call sends several statuses, so use `CallUUID` together with `CallStatus` to ignore repeats.

### The call to the person

```json
{
  "CallUUID": "b5d18f60-2e7a-4c39-8f41-6a0c3d92e4b7",
  "CallStatus": "conference_leg_answered",
  "Direction": "outbound",
  "From": "9876543210",
  "Duration": 0,
  "StartTime": "2025-01-15 14:31:02",
  "EndTime": "2025-01-15 14:31:15",
  "HangupSource": "none",
  "RoomID": "7c9e2a41-5b3d-4f8e-a6c2-1d0b9e8f7a35",
  "LegRole": "member"
}
```

| Field | Description |
| --- | --- |
| `CallUUID` | The `call_id` from the `result`. |
| `CallStatus` | See the table below. |
| `Direction` | `outbound`. |
| `From` | The person's number, as your agent sent it. |
| `Duration` | How long the person was connected, in seconds. `0` until the call to the person ends. |
| `StartTime` | When Vonyx started calling the person. |
| `EndTime` | When this status happened. |
| `HangupSource` | For a final status, why the call to the person ended (see below). |
| `RoomID` | The `roomId` from the `result`. |
| `LegRole` | `member`: this is the call to the person. |

Times are `YYYY-MM-DD HH:MM:SS`, India time (IST, UTC+05:30).

`CallStatus`, in the order they arrive:

| `CallStatus` | Meaning |
| --- | --- |
| `conference_leg_ringing` | Vonyx has started calling the person. |
| `conference_leg_connecting` | The person answered. Comes just before `conference_leg_answered`. |
| `conference_leg_answered` | The person answered and is connected to the caller. |
| `conference_leg_completed` | Final. The person was connected, and the call has now ended for them. |
| `conference_leg_no-answer` | Final. The person did not answer. |
| `conference_leg_busy` | Final. The person was busy or declined the call. |
| `conference_leg_invalid-number` | Final. The number does not exist or can't be reached. |
| `conference_leg_fail` | Final. The person did not join for another reason. `HangupSource` `conference_ring_timeout` means Vonyx stopped ringing after 60 seconds; `conference_end` means the call ended before the person answered, for example because the caller hung up. |
| any other `conference_leg_` value | Final. Treat it like `conference_leg_fail`. |

`HangupSource` on `conference_leg_completed` is `user` when the person hung up, and `conference_end` when the call ended from the caller's side.

A webhook can arrive a few seconds after the matching message to your agent.

### The original call

The original call's [status webhooks](/docs/call-api/status-webhooks) go to its own `webhook_url`, as usual. Once a transfer has been requested, they also carry `RoomID` and `LegRole` `origin`. Its `Duration` covers the whole call, including the part with the person.

### Summary when the transfer ends: `conference_ended`

If the person answered, Vonyx sends one summary when the call ends, to the same URL as the person's webhooks:

```json
{
  "event": "conference_ended",
  "RoomID": "7c9e2a41-5b3d-4f8e-a6c2-1d0b9e8f7a35",
  "OriginCallUUID": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
  "members": [
    {
      "CallUUID": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
      "To": "9812345678",
      "LegRole": "origin",
      "Status": "completed",
      "Duration": 212
    },
    {
      "CallUUID": "b5d18f60-2e7a-4c39-8f41-6a0c3d92e4b7",
      "To": "9876543210",
      "LegRole": "member",
      "Status": "conference_leg_completed",
      "Duration": 197
    }
  ],
  "RoomDuration": 212
}
```

| Field | Description |
| --- | --- |
| `event` | `conference_ended`. |
| `RoomID` | The `roomId` from the `result`. |
| `OriginCallUUID` | The id of the original call. |
| `members` | The original call and the call to the person. For the original call, `LegRole` is `origin` and `To` is the caller's number: the 10 digits you called for a call you placed or, for an inbound call, the caller's number with country code (`anonymous` when withheld). For the person, `LegRole` is `member` and `To` is their number as your agent sent it. If your agent tried more than once, each attempt is listed, and an attempt the person did not answer has `Duration` `0`. |
| `members[].Status` | The final status of that call. |
| `members[].Duration` | Seconds on the call: for the original call, from the first transfer request until it ended; for the person, from their answer until they left. |
| `RoomDuration` | Seconds from the first transfer request until the call ended. |

No summary is sent when the person did not answer.

All webhooks can contain other fields; ignore them. In particular, `BillDuration`, `BillRate`, `TotalCost` and `TotalBillDuration` are not your Vonyx charges. For costs and recordings, use the [call details API](/docs/call-api/call-details).

## 11. Billing and call records

- The call to the person is charged like any call you place: its connected time, at your per-minute rate and billing pulse. It is not charged if the person doesn't answer.
- The original call is charged as usual for its whole length. While the caller talks with the person, both calls are charged.
- If the person could not be called (a `result` status other than `dialing`), nothing is charged for it.
- In the call details API, the call to the person is listed separately once it has ended: an outbound call to the person's number, with the `call_id` from the `result` and its own status and cost. Its status is `no-answer` when the phone rang for the full ringing time, and `cancelled` when the call ended before the person answered.
- When the person answered, the `recording_url` of their call is the recording of the original call. That one recording holds the whole call: the part with your agent and the conversation with the person.

## 12. Quick reference

| Direction | Message | When |
| --- | --- | --- |
| your agent → Vonyx | `conference`, action `add` | Start a transfer. |
| Vonyx → your agent | `conference`, action `result` | Once per transfer request: `dialing`, or why the person is not being called. |
| Vonyx → your agent | WebSocket close, code `1000`, reason `Call ended` | The person answered: your agent's part is over. Also sent when the call ends. |
| Vonyx → your agent | `conference`, action `member_update` | The person will not join. Your agent is still on the call. |
| your agent → Vonyx | `hangup` with `hangupType` | End the call. |
| your agent → Vonyx | `clearAudio` | Stop your agent's speech at once. |
| your agent → Vonyx | `checkpoint` | Vonyx replies `playedStream` once the audio sent before it has been played. |
