áudio em tempo real
Stream de áudio da ligação de WhatsApp: PCM em tempo real no seu backend
O stream de áudio da ligação de WhatsApp entrega a voz da chamada ao seu backend em PCM de 16 kHz por WebSocket, e aceita o seu áudio de volta, para transcrever, gravar ou pôr um agente de IA para conversar.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Formato sem surpresa
PCM s16le, 16 kHz, mono, frames de 20 ms (320 amostras, 640 bytes), igual nos dois sentidos.
Texto é evento, binário é áudio
No mesmo socket, frames de texto contam o ciclo de vida e frames binários carregam a voz.
Sobrevive a queda de rede
Com resume=1, a chamada aguarda até 20 segundos pela reconexão e reenvia os eventos desde o início.
Mesmo socket para entrada e saída
Atender uma chamada recebida devolve uma wsUrl idêntica à da ligação de saída. Um código serve os dois.
O stream de áudio da ligação de WhatsApp é a peça que deixa o seu produto ouvir e falar numa chamada sem nenhum hardware de telefonia. A chamada sai ou entra no número do seu cliente, e o áudio dela vira um WebSocket comum: frames binários com a voz do contato chegando, frames binários com a sua voz indo. Um SaaS de atendimento usa isso para levar a chamada ao navegador; um SaaS de IA usa para transcrever em tempo real e responder com voz sintetizada.
Esta página documenta o protocolo do ponto de vista de quem integra, com as decisões que evitam áudio picotado e chamadas derrubadas. A visão geral do recurso está em ligações WhatsApp API.
De onde vem a wsUrl
Duas rotas devolvem o socket de mídia, com o mesmo formato de resposta:
POST /api/v1/calls/stream, para uma ligação de saída ao vivo. Detalhes em fazer ligações de WhatsApp pela API.POST /api/v1/calls/accept, para atender uma chamada recebida. Detalhes em receber ligações de WhatsApp pela API.
A resposta traz callId, wsUrl e token. A wsUrl é opaca e já carrega callId e token: abra exatamente como veio, sem montar a URL. O token é exclusivo daquela chamada, gerado a cada uma, e deixa de valer quando ela termina. Mesmo assim, trate a wsUrl como segredo de curta duração e não a registre em log.
O formato do stream de áudio
Todo o áudio, nos dois sentidos, segue um formato só:
| Propriedade | Valor |
|---|---|
| Codificação | PCM s16le (inteiro de 16 bits com sinal, little-endian) |
| Taxa de amostragem | 16.000 Hz |
| Canais | 1 (mono) |
| Frame | 320 amostras = 640 bytes = 20 ms |
| Transporte | Frames binários do WebSocket, sem base64 |
Dois cuidados fazem a diferença na prática. Primeiro, envie em cadência de tempo real, um frame a cada cerca de 20 ms, sem acumular e despejar em lote. Segundo, não envie áudio antes do evento accepted: até ali, o outro lado não está ouvindo.
No navegador, rodar o AudioContext com sampleRate: 16000 faz o próprio navegador reamostrar o microfone, e cada frame do worklet já sai no formato do stream. Se você montar o seu player, não reinicie o pré-buffer a cada amostra que faltar: no WebSocket, frame atrasado é comum, e cada reinício vira cerca de 100 ms de silêncio. A implementação de referência do worklet usa cerca de 150 ms de pré-buffer e descarta o áudio mais antigo quando a latência passa de cerca de 500 ms.
O ciclo de vida no mesmo socket
Frames de texto são JSON no formato { "type": ... }:
type |
Significado | O que o seu código faz |
|---|---|---|
calling |
Discagem iniciada | Mostra “chamando” |
ringing |
O telefone do contato está tocando | Mostra “tocando” |
accepted |
Atendeu, áudio ao vivo | Libera o envio de áudio |
connected |
Alias de accepted |
Igual a accepted |
recording |
Gravação disponível | Guarda url e files |
ended |
Chamada encerrada, com reason |
Encerra e limpa |
error |
Falha, com code e msg |
Mostra o erro e limpa |
O reason do ended inclui hangup, rejected, timeout, accepted_elsewhere, terminate (duração máxima atingida) e ws_closed, entre outros. Se o socket fechar sem ended, trate como encerramento.
O socket também recebe comandos: { "type": "mute", "muted": true } silencia o áudio enviado e { "type": "hangup" } desliga. Fechar o socket também desliga, porque o servidor interpreta o fechamento como hangup.
Um consumidor no backend
O exemplo abaixo é o núcleo de um agente de voz ou de um transcritor: abre a wsUrl, entrega o áudio do contato ao seu motor de fala e devolve a voz sintetizada no ritmo certo.
// Node.js 18+ (npm i ws)
import WebSocket from "ws";
function conectarMidia(wsUrl, motor) {
const ws = new WebSocket(`${wsUrl}&resume=1`);
let podeFalar = false;
ws.on("message", (data, isBinary) => {
if (isBinary) return motor.ouvir(data); // PCM s16le 16 kHz, 640 bytes = 20 ms
const msg = JSON.parse(data.toString());
if (msg.type === "accepted" || msg.type === "connected") podeFalar = true;
if (msg.type === "recording") salvarGravacao(msg.files);
if (msg.type === "ended" || msg.type === "error") ws.close(1000);
});
// a fala sintetizada sai em frames de 640 bytes, um a cada 20 ms
motor.on("frame", (pcm) => {
if (podeFalar && ws.readyState === WebSocket.OPEN) ws.send(pcm);
});
}
Para quem usa o d-api-sdk no Node, a mesma coisa vira call.on("audio", frame => ...) e call.sendAudio(pcm), com frames de 20 ms em Int16Array e reconexão já tratada. O artigo sobre agentes de IA no WhatsApp mostra como encaixar o modelo nesse fluxo.
Reconexão sem perder a ligação
Por padrão, se o WebSocket cair, o servidor desliga a chamada. Para manter a ligação durante uma oscilação de rede ou um deploy do seu serviço, acrescente &resume=1 à wsUrl. Com ele:
- Uma queda do socket não desliga: a chamada fica ativa aguardando reconexão por até 20 segundos.
- Você reconecta com a mesma
wsUrl, e o servidor reenvia os eventos desde o início (calling,ringing,accepted…). Ignore os que já tratou. - O servidor pode fechar com código
1012durante um reinício dele; trate como queda e reconecte. - Para desligar de propósito, feche com
1000ou envie{ "type": "hangup" }. Qualquer outro fechamento conta como queda. - A gravação cobre a ligação inteira, com silêncio no intervalo em que o socket esteve fora.
Para um SaaS que roda o consumidor em várias réplicas, isso é o que permite publicar versão nova no meio do expediente sem cortar a ligação de ninguém.
Gravação ao final
No stream de saída e na chamada recebida atendida, a gravação é feita por padrão. Perto do fim, o socket recebe:
{
"type": "recording",
"files": { "full": "https://...", "sender": "https://...", "recipient": "https://..." },
"url": "https://..."
}
São WAV mono de 16 kHz: full é a mixagem, sender o lado da sessão e recipient o contato. Faixas separadas facilitam transcrever cada lado sem diarização. Nas ligações por /calls/stream, a mesma gravação também chega pelo webhook call.audio, e fica disponível depois em GET /api/v1/calls/{callId}. Para não gravar uma ligação de saída, envie "record": false no /calls/stream.
Quando preferir WebRTC
O WebSocket roda sobre TCP, o que é ótimo para um servidor numa rede estável e pior para um atendente no Wi-Fi do consultório. No navegador, use o SDK com transport: "webrtc": o áudio vai por UDP com Opus e correção de perda, e volta sozinho para o WebSocket se a rede bloquear. Os detalhes estão em ligação de WhatsApp no navegador com WebRTC.
O protocolo completo, com o worklet de referência para o navegador, está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O áudio vem em base64?
No WebSocket da chamada, não. O áudio trafega em frames binários de PCM cru, sem base64. Base64 aparece só no webhook call.audio da ligação por /calls/place com recordAudio, que entrega pedaços de cerca de 1 segundo.
Posso mandar o áudio todo de uma vez?
Não é recomendado. Envie em cadência de tempo real, um frame de 20 ms a cada cerca de 20 ms. Rajadas grandes ficam enfileiradas e chegam atrasadas na chamada inteira.
Como sei que posso começar a falar?
Espere o evento accepted, ou connected, que é o mesmo. Antes disso o outro lado ainda não está ouvindo e o áudio enviado é descartado.
Quais erros chegam pelo socket?
Eventos error trazem um code: unavailable, not_found, unauthorized ou forbidden. Se o servidor recusar a conexão, ele envia o error e fecha o socket.
WebSocket ou WebRTC?
No navegador, prefira WebRTC pelo d-api-sdk, que aguenta melhor rede ruim. No servidor, o WebSocket em PCM é o caminho mais simples para alimentar transcrição e síntese de voz.