Quick Start

Do zero à primeira ligação na fila em poucos passos. Antes de tudo: contrate um número, deixe ele ativo no workspace (a ligação parte dessa linha) e tenha saldo ou créditos — voz é cobrada por minuto.

Em poucas palavras

Contrate um número e ative ele — é a linha de onde a ligação sai (campo from).
Escolha quem liga e quem recebe (from e to). Ao atender, use type + payload — igual SMS e WhatsApp.
Acompanhe e controle o status pela API ou por webhooks.

Contexto: Introdução. Escopos: Escopos da API Key. Número: Números de Telefone.

Antes de começar

Item	Por quê
Número ativo no workspace	Sem linha contratada e ativa, não há origem para discar
Chave com `voice:call`	Permissão para originar ligações
`voice:read` / `voice:control`	Só se vai consultar histórico ou controlar ligação em andamento
Saldo ou créditos	Cobrança por minuto de ligação atendida

Autenticação: Authorization: Bearer sk_live_... ou x-api-key. Base URL: https://api.notifique.dev. Números de destino em formato internacional, só dígitos, sem + (ex.: 5511999887766). A API normaliza internamente.

Estrutura do body (`POST /v1/voice/calls`)

O contrato canônico segue o mesmo padrão dos outros canais: to, type, payload. Campos extras ficam na raiz do JSON ou em options — não dentro de payload.

Campo	Onde vai	O que faz
`from`	Raiz	Número ou id da linha de origem (ativo no workspace)
`to`	Raiz	Array de destinos (até 500)
`type`	Raiz	`speak`, `play`, `gather`, `ivr` ou `template`
`payload`	Raiz	Conteúdo conforme o `type` (texto, áudio, menu de teclas, URA…)
`record`	Raiz	`true` grava a ligação (sobretaxa por minuto)
`amdMode`	Raiz	Detecção de caixa postal: `disabled`, `detect` ou `premium`
`clientState`	Raiz	Texto seu para correlacionar com CRM ou fila (volta nos webhooks)
`metadata`	Raiz	Tags da campanha (chave-valor, strings)
`localization` / `i18n`	Raiz	Traduzir texto falado ou prompt de teclas
`options.webhook`	Dentro de `options`	URL HTTPS só para esta chamada
`schedule`	Raiz	Só no painel hoje — ver seção 7

A API ainda aceita aliases legados na raiz (speakText, playAudioUrl, gather solto), mas prefira type + payload — é o padrão documentado e igual aos outros canais.

1. Fazer uma ligação

1A — Pelo painel

Voz → Nova chamada
De qual número você vai ligar e quem vai receber
Ao atender: mensagem automática (texto ou áudio) ou chamada ao vivo (WebRTC)
Opcional: traduzir, agendar, gravar ou webhook só desta chamada
Dispare (ou agende)

URA pelo painel foi descontinuada — use type: ivr na API (IVR e fluxos).

1B — Pela API v1

Escopo: voice:call. Exemplo completo — falar texto, gravar, correlacionar com CRM, webhook só desta chamada e metadados:

POST /v1/voice/calls
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "speak",
  "payload": {
    "text": "Olá! Esta é uma ligação de teste do Notifique.",
    "voice": "female-natural"
  },
  "record": false,
  "amdMode": "disabled",
  "clientState": "campanha-verificacao-42",
  "metadata": {
    "orderId": "8842",
    "source": "checkout"
  },
  "options": {
    "webhook": {
      "url": "https://api.suaempresa.com/hooks/voice-pedido-8842",
      "secret": "whsec_opcional"
    }
  }
}

Resposta 202:

{
  "success": true,
  "data": {
    "messageIds": ["clvoice1..."],
    "status": "QUEUED",
    "count": 1
  }
}

Guarde os messageIds para consultar e controlar cada destino. Outros type e payload (mesma estrutura — só muda type e o conteúdo de payload):

O que você quer	`type`	`payload`
Falar texto (TTS)	`speak`	`{ "text": "...", "voice": "female-natural" }`
Tocar áudio por URL	`play`	`{ "audioUrl": "https://cdn.../aviso.mp3" }`
Menu “pressione 1, 2…”	`gather`	`{ "gather": { "prompt": "...", "maxDigits": 1, "timeoutSecs": 15 } }`
URA publicada	`ivr`	`{ "flowId": "flow_abc123" }`

from aceita id do número no workspace ou E.164 — precisa estar ativo.

2. Listar e consultar

