Skip to content
VonyX

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

  1. VonyX → you

    10:42:07.031

    POST /answer/7f3k9q

    call_id
    "3f2b6c1e-8a4d…"
    from_number
    "14155550123"
    to_number
    "447700900123"
  2. 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

  3. Caller ⇄ agent

    10:42:07.402

    WebSocket open · 8 kHz PCM

  4. 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.

  1. 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"
    }
  2. 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
    }
  3. 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

  4. 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"
    }

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.

Clear errors that name their cause

Voice API errors
ResponseMeaning
403 no_balanceYour wallet is empty
429 client_channelsAll your channels are in use
429 client_cpsToo many new calls per second
504Network 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.

Put your first call through today.