VonyxDocs

Transfer to a person

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

View this page as Markdown

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 and on inbound calls to your agent. In this guide, the caller is whoever your agent is talking to on the call, also on calls that you placed.

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:

{
  "event": "conference",
  "action": "add",
  "phoneNumber": "9876543210"
}
PropTypeDefault
event
"conference"
-
action
"add"
-
phoneNumber
string
-
webhookUrl
string
-

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:

{
  "event": "conference",
  "action": "result",
  "roomId": "7c9e2a41-5b3d-4f8e-a6c2-1d0b9e8f7a35",
  "results": [
    {
      "number": "9876543210",
      "call_id": "b5d18f60-2e7a-4c39-8f41-6a0c3d92e4b7",
      "status": "dialing"
    }
  ]
}
FieldDescription
roomIdThe id of the transfer. It stays the same for every transfer request of one call, and the webhooks carry it as RoomID.
resultsOne entry, for the number you sent.
numberThe number, as your agent sent it.
call_idThe 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.
statusdialing: Vonyx is calling the person. Any other value: the person is not being called (table below).
statusMeaningWhat your agent can do
dialingVonyx is calling the person.Stay with the caller while the phone rings (section 4).
invalid_numberThe number is not a 10-digit Indian number.Check the number.
client_channelsAll your channels are in use.Tell the caller no one can be reached right now, or try again later.
client_cpsCalls were started faster than your calls-per-second limit.Try again after a second or two.
no_balanceYour balance was below zero when Vonyx last checked it.Tell the caller no one can be reached right now. Top up.
pool_busyNo line became free within 25 seconds on the network your number uses.Try again later, or tell the caller.
room_endingThe call is ending.Nothing.
any other valueThe 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:

{ "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.

6. If the person does not join: member_update

Vonyx sends:

{
  "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
}
FieldDescription
roomId, number, call_idThe same values as in the result.
statusWhy the person did not join (table below).
still_ringingAlways 0 for a transfer: no one else is being called. You can ignore it.
statusMeaning
no-answerThe person did not answer. This includes Vonyx ending the call after 60 seconds of ringing.
busyThe person was on another call or declined it, or their network was busy.
invalid-numberThe number does not exist or can't be reached.
cancelledThe call to the person was stopped before they answered.
failThe 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

{ "event": "hangup", "hangupType": "completed" }
PropTypeDefault
event
"hangup"
-
hangupType
string
-

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 first and hang up when its playedStream arrives.

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

Send hangup, don't just close

Vonyx treats a closed WebSocket as a dropped connection and connects to your websocket_url again.

8. Interruptions: clearAudio

{ "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 messageNotice to your agent
result, dialingYour 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 statusYour colleague could not be called right now. Tell the caller, and offer another way to help.
member_update, no-answerYour colleague did not answer and will not join the call.
member_update, busyYour colleague is busy and will not join the call.
member_update, any other statusYour colleague could not be reached and will not join the call.
WebSocket closedNone. The call has moved to your colleague, or it has ended.

Example instructions for your agent

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.

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

{
  "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"
}
FieldDescription
CallUUIDThe call_id from the result.
CallStatusSee the table below.
Directionoutbound.
FromThe person's number, as your agent sent it.
DurationHow long the person was connected, in seconds. 0 until the call to the person ends.
StartTimeWhen Vonyx started calling the person.
EndTimeWhen this status happened.
HangupSourceFor a final status, why the call to the person ended (see below).
RoomIDThe roomId from the result.
LegRolemember: 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:

CallStatusMeaning
conference_leg_ringingVonyx has started calling the person.
conference_leg_connectingThe person answered. Comes just before conference_leg_answered.
conference_leg_answeredThe person answered and is connected to the caller.
conference_leg_completedFinal. The person was connected, and the call has now ended for them.
conference_leg_no-answerFinal. The person did not answer.
conference_leg_busyFinal. The person was busy or declined the call.
conference_leg_invalid-numberFinal. The number does not exist or can't be reached.
conference_leg_failFinal. 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_ valueFinal. 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 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:

{
  "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
}
FieldDescription
eventconference_ended.
RoomIDThe roomId from the result.
OriginCallUUIDThe id of the original call.
membersThe 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[].StatusThe final status of that call.
members[].DurationSeconds on the call: for the original call, from the first transfer request until it ended; for the person, from their answer until they left.
RoomDurationSeconds 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.

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

DirectionMessageWhen
your agent → Vonyxconference, action addStart a transfer.
Vonyx → your agentconference, action resultOnce per transfer request: dialing, or why the person is not being called.
Vonyx → your agentWebSocket close, code 1000, reason Call endedThe person answered: your agent's part is over. Also sent when the call ends.
Vonyx → your agentconference, action member_updateThe person will not join. Your agent is still on the call.
your agent → Vonyxhangup with hangupTypeEnd the call.
your agent → VonyxclearAudioStop your agent's speech at once.
your agent → VonyxcheckpointVonyx replies playedStream once the audio sent before it has been played.