> ## 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

> Primeira ligação: originar chamada, acompanhar status e controlar a sessão em tempo real.

<Tip>
  Do **zero à primeira ligação na fila** em poucos passos. Antes de tudo: **número ACTIVE** no workspace e saldo ou créditos (cobrança por minuto).
</Tip>

## Em poucas palavras

* **Contrate um número ACTIVE**, é a linha de origem (`from`).
* **Origine** com `from`, `to` e o que falar ao atender (`speak`, áudio ou `gather`).
* **Acompanhe e controle** pela API ou webhooks (`voice.call.*`).

Contexto: [Introdução](/voice-api/como-funciona/introducao). Escopos: [Escopos da API Key](/voice-api/como-funciona/escopos-da-api-key). Número: [Números de Telefone](/phone-numbers-api/como-funciona/quick-start).

## Antes de começar

* **Número ACTIVE** no workspace
* Chave com **`voice:call`** (e `voice:read` / `voice:control` conforme o fluxo)
* **Saldo ou créditos** disponíveis
* Autenticação: `Authorization: Bearer sk_live_...` ou `x-api-key`
* Base URL: `https://api.notifique.dev`
* Destinos em **E.164 com `+`** (ex.: `+5511999887766`)

***

## 1. Originar uma chamada

Dois caminhos, escolha o que combina com sua integração:

#### 1A, Pelo painel

1. Voz → **Nova chamada**
2. Selecione o número de **origem** e o **destino**
3. Defina o prompt (TTS ou áudio) e dispare

#### 1B, Pela API

`to` é um **array** (até **100** destinos). Escopo: **`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": "Olá! Esta é uma ligação de teste do Notifique.",
    "voice": "female-natural"
  },
  "clientState": "campanha-verificacao-42"
}
```

Resposta esperada: **202**

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

Guarde o **`id`** da chamada para consultar e controlar.

**Outras opções no body** (altere `type` e `payload`):

* **`type: "play"`**, tocar áudio por URL: `payload.audioUrl`
* **`type: "gather"`**, coletar DTMF: `payload.gather` com `prompt`, `maxDigits`, `timeoutSecs`
* **`type: "template"`**, template do workspace: `payload.templateId` + `variables` opcionais
* **`record: true`**, gravar a ligação
* **`machineDetection: "detect"`**, detectar caixa postal

`from` aceita o **id** do número no workspace ou o **E.164**, precisa estar **ACTIVE**.

***

## 2. Listar e consultar

**Listar chamadas**

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

Filtro opcional: `direction` (`OUTBOUND` ou `INBOUND`). Escopo: **`voice:read`**.

**Consultar uma chamada**

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

Com `includeEvents=true`, a resposta traz a linha do tempo interna da sessão.

***

## 3. Controlar chamada ativa

Enquanto a ligação está em andamento, execute ações na rota `POST /v1/voice/calls/:id/actions/{action}`. Escopo: **`voice:control`**.

Exemplo, falar texto (TTS):

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

```json theme={null}
{
  "text": "Pressione 1 para vendas ou 2 para suporte.",
  "voice": "female-natural"
}
```

| Ação                           | Uso                          |
| ------------------------------ | ---------------------------- |
| `speak`                        | Falar texto (TTS)            |
| `play`                         | Tocar áudio por URL          |
| `gather`                       | Coletar DTMF                 |
| `transfer`                     | Transferir para outro número |
| `record-start` / `record-stop` | Gravar trecho                |
| `dtmf`                         | Enviar tons                  |
| `hangup`                       | Encerrar                     |

A sessão precisa estar ativa (chamada atendida e em andamento).

***

## 4. Baixar gravação

Quando a gravação estiver pronta:

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

Escopo: **`voice:read`**. Você também recebe **`voice.call.recording.ready`** no webhook.

***

## 5. Chamadas recebidas (inbound)

1. Configure `inboundVoiceAction` no número, [Números de Telefone](/phone-numbers-api/como-funciona/quick-start)
2. Com **`WEBHOOK_CONTROL`**, receba **`voice.call.received`** e controle pela API
3. Com **`FORWARD`**, encaminhe para `forwardToE164`
4. Com **`TTS_HANGUP`**, fale o texto configurado e encerre

***

## 6. Webhooks (opcional)

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

Guia: [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks).

***

## Vozes TTS

| Identificador       | Idioma                 |
| ------------------- | ---------------------- |
| `female-natural`    | Português (BR), padrão |
| `male-natural`      | Português (BR)         |
| `female-natural-en` | Inglês (US)            |
| `male-natural-en`   | Inglês (US)            |

***

## Todos os tipos de envio

Na referência da API (aba Voz), abra **Originar chamada** (`POST /v1/...`) e escolha o exemplo no playground: Falar, Reproduzir áudio, Coletar dígitos, Template, Gravação.

## Próximos passos

* [Introdução](/voice-api/como-funciona/introducao): quando usar e ciclo da chamada
* [Escopos](/voice-api/como-funciona/escopos-da-api-key): permissões da chave
* [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks): status em tempo real
* [Cobrança](/guides/introducao/cobranca-e-pague-pelo-uso): custo por minuto