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

# Voice

> AI phone calls: what is built, how it is turned on, and what a developer can reach.

Voice is **Beta**. It works — real customers run real calls on it, in both
directions — but it is switched on per account rather than sold on a plan, and
the developer surface is read-only.

<Note>
  **You have to ask us.** Phone is not on any published plan's price list. That
  is deliberate: "upgrade" points at a plan that does not grant it, and "coming
  soon" is simply false. Request it and we turn it on for your account.
</Note>

## What is built

<CardGroup cols={2}>
  <Card title="Outbound" icon="phone-arrow-up-right">
    A campaign dials a lead list — one task per lead, with pause, resume and
    cancel.
  </Card>

  <Card title="Inbound" icon="phone-arrow-down-left">
    A caller dials your number and an agent answers. One running inbound
    campaign per workspace at a time.
  </Card>
</CardGroup>

Also live: test calls from the dashboard (in-browser, or a real call to a phone
you name), call recordings, diarised transcripts and summaries, and metering into
your usage.

**Not built:** voice on the website widget. Website text chat is available; the
audio widget is a separate thing and it does not exist.

## Getting a number

Onboarding is deliberate rather than self-serve. There is no "buy a number"
button.

<Steps>
  <Step title="Order">
    Pick a country and supply KYC documents.
  </Step>

  <Step title="We approve the KYC" />

  <Step title="We provision the number">
    Telephony partner details are entered, SIP trunks are created, and the number
    is activated.
  </Step>
</Steps>

Until a number has an active SIP trunk attached, starting a campaign fails with a
message saying exactly that — it is not a silent no-op.

## What a developer can reach

Voice is **not on `/api/v2/`**. The API surface is v1, read-mostly, and it cannot
place a call.

| Endpoint                             | Method         | Scope         |
| ------------------------------------ | -------------- | ------------- |
| `/api/v1/calls/`                     | `GET`          | `calls:read`  |
| `/api/v1/calls/{call_uuid}/`         | `GET`          | `calls:read`  |
| `/api/v1/calls/{call_uuid}/summary/` | `PUT`, `PATCH` | `calls:write` |

<Warning>
  **There is no API way to start a call.** Campaigns, jobs and phone-number
  routes deny API keys entirely — they are dashboard operations. An API key reads
  call records and writes a summary; that is the whole of it.
</Warning>

Recording visibility follows your plan's retention setting: past the window, a
recording stops being served through the API and the dashboard.

## Getting told when a call ends

One webhook event fires today:

| Event            | Fires when                               |
| ---------------- | ---------------------------------------- |
| `call.completed` | A call ended and its outcome is resolved |

Subscribe to it on `/api/v2/webhooks/endpoints/` with `webhooks:manage`, and read
deliveries back with `webhooks:read`.

<Note>
  The published event catalogue also lists `call.started` and `call.failed`.
  **Neither is emitted yet.** They are in the catalogue as declarations, not as
  promises you can build on — do not wait on one.

  Read the catalogue from code rather than hardcoding a list:
  `GET /api/v2/webhooks/catalogue/`.
</Note>

## How a call is answered

Media runs on a self-hosted LiveKit deployment with SIP trunking to the telephony
provider. When a call connects, the worker asks the platform who should answer
and what they know — the agent's persona, its knowledge and its tools are the
same ones the text channels use. Your assistant is one assistant, whichever
channel reaches it.

A voice turn bills to the `phone` channel, so telephony spend is reported as
itself rather than folded into another channel's column.

## Limits worth knowing

* One running inbound campaign per workspace. Per-number routing is not built.
* Recording storage and retention are plan settings; retention is honoured for
  API and dashboard visibility.
* Cancellation of an in-progress call is cooperative, like everywhere else on the
  platform.

## Related

<CardGroup cols={2}>
  <Card title="Channels" icon="signal-stream" href="/concepts/channels">
    Which channels exist and what each one can carry.
  </Card>

  <Card title="Webhooks" icon="bell" href="/api/webhooks">
    Signing, delivery and replay.
  </Card>
</CardGroup>