Pular para o conteúdo principal
As Ligações URA por Stream deixam o seu aplicativo conversar com um telefone (fixo ou celular) em tempo real: você inicia a ligação por uma chamada HTTP, abre um WebSocket e troca áudio nos dois sentidos — o seu áudio (microfone, robô, agente de IA) vai para o telefone, e a voz de quem atendeu volta para você. O contrato do WebSocket é o mesmo das Ligações de WhatsApp por Stream: mesma URL, mesmo formato de áudio e o mesmo modelo de eventos. Se você já integrou o WhatsApp, reaproveita o código.
Você precisa de saldo na carteira e da API Key da conta. A ligação é cobrada da carteira com a mesma tarifa das ligações URA (veja Cobrança). Gere a sua chave no painel.

Como funciona

1

Inicie a ligação

POST /voice/live/start reserva saldo, disca para o número e retorna um callId e uma wsUrl pronta para abrir.
2

Abra o WebSocket em até 30 segundos

O telefone já está tocando. Frames de texto são eventos; frames binários são áudio.
3

Troque áudio

Envie PCM binário e reproduza (ou processe) o PCM binário recebido.
4

Finalize

Feche o WebSocket para desligar. O valor é debitado pelo tempo falado e a gravação fica disponível.
Por baixo, a D-API disca pela rede de telefonia e faz a ponte entre o telefone e o seu WebSocket, convertendo o áudio da telefonia (8 kHz) para o formato do stream (16 kHz) nos dois sentidos.

Com o SDK Node

O d-api-sdk faz os passos abaixo por você. A ligação usa a mesma interface das chamadas de WhatsApp:
Para o áudio ir por WebRTC, passe { transport: "webrtc" } como segundo argumento de voice.live(); os detalhes estão em URA ao vivo com WebRTC, com o exemplo completo para navegador e Node.

Passo 1 — Inicie a ligação

Chame POST /voice/live/start com o número de destino (com DDI, apenas dígitos).
A resposta traz o identificador da ligação e a URL do stream:
string
Identificador da ligação. É o mesmo callId dos webhooks e da gravação.
string
URL opaca do WebSocket, com callId e token já embutidos. Abra-a exatamente como veio — não monte a URL você mesmo.
string
Token de acesso exclusivo desta ligação, gerado a cada chamada. Já está dentro da wsUrl. Ele não é a sua API Key: só abre o WebSocket desta ligação e deixa de valer quando ela termina.
A sua API Key nunca deve ir ao navegador. Inicie a ligação pelo seu backend e entregue ao navegador apenas a wsUrl — ela carrega só o token da ligação. Mesmo assim, trate a wsUrl como um segredo de curta duração (não registre em logs) enquanto a ligação está ativa.
Um exemplo de início pelo backend, que mantém a chave fora do navegador:

Passo 2 — Conecte ao WebSocket

A ligação já foi discada quando a resposta chega. Abra a wsUrl em até 30 segundos: se o WebSocket não conectar nesse prazo, a ligação é desligada e a reserva de saldo é devolvida.
Não há handshake pós-conexão: a autenticação está na URL. Se o servidor recusar, ele envia um evento error e fecha a conexão com o código 1008.

Passo 3 — Troque o áudio

O áudio no WebSocket é PCM cru (s16le, 16 kHz, mono), em frames de 20 ms = 320 amostras = 640 bytes, nos dois sentidos. Veja a seção Encoding de áudio para converter de/para outros formatos.
No navegador o caminho é idêntico ao da ligação de WhatsApp: rode o AudioContext a sampleRate: 16000 (o navegador reamostra o microfone para você) e converta Float32 ⇄ Int16 num AudioWorklet. Use o worklet voip-worklet.js de referência da página Ligações de WhatsApp por Stream sem nenhuma alteração.
Mantenha echoCancellation: true. Na telefonia o eco do alto-falante voltando pelo microfone é muito perceptível para quem está no telefone.
Não envie áudio antes do evento accepted. Antes disso o telefone ainda está tocando e o áudio é descartado.

Encoding de áudio

A rede de telefonia trafega voz em banda estreita: 8 kHz, normalmente em G.711 (μ-law/A-law), com conteúdo útil até ~3,4 kHz. A D-API cuida dessa ponta e entrega para você sempre o mesmo formato do stream de WhatsApp: Isso significa que você nunca envia μ-law, A-law, base64, WAV, MP3 ou Opus pelo WebSocket — só PCM cru de 16 kHz. Se o seu sistema trabalha em outro formato, converta na sua ponta antes de enviar e depois de receber.
O áudio recebido do telefone vem em 16 kHz, mas o conteúdo é de telefonia: não há nada acima de ~3,6 kHz. Isso é esperado — não é perda na D-API.

