Pular para o conteúdo
D-APITestar grátis

á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:

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 1012 durante um reinício dele; trate como queda e reconecte.
  • Para desligar de propósito, feche com 1000 ou 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.