Enviar áudio como mensagem de voz e vídeo redondo pela API do WhatsApp

Pela API não oficial do WhatsApp você envia áudio como mensagem de voz com um POST /message/audio — ele chega com a onda sonora e o microfone, igual a um áudio gravado no app — e manda vídeo redondo (o PTV, aquele circular) com POST /message/video-note. Os dois aceitam o arquivo por URL, o áudio também aceita base64, e dá para mostrar "gravando áudio..." antes do envio para a mensagem chegar com a naturalidade de uma pessoa.

No Brasil, áudio é linguagem nativa do WhatsApp. Muita gente prefere ouvir a ler, e uma mensagem de voz bem colocada — de boas-vindas, de instrução, de confirmação — tem um efeito que texto nenhum tem. Este guia mostra como enviar os dois formatos, quando cada um faz sentido e os cuidados para o recurso não virar ruído.

A camada não oficial não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Áudio de voz vs arquivo de áudio

Existe uma diferença que o usuário percebe na hora:

• Mensagem de voz (PTT, Push-To-Talk): aparece com a onda sonora, a foto do remetente e o ícone de microfone. É o áudio "gravado na hora". O app toca em sequência, acelera em 1,5x e 2x, e o contato trata como conversa.
• Arquivo de áudio: aparece como anexo, com nome de arquivo. Tem cara de material enviado, não de fala.

Na API não oficial da WAME, o endpoint /message/audio envia como mensagem de voz. Você não precisa converter nada nem marcar flag nenhuma: manda a URL do mp3 ou do ogg e o contato recebe um áudio de voz.

Enviar áudio por URL

O caminho mais simples é hospedar o arquivo num lugar acessível por HTTPS (seu storage, um CDN, um bucket) e passar a URL:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/audio" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "url": "https://seu-cdn.com/audios/boas-vindas.mp3"
  }'

Três cuidados práticos com a URL:

• Tem de ser pública e direta. Link de página de compartilhamento (Google Drive, Dropbox com tela de preview) não serve: a API precisa baixar o arquivo, não uma página HTML.
• Responda rápido. Um servidor lento na hora do download atrasa o envio.
• Áudio curto funciona melhor. Mensagem de voz boa tem de 15 a 60 segundos. Áudio de cinco minutos ninguém escuta até o fim.

O mesmo to aceita grupo ([email protected]), então dá para mandar a instrução de voz direto no grupo de uma turma ou equipe.

Enviar áudio em base64

Quando o áudio nasce dentro do seu sistema — gerado por síntese de voz, gravado num painel de atendimento, recebido de outra integração — não vale a pena subir para um storage só para gerar uma URL. Use o endpoint de base64:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/base64/audio" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "base64": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4..."
  }'

Aqui a API converte o áudio para o formato que o WhatsApp usa em mensagem de voz antes de enviar. Isso resolve o problema clássico de quem monta a integração do zero: gerar ogg/opus no formato exato que o app aceita.

Em Node.js, lendo um arquivo local:

import { readFile } from 'node:fs/promises';

const BASE = 'https://us.api-wa.me/SUA_KEY';

async function enviarAudioLocal(to, caminho) {
  const base64 = (await readFile(caminho)).toString('base64');

  const res = await fetch(`${BASE}/message/base64/audio`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ to, base64 }),
  });

  if (!res.ok) throw new Error(`falha no envio: ${res.status}`);
  return res.json();
}

await enviarAudioLocal('5511999999999', './audios/confirmacao.mp3');

Mostrar "gravando áudio..." antes

Quando uma pessoa manda um áudio, o outro lado vê "gravando áudio..." no topo da conversa. Um áudio que cai do nada, sem esse sinal, tem cara de automação. O endpoint de presença resolve:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/presence" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "status": "recording" }'

Uma sequência natural fica assim:

async function post(path, body) {
  return fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
}

const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

async function responderComAudio(to, url, duracaoSegundos) {
  await post('/message/presence', { to, status: 'recording' });

  // Um tempo de "gravação" coerente com o tamanho do áudio,
  // com teto para o cliente não ficar esperando demais.
  const ms = Math.min(duracaoSegundos * 400, 8000);
  await esperar(ms);

  await post('/message/audio', { to, url });
  await post('/message/presence', { to, status: 'paused' });
}