GET /v1/voice/calls?page=1&limit=20&direction=OUTBOUND
Authorization: Bearer sk_live_xxxxx

GET /v1/voice/calls/:id?includeEvents=true
Authorization: Bearer sk_live_xxxxx

Escopo: voice:read. Com includeEvents=true, a resposta traz a linha do tempo (discou, atendeu, encerrou…).

3. Controlar ligação em andamento

POST /v1/voice/calls/:id/actions/{action} — escopo voice:control. A ligação precisa estar atendida.

POST /v1/voice/calls/clvoice1.../actions/speak
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "text": "Pressione 1 para vendas ou 2 para suporte.",
  "voice": "female-natural"
}

Ação	O que faz
`speak`	Fala texto (TTS)
`play`	Toca áudio por URL
`gather`	Pede que o cliente pressione teclas
`transfer`	Transfere para outro número
`record-start` / `record-stop`	Grava um trecho
`dtmf`	Envia tons
`hangup`	Encerra

4. Baixar gravação

GET /v1/voice/calls/:id/recordings/latest/download
Authorization: Bearer sk_live_xxxxx

Escopo: voice:read. Webhook: voice.call.recording.ready.

5. Chamadas recebidas (inbound)

Quando alguém liga para o seu número, configure a linha em Números de Telefone: encaminhar, falar mensagem e encerrar, ou controle via webhook.

6. Webhooks globais vs webhook desta chamada

Globais — cadastre no workspace os eventos voice.call.* (Eventos dos webhooks). Só desta chamada — use options.webhook no body (HTTPS pública + secret opcional). Os eventos desta ligação vão para essa URL em vez dos webhooks globais do workspace para essa chamada.

7. Agendar discagem

Painel — chip Agendar na Nova chamada (plano pago, dentro do limite de dias do workspace). A rota API v1 POST /v1/voice/calls ainda não aceita schedule — agendamento por API de voz está no roadmap alinhado aos outros canais. No painel, o body usa campos legados (speakText na raiz); na API v1, use sempre type: "speak" e payload.text.

8. Traduzir o texto falado

Na raiz do body, igual SMS e e-mail:

{
  "from": "5511987654321",
  "to": ["5511999887766", "14155552671"],
  "type": "speak",
  "payload": {
    "text": "Olá! Sua entrega chega hoje.",
    "voice": "female-natural"
  },
  "localization": { "mode": "ai", "sourceLocale": "pt-BR" }
}

Modo manual — textos por idioma em i18n (chaves speakText e gatherPrompt):

{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "gather",
  "payload": {
    "gather": {
      "prompt": "Pressione 1 para confirmar.",
      "maxDigits": 1,
      "timeoutSecs": 15
    }
  },
  "localization": { "mode": "manual", "sourceLocale": "pt-BR" },
  "i18n": {
    "en": {
      "speakText": "Hello! Your delivery arrives today.",
      "gatherPrompt": "Press 1 to confirm."
    }
  }
}

Detalhes: Localização e i18n.

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)

Voz

Voice: Chamadas

Voice: Fluxos IVR

Números de telefone

Números de Telefone

Em poucas palavras

Antes de começar

Estrutura do body (`POST /v1/voice/calls`)

1. Fazer uma ligação

1A — Pelo painel

1B — Pela API v1

2. Listar e consultar

3. Controlar ligação em andamento

4. Baixar gravação

5. Chamadas recebidas (inbound)

6. Webhooks globais vs webhook desta chamada

7. Agendar discagem

8. Traduzir o texto falado

Vozes TTS

Próximos passos

​Em poucas palavras

​Antes de começar

​Estrutura do body (POST /v1/voice/calls)

​1. Fazer uma ligação

​1A — Pelo painel

​1B — Pela API v1

​2. Listar e consultar

​3. Controlar ligação em andamento

​4. Baixar gravação

​5. Chamadas recebidas (inbound)

​6. Webhooks globais vs webhook desta chamada

​7. Agendar discagem

​8. Traduzir o texto falado

​Vozes TTS

​Próximos passos

Em poucas palavras

Antes de começar

Estrutura do body (`POST /v1/voice/calls`)

1. Fazer uma ligação

1A — Pelo painel

1B — Pela API v1

2. Listar e consultar

3. Controlar ligação em andamento

4. Baixar gravação

5. Chamadas recebidas (inbound)

6. Webhooks globais vs webhook desta chamada

7. Agendar discagem

8. Traduzir o texto falado

Vozes TTS

Próximos passos