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.
Com o SDK Node
Od-api-sdk faz os passos abaixo
por você. A ligação usa a mesma interface das chamadas de WhatsApp:
{ 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
ChamePOST /voice/live/start com o número de destino (com DDI, apenas dígitos).
Identificador da ligação. É o mesmo
callId dos webhooks e da
gravação.URL opaca do WebSocket, com
callId e token já embutidos. Abra-a
exatamente como veio — não monte a URL você mesmo.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.Passo 2 — Conecte ao WebSocket
A ligação já foi discada quando a resposta chega. Abra awsUrl em até
30 segundos: se o WebSocket não conectar nesse prazo, a ligação é desligada e
a reserva de saldo é devolvida.
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.
- Servidor (robô / agente de IA)
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.Reamostragem (8, 16, 24, 48 kHz...)
Reamostragem (8, 16, 24, 48 kHz...)
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.μ-law (G.711 PCMU) ⇄ PCM
μ-law (G.711 PCMU) ⇄ PCM
Ler o áudio recebido com segurança
Ler o áudio recebido com segurança
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:
Gravar o PCM recebido como WAV
Gravar o PCM recebido como WAV
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.reason do evento ended:
Passo 5 — Controle a ligação
Mutar / desmutar
Mutar / desmutar
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.Desligar
Desligar
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/startreserva o valor demin(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
acceptedaté 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
(
endedcomreason: "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: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 canalvoice 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.call.audio traz os mesmos arquivos do evento recording do WebSocket:
Erros e limites
O stream de voz está indisponível no momento. Tente novamente mais tarde.
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.
