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

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.

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 (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[]:

{
  "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.

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.

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`)

{
  "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`)

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

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.

machineDetection ainda é aceito na API v1 por compatibilidade (detect, premium, etc.), mas prefira amdMode.

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

{
  "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)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clvoice_01...", "clvoice_02..."],
    "voiceCallIds": ["clvoice_01...", "clvoice_02..."]
  }
}

Exemplo — reproduzir áudio

{
  "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). 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:

{
  "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:

{
  "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: criar e publicar URA pela API
Quick Start: primeira ligação
Números de telefone: contratar linha com voz e SMS
Consulta de preços: GET /v1/pricing
Eventos dos webhooks: voice.call.*

API E-mail

E-mail

Domínios

E-mails recebidos

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

Em poucas palavras

Preço dinâmico por país

Como estimar antes de ligar (painel)

Opções `record` e `amdMode`

`record` (gravação)

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

Sobretaxas de voz (`voice.surcharges`)

Tipos de chamada (`type`)

Exemplo completo — speak + gather + AMD

Exemplo — reproduzir áudio

Dashboard modes

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

Chamada ao vivo (WebRTC) — rotas de app

Objeto de chamada (resumo do schema)

Próximos passos

​Em poucas palavras

​Preço dinâmico por país

​Como estimar antes de ligar (painel)

​Opções record e amdMode

​record (gravação)

​amdMode (detecção de caixa postal)

​Sobretaxas de voz (voice.surcharges)

​Tipos de chamada (type)

​Exemplo completo — speak + gather + AMD

​Exemplo — reproduzir áudio

​Dashboard modes

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

​Chamada ao vivo (WebRTC) — rotas de app

​Objeto de chamada (resumo do schema)

​Próximos passos

Em poucas palavras

Preço dinâmico por país

Como estimar antes de ligar (painel)

Opções `record` e `amdMode`

`record` (gravação)

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

Sobretaxas de voz (`voice.surcharges`)

Tipos de chamada (`type`)

Exemplo completo — speak + gather + AMD

Exemplo — reproduzir áudio

Dashboard modes

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

Chamada ao vivo (WebRTC) — rotas de app

Objeto de chamada (resumo do schema)

Próximos passos