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

# Quick Start

> First voice call: originate, track status, and control the session in real time.

<Tip>
  From **zero to your first call in the queue** in a few steps. First: an **ACTIVE** workspace number and balance or credits (per-minute billing).
</Tip>

## In short

* **Contract an ACTIVE number**, it's the origin line (`from`).
* **Originate** with `from`, `to`, and what to say when answered (`speak`, audio, or `gather`).
* **Track and control** via API or webhooks (`voice.call.*`).

Context: [Introduction](/en/voice-api/como-funciona/introducao). Scopes: [API Key scopes](/en/voice-api/como-funciona/escopos-da-api-key). Number: [Phone Numbers](/en/phone-numbers-api/como-funciona/quick-start).

## Before you start

* **ACTIVE** number in the workspace
* Key with **`voice:call`** (and `voice:read` / `voice:control` as needed)
* **Balance or credits** available
* Auth: `Authorization: Bearer sk_live_...` or `x-api-key`
* Base URL: `https://api.notifique.dev`
* Destinations in **E.164 with `+`** (e.g. `+5511999887766`)

***

## 1. Originate a call

Two paths, pick what fits your integration:

#### 1A, Via dashboard

1. Voice → **New call**
2. Select **origin** and **destination** numbers
3. Set the prompt (TTS or audio) and dispatch

#### 1B, Via API

`to` is an **array** (up to **100** destinations). Scope: **`voice:call`**.

```http theme={null}
POST /v1/voice/calls
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "from": "+5511987654321",
  "to": ["+5511999887766"],
  "type": "speak",
  "payload": {
    "text": "Hello! This is a Notifique test call.",
    "voice": "female-natural"
  },
  "clientState": "verification-campaign-42"
}
```

Expected response: **202**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clvoice1...",
    "direction": "OUTBOUND",
    "fromE164": "+5511987654321",
    "toE164": "+5511999887766",
    "status": "QUEUED",
    "clientState": "verification-campaign-42",
    "createdAt": "2025-02-15T10:00:00.000Z"
  }
}
```

Save the call **`id`** to query and control.

**Other body options** (change `type` and `payload`):

* **`type: "play"`**, play audio from URL: `payload.audioUrl`
* **`type: "gather"`**, collect DTMF: `payload.gather` with `prompt`, `maxDigits`, `timeoutSecs`
* **`type: "template"`**, workspace template: `payload.templateId` + optional `variables`
* **`record: true`**, record the call
* **`machineDetection: "detect"`**, detect voicemail

`from` accepts the workspace number **id** or **E.164**, must be **ACTIVE**.

***

## 2. List and query

**List calls**

```http theme={null}
GET /v1/voice/calls?page=1&limit=20&direction=OUTBOUND
Authorization: Bearer sk_live_xxxxx
```

Optional filter: `direction` (`OUTBOUND` or `INBOUND`). Scope: **`voice:read`**.

**Query one call**

```http theme={null}
GET /v1/voice/calls/:id?includeEvents=true
Authorization: Bearer sk_live_xxxxx
```

With `includeEvents=true`, the response includes the internal session timeline.

***

## 3. Control active call

While the call is in progress, run actions at `POST /v1/voice/calls/:id/actions/{action}`. Scope: **`voice:control`**.

Example, speak text (TTS):

```http theme={null}
POST /v1/voice/calls/clvoice1.../actions/speak
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "text": "Press 1 for sales or 2 for support.",
  "voice": "female-natural"
}
```

| Action                         | Use                        |
| ------------------------------ | -------------------------- |
| `speak`                        | Speak text (TTS)           |
| `play`                         | Play audio from URL        |
| `gather`                       | Collect DTMF               |
| `transfer`                     | Transfer to another number |
| `record-start` / `record-stop` | Record segment             |
| `dtmf`                         | Send tones                 |
| `hangup`                       | End call                   |

The session must be active (call answered and in progress).

***

## 4. Download recording

When the recording is ready:

```http theme={null}
GET /v1/voice/calls/:id/recordings/:recordingId/download
Authorization: Bearer sk_live_xxxxx
```

Scope: **`voice:read`**. You also receive **`voice.call.recording.ready`** on the webhook.

***

## 5. Inbound calls

1. Configure `inboundVoiceAction` on the number, [Phone Numbers](/en/phone-numbers-api/como-funciona/quick-start)
2. With **`WEBHOOK_CONTROL`**, receive **`voice.call.received`** and control via API
3. With **`FORWARD`**, forward to `forwardToE164`
4. With **`TTS_HANGUP`**, speak configured text and hang up

***

## 6. Webhooks (optional)

Configure `voice.call.initiated`, `voice.call.answered`, `voice.call.dtmf`, `voice.call.completed`, etc.

Guide: [Webhook events](/en/voice-api/como-funciona/eventos-do-webhooks).

***

## TTS voices

| Identifier          | Language                 |
| ------------------- | ------------------------ |
| `female-natural`    | Portuguese (BR), default |
| `male-natural`      | Portuguese (BR)          |
| `female-natural-en` | English (US)             |
| `male-natural-en`   | English (US)             |

***

## All send types

In the API reference (Voice tab), open **Originate call** and pick an example in the playground: Speak, Play, Gather, Template, Recording.

## Next steps

* [Introduction](/en/voice-api/como-funciona/introducao): when to use and call lifecycle
* [Scopes](/en/voice-api/como-funciona/escopos-da-api-key): key permissions
* [Webhook events](/en/voice-api/como-funciona/eventos-do-webhooks): real-time status
* [Billing](/en/guides/introducao/cobranca-e-pague-pelo-uso): per-minute cost