Conversões mais comuns

Arquivos, com ffmpeg:

Funções de referência (Node.js)

Implementações sem dependências para converter em tempo real, frame a frame.
Reamostrador linear com estado entre frames (sem estalos na emenda). Para reduzir a taxa, ele aplica antes uma média móvel simples como filtro passa-baixa. É suficiente para voz de telefonia; para qualidade de estúdio, use ffmpeg/libsoxr.
Não assuma que todo frame recebido tem exatamente 640 bytes. Acumule os bytes e leia sempre um número par de bytes, em little-endian:
Para enviar um WAV, descarte o cabeçalho (normalmente os 44 primeiros bytes) e confira que ele já é 16 kHz, mono, 16 bits — senão converta com ffmpeg.

Diagnóstico de problemas de áudio

Passo 4 — Acompanhe o ciclo de vida

Os frames de texto do WebSocket são eventos JSON no formato { "type": ... }.
Diferente do WhatsApp, a telefonia não emite calling nem ringing: entre a resposta do POST /voice/live/start e o accepted, o telefone está tocando. Uma ligação não atendida (ocupado, sem resposta, recusada) termina com ended sem ter passado por accepted.
O reason do evento ended:

Passo 5 — Controle a ligação

Na URA o mute é do seu lado: pare de enviar frames de áudio (ou envie silêncio). O controle { "type": "mute" } do WhatsApp é ignorado aqui.
Fechar o WebSocket desliga a ligação. Você também pode enviar um controle por texto:

Cobrança

A ligação é paga com o saldo da carteira, na mesma tarifa das ligações URA do seu plano (30/6: primeiro bloco de 30 segundos, depois blocos de 6 segundos).
  • Reserva no início. O POST /voice/live/start reserva o valor de min(duração máxima, tempo que o seu saldo cobre). Sem saldo para o primeiro bloco de 30 segundos, a resposta é 402.
  • Cobrança pelo tempo falado. Conta do evento accepted até o fim. Ligações não atendidas e falsos atendimentos (false-answer) não são cobrados.
  • Corte automático. Quando o tempo reservado acaba, a ligação é desligada (ended com reason: "hangup"). Para ligações longas, mantenha saldo suficiente antes de discar.
  • Devolução da sobra. Ao encerrar, a parte não usada da reserva volta para o saldo disponível — inclusive se o WebSocket nunca conectar.

Reconexão (opcional)

Funciona como no WhatsApp: adicione &resume=1 à wsUrl e uma queda do socket não desliga a ligação — ela aguarda você reconectar com a mesma wsUrl por até 20 segundos. O tempo continua contando (e sendo cobrado) enquanto o socket está fora. Veja o exemplo de reconexão em Ligações de WhatsApp por Stream.

Gravação

Toda ligação atendida é gravada. Perto do fim, o servidor envia:
Os arquivos são WAV mono de 16 kHz: full é a mixagem, sender é o seu lado e recipient é o telefone. A gravação também fica disponível depois em GET /api/v1/calls/:callId. Contas com armazenamento de mídia desativado não têm gravação.

Webhooks

As ligações por stream disparam os mesmos eventos do webhook de conta do canal voice que as demais ligações URA, além de um evento com a gravação. O data.callId é o mesmo callId retornado por POST /voice/live/start — é ele que relaciona a resposta, o WebSocket, os webhooks e a gravação. Em ligações por stream, bulkCallId vem sempre null.
Em ligações por stream, cause e causeDescription vêm null: o motivo do encerramento chega pelo reason do evento ended no WebSocket. Falsos atendimentos encerram com answered: false e não são cobrados.
O call.audio traz os mesmos arquivos do evento recording do WebSocket:

Erros e limites

Saldo insuficiente para o primeiro bloco de 30 segundos (code: "insufficient_balance").
A operadora recusou a ligação (code: "gateway_error"). Nada é cobrado e a reserva é devolvida.
O stream de voz está indisponível no momento. Tente novamente mais tarde.
30 s
Prazo para abrir a wsUrl depois do início. Passou, a ligação é desligada.
3600 s
Ou menos, se o saldo cobrir menos tempo. Ao atingir, a ligação encerra.
Os eventos error trazem um code: unavailable, not_found, unauthorized ou forbidden.

Próximos passos

Ligações de WhatsApp por Stream

O mesmo WebSocket para chamadas de voz do WhatsApp, com o worklet de referência.

Referência da API

Autenticação e todos os endpoints da D-API.