# Inbound calls to your agent

Answer calls to your number with your WebSocket agent.

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.

```text
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](/docs/console/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:

```http
POST <your answer webhook URL>
Content-Type: application/json
```

```json
{
  "call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
  "from_number": "919876543210",
  "to_number": "918012345678"
}
```

| Field | Description |
| --- | --- |
| `call_id` | Vonyx's id for this call. The call status in step 4 carries the same id as `CallUUID`. |
| `from_number` | The caller's number: digits only, with country code. `anonymous` when the caller's number is withheld. |
| `to_number` | Your number that was called: digits only, with country code. |

<Callout type="warn" title="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.
</Callout>

## 3. What you reply

Reply with HTTP `200` and a JSON object:

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

<TypeTable
  type={{
    websocket_url: { type: 'string', description: "Your agent's WebSocket. Must start with wss://.", required: true },
    webhook_url: {
      type: 'string',
      description: "Where Vonyx sends the call status when the call ends (step 4). Leave it out if you don't want the status.",
    },
    noise_cancellation: {
      type: 'boolean',
      description: "true removes background noise from the caller's audio before it reaches your agent.",
      default: '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`](/docs/call-api/websocket). The audio is 8 kHz, 16-bit linear PCM by default ([audio format](/docs/call-api/websocket#4-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:

```json
{
  "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"
}
```

| Field | Description |
| --- | --- |
| `CallUUID` | The same id as `call_id` in step 2. |
| `CallStatus` | `completed` for an answered call. |
| `Direction` | Always `inbound` for these calls. |
| `From`, `To` | The caller and your number, as in step 2. |
| `Duration` | The call's length in seconds. |
| `StartTime`, `EndTime` | `YYYY-MM-DD HH:MM:SS`, India time (IST, UTC+05:30). |
| `HangupSource` | Which 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](/docs/call-api/call-details).

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](/docs/call-api/human-transfer).