Para mensagens de texto, a WAME já mostra "digitando..." sozinha em todo envio, com tempo proporcional ao tamanho do texto. Para áudio, o "gravando" é um toque seu — e vale a pena. O guia completo de presença está em simular "digitando..." pela API.

Vídeo redondo (PTV)

O vídeo redondo é o vídeo curto em formato circular que o usuário grava segurando o botão da câmera. Ele toca automaticamente, sem som, na conversa, e abre com áudio no toque. Tem uma força enorme em relacionamento: é o rosto de alguém falando direto com o cliente.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/video-note" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "url": "https://seu-cdn.com/videos/obrigado.mp4"
  }'

Dicas para o vídeo funcionar bem:

• Curto. Vídeo redondo é para poucos segundos — o formato foi feito para mensagens rápidas, não para aulas.
• Enquadramento quadrado e centralizado. O círculo corta as bordas; rosto no centro, nada importante nos cantos.
• mp4 comum, hospedado com URL direta, como no áudio.

Onde áudio e vídeo redondo funcionam de verdade

A regra de ouro: voz para quem está conversando com você. Alguns usos que encaixam bem:

• Boas-vindas de quem acabou de comprar. Um áudio de 20 segundos do fundador ou do consultor agradecendo e dizendo o próximo passo. O cliente pediu o contato ao comprar; a voz humaniza.
• Instrução de uso. "Para ativar, segure o botão por cinco segundos" é mais claro falado que escrito. Loja de eletrônicos, clínica com preparo de exame, curso com primeiro acesso.
• Confirmação de agendamento com voz da recepção. Combina com lembretes de agendamento.
• Vídeo redondo de agradecimento pós-atendimento. Um corretor, um personal, um professor mostrando o rosto.
• Resposta de bot que ficaria longa em texto. Se o seu bot precisa explicar algo com muitos passos, um áudio gravado uma vez resolve para todos que perguntarem.

E se o cliente responder com áudio? Aí o caminho é o inverso: receber a mensagem de voz no webhook, baixar o arquivo e transcrever. Está em transcrição de áudio no WhatsApp com IA, e o download de mídia está detalhado em mídia no webhook.

Áudio personalizado sem gravar um por um

Áudio genérico funciona, mas áudio com o nome do cliente funciona mais. Duas formas de chegar lá sem ninguém gravar mil áudios:

1. Blocos gravados + texto. Um áudio padrão de boas-vindas seguido de uma mensagem de texto com o nome e o detalhe do pedido. Simples e honesto.
2. Síntese de voz. Gere o áudio com um serviço de TTS a partir de um texto com o nome do cliente e envie pelo endpoint de base64. Se for voz sintética, não finja que é uma pessoa específica gravando — o cliente percebe, e a confiança vai embora.

O cuidado que importa

Áudio e vídeo são formatos que chamam atenção — e é justamente por isso que viram ferramenta de spam na mão errada. A WAME não apoia spam. Mandar o mesmo áudio promocional para uma lista de gente que não pediu é disparo em massa, é denunciado rápido e derruba número, não importa o formato.

Duas proteções já agem do lado da plataforma: a API recusa o envio (com 429) quando a instância começa a falar com gente nova demais em pouco tempo, e cada instância tem identidade de dispositivo própria e reconexão espaçada. Mas o que mantém o risco de bloqueio muito baixo é o uso: áudio para quem está em conversa com você, no momento em que faz sentido. As regras completas estão em uso responsável da API não oficial.

Checklist rápido antes de colocar em produção:

• O áudio vai para quem pediu ou está em conversa?
• Tem menos de um minuto?
• A URL é pública, direta e rápida?
• Você mostra "gravando áudio..." antes?
• Se o cliente responder com áudio, alguém (ou algo) escuta?

Conclusão

Mensagem de voz e vídeo redondo são dois dos formatos mais humanos do WhatsApp, e a API não oficial da WAME entrega os dois do jeito que o usuário conhece: /message/audio sai como áudio de voz, com URL ou base64 convertido automaticamente, e /message/video-note sai como vídeo circular. Somando o "gravando áudio..." antes do envio, a automação soa como gente — que é exatamente o objetivo. Use para quem está conversando com você, mantenha curto e deixe o disparo em massa de fora. Os parâmetros completos estão na documentação, e o panorama do que a camada não oficial oferece está em vantagens da API não oficial do WhatsApp.