> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Callback

> How click-to-call works, the call lifecycle, and reading call logs.

Web Callback places a click-to-call from your backend: you name a destination, Wave dials it through its telephony backend and bridges the call.

## Placing a call

`POST /v1/callback` with at least a `to` number. See the [Quickstart](/quickstart) and the [API Reference](/api-reference/overview).

| Field              | Required | Description                                        |
| ------------------ | -------- | -------------------------------------------------- |
| `to`               | ✅        | Destination KSA number in E.164 (`+9665XXXXXXXX`). |
| `caller_id_name`   | —        | Caller ID name shown to the callee.                |
| `caller_id_number` | —        | Caller ID number.                                  |
| `from_queue`       | —        | Originating extension/queue.                       |
| `metadata`         | —        | Key/value object echoed back on webhooks.          |

## Call lifecycle

A callback is created with `status: "initiated"` and returns `202` immediately.

The call then progresses through its lifecycle as the telephony backend reports it — `answered` (with `answered_at`), then `ended` (with `duration`). Each transition fires the matching [webhook](/webhooks) (`call.answered`, `call.ended`), and the final status and duration are written to the call record.

```
initiated  ──▶  answered  ──▶  ended
```

<Note>
  Treat the `202` as "accepted," not "completed." Subscribe to
  [webhooks](/webhooks) — or poll `GET /v1/calls` — to follow the call to
  `answered` / `ended`.
</Note>

## Call logs

Every callback is recorded. Retrieve them with **`GET /v1/calls`** — cursor-paginated (`cursor`, `limit` up to 100), numbers masked — or view them on the **Call Logs** page in the dashboard. See the [API Reference](/api-reference/overview) for the full request/response.

## Cancelling / retrieving a single call

`GET /v1/callbacks/:id` and `DELETE /v1/callbacks/:id` are **coming soon** (D1.1) — they are not yet functional. This page will document them when they ship.