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

# Voice Calls API Overview

> Programmable voice — place and receive calls, bridge to agents, run call queues, monitor, and record over the Trackly Voice API.

The Voice Calls API lets you place and receive phone calls programmatically. You call a simple REST API; Trackly handles the telephony provider and carrier connection for you. Use it to power click-to-call, outbound campaigns, inbound call queues with live agents, supervisor monitoring, and call recording.

<Note>
  Voice Calls is a distinct product served under the `/v1/voice` path. It is unrelated to the deprecated v1 SMS API. It must be enabled on your account before use — requests from an unentitled account return `403 voice_not_entitled`.
</Note>

## Base URL

```
https://api.tracklysms.com/api/v1/voice
```

## Authentication & scopes

Every request uses the same API-key authentication as the rest of the Trackly API — an `X-Api-Key` header (or `Authorization: Bearer`). See [Authentication](/api-reference/authentication).

Voice endpoints additionally require a product scope on the API key:

| Scope               | Grants                                                                               |
| ------------------- | ------------------------------------------------------------------------------------ |
| `voice_calls.read`  | Read calls, queues, agents, and recordings.                                          |
| `voice_calls.write` | Place/answer/hang up/monitor calls, manage recordings, and create queues and agents. |

## Core concepts

<CardGroup cols={2}>
  <Card title="Calls" icon="phone">
    A single call leg. A `primary` call is the customer-facing leg; `bridge` and `monitor` legs are agents and supervisors joined into the call's conference.
  </Card>

  <Card title="Queues" icon="users-line">
    Inbound callers are parked on hold audio in a queue, then claimed FIFO by an agent via [dequeue](/api-reference/voice/queues/dequeue).
  </Card>

  <Card title="Agents" icon="headset">
    A reusable, named destination (a phone number). Reference an agent by its `id` in a `connectTo` field (place/answer/dequeue) or the `to` on [monitor](/api-reference/voice/calls/monitor-call). The `to` on [Place a Call](/api-reference/voice/calls/place-call) is a plain E.164 number, not an agent id.
  </Card>

  <Card title="Recordings" icon="record-vinyl">
    Start/stop recording on an active call, then list and download the resulting audio files.
  </Card>
</CardGroup>

## Call states

A call moves through these states. `status=active` on [List Calls](/api-reference/voice/calls/list-calls) matches any non-terminal state.

| Phase    | State             | Meaning                                          |
| -------- | ----------------- | ------------------------------------------------ |
| Active   | `calling`         | The call is being set up, awaiting the provider. |
| Active   | `ringing`         | The destination is ringing.                      |
| Active   | `pre_established` | Early media before answer.                       |
| Active   | `established`     | Answered and connected.                          |
| Active   | `queued`          | Inbound call parked on hold in a queue.          |
| Active   | `dequeuing`       | Claimed from a queue and bridging to an agent.   |
| Terminal | `finished`        | Ended normally.                                  |
| Terminal | `failed`          | Ended with an error (see the call's `error`).    |
| Terminal | `cancelled`       | Cancelled before answer.                         |
| Terminal | `no_answer`       | Rang with no answer.                             |
| Terminal | `busy`            | The destination was busy.                        |

## Compliance

Every outbound dial to a phone number — `to` on [Place a Call](/api-reference/voice/calls/place-call), and the resolved `connectTo` on place/answer/dequeue or the `to` on monitor — is screened against your account's compliance suppression: Do-Not-Call, per-number opt-out, litigation/reassignment suppression, and TCPA quiet hours. This includes numbers that resolve from an [agent](/api-reference/voice/agents/create-agent). A blocked dial returns `403` with a `compliance_*` code.

## Concurrency

Each account has a ceiling on simultaneous active calls. When it is reached, new calls return `429 concurrency_limit`. Retry once existing calls complete.

## Idempotency

[Place a Call](/api-reference/voice/calls/place-call) accepts an `Idempotency-Key` header. Reusing the same key returns the original call rather than placing a second one — safe for network retries.

## Call recording

<Warning>
  Recording calls is subject to consent laws that vary by jurisdiction — many US states and other countries require one-party or all-party consent. You are responsible for obtaining any consent the law requires before recording. See [Start Recording](/api-reference/voice/calls/start-recording).
</Warning>

## Webhooks

Attach a `notifyUrl` to a queue to receive `call.received` and `call.ended` events; set a `notifySecret` to have them signed with `X-Trackly-Signature`. See [Queue Webhooks](/api-reference/voice/webhooks).

## Quickstart

Place an outbound call and bridge it to an agent on answer:

```bash theme={null}
curl -X POST https://api.tracklysms.com/api/v1/voice/calls \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155551234", "from": "+18005551234", "connectTo": "+14155559876" }'
```