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

# Preços, opções e modos de chamada

> Tarifa de voz por país de destino, sobretaxas (AMD, gravação, WebRTC), record, amdMode e modos de origem na API e no painel.

<Tip>
  A voz é cobrada **por minuto**, com valor que depende do **país de destino** (saída) ou do **país de origem** (entrada). Gravação e AMD são **opcionais** — só são ativados na operadora e cobrados quando você pede.
</Tip>

## Em poucas palavras

| Conceito              | O que é                                                                           |
| --------------------- | --------------------------------------------------------------------------------- |
| **Minuto de saída**   | Tarifa por país do número discado (`to` em outbound)                              |
| **Minuto de entrada** | Tarifa por país de quem liga (`from` em inbound)                                  |
| **WebRTC (ao vivo)**  | Adicional por minuto quando a conversa é pelo navegador (painel)                  |
| **Sobretaxas**        | AMD (por chamada), gravação (por minuto gravado), transferência, etc.             |
| **`record`**          | Liga gravação na sessão (`true` / `false`, padrão `false`)                        |
| **`amdMode`**         | Detecção de caixa postal: `disabled` \| `detect` \| `premium` (padrão `disabled`) |

Tabela pública sempre atualizada: [Consulta de preços](/guides/precos/api-de-precos) (`GET /v1/pricing` → bloco `voice`).

***

## Preço dinâmico por país

Com precificação v2 ativa, cada destino tem linha própria em `voice.rates[]`:

```json theme={null}
{
  "country": "BR",
  "countryName": "Brasil",
  "callingCode": "55",
  "direction": "OUTBOUND",
  "credits": 120,
  "paygCents": 12,
  "available": true,
  "unavailableReason": null
}
```

* **`direction: "OUTBOUND"`** — você disca para o destino; o país vem do `to`.
* **`direction: "INBOUND"`** — alguém liga para seu número; o país vem do `from` do chamador.
* País desconhecido ou sem linha → usa `voice.fallbackCountry` (geralmente `BR` ou `ZZ`).

### Como estimar antes de ligar (painel)

No dashboard, `GET /voice/price-estimate?to=5511999887766&legMode=pstn` devolve o custo estimado por minuto para aquele E.164. Com `legMode=webrtc`, inclui o adicional de conversa ao vivo pelo navegador.

Na API v1 pública, use `GET /v1/pricing` e filtre `voice.rates` pelo código ISO do destino.

<Note>
  A cobrança real usa **minutos arredondados para cima** (mínimo 1 minuto por chamada atendida). O primeiro minuto é debitado na criação; minutos extras no encerramento.
</Note>

***

## Opções `record` e `amdMode`

Disponíveis em **todos** os caminhos de saída:

* `POST /v1/voice/calls` (API v1)
* Automações (`placeVoiceCall`)
* Painel → Nova chamada (mensagem automática e IVR)

### `record` (gravação)

| Valor              | Telnyx                        | Cobrança Notifique                                                  |
| ------------------ | ----------------------------- | ------------------------------------------------------------------- |
| `false` ou omitido | **Não** inicia `record_start` | Sem sobretaxa de gravação                                           |
| `true`             | Grava após atender            | Sobretaxa **por minuto gravado** (`voice.surcharges` → `recording`) |

```json theme={null}
{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": {
    "text": "Olá! Sua entrega chega hoje entre 14h e 18h.",
    "voice": "female-natural"
  },
  "record": true
}
```

Depois do encerramento, baixe com `GET /v1/voice/calls/:id/recordings/latest/download` ou aguarde o webhook `voice.call.recording.ready`.

### `amdMode` (detecção de caixa postal)

Substitui o campo legado `machineDetection`.

| Valor               | Enviado à Telnyx | Cobrança                                    |
| ------------------- | ---------------- | ------------------------------------------- |
| `disabled` (padrão) | Nada             | Nenhuma                                     |
| `detect`            | AMD padrão       | Sobretaxa fixa por chamada (`amd_standard`) |
| `premium`           | AMD premium      | Sobretaxa fixa por chamada (`amd_premium`)  |

```json theme={null}
{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": {
    "text": "Olá, aqui é a loja X confirmando seu pedido 8842."
  },
  "amdMode": "detect",
  "record": false
}
```

<Warning>
  **AMD não se aplica** à conversa **ao vivo pelo navegador** (modo live do painel). Nesse modo, `amdMode` é sempre tratado como `disabled`; a gravação (`record`) continua opcional.
</Warning>

<Info>
  `machineDetection` ainda é aceito na API v1 por compatibilidade (`detect`, `premium`, etc.), mas prefira **`amdMode`**.
</Info>

***

## Sobretaxas de voz (`voice.surcharges`)

Além do minuto, o bloco `voice.surcharges[]` em `GET /v1/pricing` lista add-ons:

| Código         | Unidade                         | Quando cobra                      |
| -------------- | ------------------------------- | --------------------------------- |
| `amd_standard` | por chamada                     | `amdMode: "detect"`               |
| `amd_premium`  | por chamada                     | `amdMode: "premium"`              |
| `recording`    | por minuto                      | `record: true` e chamada atendida |
| `transfer`     | por uso                         | transferência na sessão           |
| `webrtc`       | (já embutido no minuto ao vivo) | painel, modo live                 |
| `tts_char`     | por caractere                   | TTS avançado (quando aplicável)   |

Se você **não** pedir gravação nem AMD, a Telnyx **não** ativa esses recursos na perna — e a Notifique **não** debita as sobretaxas correspondentes.

***

## Tipos de chamada (`type`)

