> ## 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                      | Em português claro                                                 |
| ----------------------------- | ------------------------------------------------------------------ |
| **Minuto de saída**           | Você liga para o cliente — preço depende do país do número discado |
| **Minuto de entrada**         | Cliente liga para você — preço depende do país de quem ligou       |
| **Chamada ao vivo (WebRTC)**  | Conversa pelo navegador no painel — adicional por minuto           |
| **Gravar ligação** (`record`) | Opcional — sobretaxa por minuto gravado                            |
| **Caixa postal** (`amdMode`)  | Opcional — detecta se atendeu humano ou secretária eletrônica      |

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"
  }
}
```

***

## Modos no painel (dashboard)

A tela **Nova chamada** expõe dois modos de discagem e três chips de opções:

| Modo                    | Equivalente API                     | Observação                                           |
| ----------------------- | ----------------------------------- | ---------------------------------------------------- |
| **Mensagem automática** | `type: speak` (+ `gather` opcional) | TTS após atender; chips Tradução, Agendar e Avançado |
| **Chamada ao vivo**     | WebRTC (`POST /voice/webrtc/calls`) | Um destino; minuto saída + WebRTC; AMD desligado     |

| Chip         | O que envia                                               |
| ------------ | --------------------------------------------------------- |
| **Tradução** | `localization` + `i18n` (`speakText`, `gatherPrompt`)     |
| **Agendar**  | `schedule.sendAt` (planos pagos)                          |
| **Avançado** | `record`, `amdMode`, voz TTS, `gather`, `options.webhook` |

**URA / IVR** não é mais criada pelo painel — use `POST /v1/voice/flows` + `type: ivr` na API ([IVR e fluxos](/voice-api/como-funciona/ivr-e-fluxos)).

O painel mostra o **preço estimado por minuto** conforme o destino e o modo (PSTN vs WebRTC).

***

## Agendamento, localização e webhook (`POST /v1/voice/calls`)

Campos opcionais na raiz do body (API v1 e painel, exceto onde indicado):

| Campo                       | Uso                                                                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule.sendAt`           | ISO 8601 — discagem futura (**painel** `POST /voice/calls`; plano pago). **API v1** `POST /v1/voice/calls` ainda não aceita agendamento. |
| `localization.mode`         | `off` \| `manual` \| `ai`                                                                                                                |
| `localization.sourceLocale` | Locale do texto fonte (ex.: `pt-BR`)                                                                                                     |
| `i18n`                      | Mapa locale → `{ speakText, gatherPrompt? }` em `manual`                                                                                 |
| `options.webhook.url`       | HTTPS — eventos `voice.call.*` **só desta chamada**                                                                                      |
| `options.webhook.secret`    | Segredo HMAC opcional                                                                                                                    |
| `metadata`                  | Pares string gravados no registro da chamada                                                                                             |

Exemplo combinado:

```json theme={null}
{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": { "text": "Confirme sua consulta pressionando 1." },
  "gather": {
    "prompt": "Pressione 1 para confirmar.",
    "maxDigits": 1,
    "timeoutSecs": 15
  },
  "record": false,
  "amdMode": "disabled",
  "schedule": { "sendAt": "2026-12-01T15:00:00.000Z" },
  "localization": { "mode": "ai", "sourceLocale": "pt-BR" },
  "options": {
    "webhook": {
      "url": "https://hooks.suaempresa.com/voice/consulta-42",
      "secret": "whsec_..."
    }
  },
  "metadata": { "campaignId": "consultas-dez" }
}
```

Resposta **202** com agendamento: `data.status` pode ser `SCHEDULED` e `data.scheduledAt` traz o horário. Com localização IA: `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.*`