Calls to your agent’s WebSocket,with one request
The VonyX Voice API answers inbound calls with a webhook and places outbound calls with one HTTPS request, then streams live call audio to your agent’s WebSocket. No SIP stack needed, and VonyX.HD is one setting away.
your-server · answer webhook
1app.post("/answer/7f3k9q", (req, res) => {2 const { call_id, from_number } = req.body;34 res.json({5 websocket_url: `wss://agent.example.com/ws?call=${call_id}`,6 webhook_url: "https://example.com/vonyx/status",7 noise_cancellation: true,8 });9});incoming · live
VonyX → you
10:42:07.031
POST /answer/7f3k9q
- call_id
- "3f2b6c1e-8a4d…"
- from_number
- "14155550123"
- to_number
- "447700900123"
You → VonyX
10:42:07.215
200 OK in 184 ms
- websocket_url
- "wss://agent.example.com/ws"
- webhook_url
- "https://example.com/status"
- noise_cancellation
- true
184 ms used2 s to reply
Caller ⇄ agent
10:42:07.402
WebSocket open · 8 kHz PCM
VonyX → you
10:45:01.118
POST /status
- CallStatus
- "completed"
- Duration
- 174
- HangupSource
- "user"
Answer every call with a webhook
When someone calls your VonyX number, VonyX sends the call details to your answer webhook. Reply with your agent’s secure WebSocket URL within 2 seconds, and the caller is connected to your agent.
VonyX → your answer webhook
Someone calls your number
VonyX sends one POST to the number’s answer webhook: who is calling, and which of your numbers they dialled.
POST /answer/7f3k9q
{ "call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12", "from_number": "14155550123", "to_number": "447700900123" }You → VonyX, within 2 seconds
You say where it goes
Reply 200 with your agent’s wss:// URL. Add a status webhook and noise cancellation if you want them. No reply in 2 seconds declines the caller, uncharged.
200 OK
{ "websocket_url": "wss://agent.example.com/ws", "webhook_url": "https://example.com/status", "noise_cancellation": true }Caller ⇄ your agent
Your agent talks
VonyX answers and streams the caller’s audio to your WebSocket as 8 kHz 16-bit PCM, and plays back what your agent sends.
WebSocket open
VonyX → your webhook_url
You hear how it ended
When the call ends, its status arrives with the duration and who hung up. Reply 200 within 10 seconds or it is sent again, up to 3 times.
POST /status
{ "CallUUID": "3f2b6c1e-8a4d…", "CallStatus": "completed", "Duration": 174, "HangupSource": "user" }
POST /answer/7f3k9q
{
"call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
"from_number": "14155550123",
"to_number": "447700900123"
}Place a call with one request
Send one HTTPS request to start an outbound call. When it’s answered, VonyX streams the audio both ways over your agent’s WebSocket, with hangup and transfer events on the same connection.
Audio your agent can use
- 16-bit PCM or μ-law
- 8 kHz or 16 kHz, your choice
- VonyX.HD (optional): VonyX speech models turn raw call audio into HD before it reaches your agent
- ElevenLabs agents connect directly with ws_protocol: "elevenlabs"
POSTapi.vocalstack.site/v1/calls
curl -X POST https://api.vocalstack.site/v1/calls \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"did": "YOUR_VONYX_NUMBER",
"phone_number": "9876543210",
"websocket_url": "wss://agent.example.com/ws",
"sample_rate": 16000,
"webhook_url": "https://example.com/vonyx/call-status"
}'The token comes from your API key. How to get one
Know what happened on every call
Status webhooks for ringing, in progress and the final status, with duration and who hung up. Call details for any call: cost, recording and timings, plus filtered, cursor-paged call lists.
- POST/v1/callsPlace an outbound call and stream it to your agent
- GET/v1/calls/{call_id}One call’s cost, recording and timings
- GET/v1/calls?client_id=…Your calls, filtered and paged by cursor
- HOOKanswer webhookVonyX asks where an inbound call goes
- HOOKstatus webhookringing, in-progress and the final status
- WSSyour agentCall audio both ways, plus hangup and transfer events
Clear errors that name their cause
| Response | Meaning |
|---|---|
| 403 no_balance | Your wallet is empty |
| 429 client_channels | All your channels are in use |
| 429 client_cps | Too many new calls per second |
| 504 | Network timeout; the call may still have been placed |
Voice API questions
Still have a question?
No. The Voice API places and answers calls over HTTPS and streams audio to your agent’s WebSocket, so you need no SIP client, trunk or PBX.
Within 2 seconds. If it doesn’t, the caller is declined and you aren’t charged. The answer webhook is not retried.
Reply with HTTP 200 within 10 seconds, or VonyX resends the event, up to 3 times. Use the call ID with the call status to ignore repeats.
16-bit PCM or μ-law, at 8 or 16 kHz. Turn on VonyX.HD to have VonyX speech models enhance the raw call audio into HD first. Inbound calls stream 8 kHz today.
Yes. Set ws_protocol to "elevenlabs" and VonyX connects the call straight to your ElevenLabs agent.