VonyxDocs

Inbound calls to your agent

Answer calls to your number with your WebSocket agent.

View this page as Markdown

When someone calls one of your Vonyx numbers, Vonyx asks your answer webhook where the call should go, then connects the caller to your agent over a WebSocket. When the call ends, Vonyx can send you the call's status.

Caller dials your Vonyx number
  -> Vonyx sends the call to your answer webhook             (POST, step 2)
  <- you reply with your agent's websocket_url               (step 3)
  -> Vonyx answers and connects the caller to your WebSocket
  -> when the call ends, Vonyx sends the call status         (optional, step 4)

To send calls to your own SIP system instead, see Inbound calls.

1. Set up the number

  1. Open My numbers in the console.
  2. In the number's Inbound webhook column, turn the switch on.
  3. Enter your answer webhook URL and choose Save & turn on.

Your answer webhook must:

  • use https:// with a valid, publicly trusted certificate. http:// is not accepted.
  • be reachable from the internet.

To clean background noise from callers' audio on every call to the number, also turn on its Noise cancellation switch, or send noise_cancellation in your reply (step 3).

If the number is released or moves to another account, its inbound webhook is switched off and the URL is cleared. Turn it on again once the number is yours.

2. What Vonyx sends you

For every inbound call, Vonyx sends one request to your answer webhook:

POST <your answer webhook URL>
Content-Type: application/json
{
  "call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
  "from_number": "919876543210",
  "to_number": "918012345678"
}
FieldDescription
call_idVonyx's id for this call. The call status in step 4 carries the same id as CallUUID.
from_numberThe caller's number: digits only, with country code. anonymous when the caller's number is withheld.
to_numberYour number that was called: digits only, with country code.

No authentication header

The request carries no credentials. Use an answer webhook URL that is hard to guess, for example one with a secret token in its path, so that only Vonyx can reach it.

3. What you reply

Reply with HTTP 200 and a JSON object:

{
  "websocket_url": "wss://agent.example.com/ws?session=abc123",
  "webhook_url": "https://example.com/vonyx/call-status",
  "noise_cancellation": true
}
PropTypeDefault
websocket_url
string
-
webhook_url
string
-
noise_cancellation
boolean
false

Vonyx then answers the call and connects the caller to your websocket_url. The WebSocket uses the same protocol as calls you place with /v1/calls. The audio is 8 kHz, 16-bit linear PCM by default (audio format).

When the call is declined

The caller is declined, and the call is not charged, when:

  • your webhook can't be reached or doesn't reply within 2 seconds. Vonyx does not retry this request.
  • the reply is not a JSON object.
  • websocket_url is missing or doesn't start with wss://.

If webhook_url or noise_cancellation has the wrong type, for example "yes" instead of true, it is ignored and the call goes ahead without it.

4. Call status (optional)

If your reply included a webhook_url, Vonyx sends the call's status to it when the call ends:

{
  "CallUUID": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
  "CallStatus": "completed",
  "Direction": "inbound",
  "From": "919876543210",
  "To": "918012345678",
  "Duration": 174,
  "StartTime": "2025-01-15 14:30:05",
  "EndTime": "2025-01-15 14:32:59",
  "HangupSource": "user"
}
FieldDescription
CallUUIDThe same id as call_id in step 2.
CallStatuscompleted for an answered call.
DirectionAlways inbound for these calls.
From, ToThe caller and your number, as in step 2.
DurationThe call's length in seconds.
StartTime, EndTimeYYYY-MM-DD HH:MM:SS, India time (IST, UTC+05:30).
HangupSourceWhich side ended the call.

The status can contain other fields; ignore them. In particular, BillRate and TotalCost are not your Vonyx charges. For costs and recordings, use the call details API.

Reply with HTTP 200 within 10 seconds. Any other status, 204 included, counts as a failure and the status is sent again, up to 3 times in total. Use CallUUID to ignore repeats.

Your agent can also hand the caller to a person.

On this page