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 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.
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/callsalready 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:
| Prop | Type | Default |
|---|---|---|
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:
| 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. |
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. |
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:
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:
| 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.busyand 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
| Prop | Type | Default |
|---|---|---|
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
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
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.
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
| 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 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:
| 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.
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
resultstatus other thandialing), 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_idfrom theresultand its own status and cost. Its status isno-answerwhen the phone rang for the full ringing time, andcancelledwhen the call ended before the person answered. - When the person answered, the
recording_urlof 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. |