| `type`     | Uso                     | Campos principais em `payload`              |
| ---------- | ----------------------- | ------------------------------------------- |
| `speak`    | TTS após atender        | `text`, `voice`, `language`                 |
| `play`     | Áudio por URL           | `audioUrl`                                  |
| `gather`   | Coletar DTMF            | `gather.prompt`, `maxDigits`, `timeoutSecs` |
| `template` | Template do workspace   | `templateId`, `variables`                   |
| `ivr`      | URA publicada ou inline | `flowId` ou `flow` (grafo)                  |

### Exemplo completo — speak + gather + AMD

```json theme={null}
{
  "from": "clxx_phone_br_sp",
  "to": ["5511999887766", "5521988776655"],
  "type": "gather",
  "payload": {
    "gather": {
      "prompt": "Digite 1 para confirmar a consulta ou 2 para reagendar.",
      "maxDigits": 1,
      "timeoutSecs": 15,
      "voice": "female-natural"
    }
  },
  "amdMode": "detect",
  "record": false,
  "clientState": "agendamento-clinica-2026-08"
}
```

**Resposta (202)**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clvoice_01...", "clvoice_02..."],
    "voiceCallIds": ["clvoice_01...", "clvoice_02..."]
  }
}
```

### Exemplo — reproduzir áudio

```json theme={null}
{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "play",
  "payload": {
    "audioUrl": "https://cdn.suaempresa.com/audio/aviso-entrega.mp3"
  }
}
```

***

## Dashboard modes

The **New call** screen has two dial modes and three option chips:

| Mode                  | API equivalent                      | Notes                                                       |
| --------------------- | ----------------------------------- | ----------------------------------------------------------- |
| **Automatic message** | `type: speak` (+ optional `gather`) | TTS after answer; Translation, Schedule, and Advanced chips |
| **Live call**         | WebRTC (`POST /voice/webrtc/calls`) | One destination; outbound + WebRTC minute; AMD off          |

| Chip            | Sends                                                       |
| --------------- | ----------------------------------------------------------- |
| **Translation** | `localization` + `i18n` (`speakText`, `gatherPrompt`)       |
| **Schedule**    | `schedule.sendAt` (paid plans)                              |
| **Advanced**    | `record`, `amdMode`, TTS voice, `gather`, `options.webhook` |

**IVR** is no longer created from the dashboard — use `POST /v1/voice/flows` + `type: ivr` ([IVR and flows](/en/voice-api/como-funciona/ivr-e-fluxos)).

The dashboard shows **estimated price per minute** by destination and mode (PSTN vs WebRTC).

***

## Scheduling, localization, and webhook (`POST /v1/voice/calls`)

Optional root fields (API v1 and dashboard, unless noted):

| Field                       | Use                                                                                     |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `schedule.sendAt`           | ISO 8601 — future dial (**dashboard** and authenticated `POST /voice/calls`; paid plan) |
| `localization.mode`         | `off` \| `manual` \| `ai`                                                               |
| `localization.sourceLocale` | Source locale (e.g. `pt-BR`)                                                            |
| `i18n`                      | Locale map → `{ speakText, gatherPrompt? }` in manual mode                              |
| `options.webhook.url`       | HTTPS — `voice.call.*` events **for this call only**                                    |
| `options.webhook.secret`    | Optional HMAC secret                                                                    |
| `metadata`                  | String key-value pairs stored on the call record                                        |

**202** with scheduling: `data.status` may be `SCHEDULED` and `data.scheduledAt` has the time. With AI localization: `data.localization`.

***

## Chamada ao vivo (WebRTC) — rotas de app

Autenticação de **sessão** (não API Key). Usadas pelo softphone do painel:

| Método  | Rota                      | Função                                  |
| ------- | ------------------------- | --------------------------------------- |
| `GET`   | `/voice/price-estimate`   | Estimativa por `to` e `legMode`         |
| `POST`  | `/voice/webrtc/token`     | Token SIP/WebRTC para o número          |
| `POST`  | `/voice/webrtc/calls`     | Abre CDR da chamada ao vivo             |
| `PATCH` | `/voice/webrtc/calls/:id` | Atualiza estado (atendeu, DTMF, hangup) |

Body de criação WebRTC:

```json theme={null}
{
  "phoneNumberId": "clxx_phone_1",
  "toE164": "+5511999887766",
  "sdkCallId": "telnyx-sdk-call-id-opcional",
  "record": true,
  "amdMode": "disabled"
}
```

***

## Objeto de chamada (resumo do schema)

Campos retornados em `GET /v1/voice/calls/:id`:

```json theme={null}
{
  "id": "clvoice_abc",
  "direction": "OUTBOUND",
  "fromE164": "5511987654321",
  "toE164": "5511999887766",
  "status": "COMPLETED",
  "durationSecs": 87,
  "recordingAvailable": true,
  "recordingId": "rec_xyz",
  "gatherResult": "1",
  "machineDetectionResult": "human",
  "metadata": {
    "record": true,
    "machineDetection": "detect",
    "chargedMinutes": 2
  },
  "chargedAs": "credits",
  "chargeAmount": 245,
  "clientState": "campanha-42"
}
```

Status típicos: `QUEUED` → `INITIATED` → `RINGING` → `ANSWERED` → `COMPLETED` (ou `NO_ANSWER`, `BUSY`, `FAILED`, `CANCELLED`).

***

## Próximos passos

* [IVR e fluxos](/voice-api/como-funciona/ivr-e-fluxos): criar e publicar URA pela API
* [Quick Start](/voice-api/como-funciona/quick-start): primeira ligação
* [Números de telefone](/phone-numbers-api/como-funciona/quick-start): contratar linha com voz e SMS
* [Consulta de preços](/guides/precos/api-de-precos): `GET /v1/pricing`
* [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks): `voice.call.*`