Transcrição de áudio no WhatsApp com IA: responder mensagens de voz automaticamente

Transcrever áudio do WhatsApp com IA são três passos: baixar o arquivo pelo identificador que chega no webhook, mandar para um modelo de transcrição como o Whisper, e tratar o texto resultante como se fosse uma mensagem de texto normal. A dificuldade não está em nenhum desses passos isoladamente — está no que fica entre eles: o formato do áudio, o tempo de processamento e o que fazer quando a transcrição sai ruim.

Passo 1: identificar e baixar o áudio

Quando chega uma mensagem de voz, o webhook entrega um evento do tipo audio, com um identificador de mensagem em vez do conteúdo direto — o áudio em si precisa ser baixado à parte:

function extrairAudio(body) {
  const msg = body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!msg || msg.type !== "audio") return null;

  return { messageId: msg.id, de: msg.from, canal: body.provider };
}

async function baixarAudio(messageId) {
  const r = await fetch(
    `https://us.api-wa.me/${process.env.WAME_KEY}/message/${messageId}/media?format=binary`
  );
  return Buffer.from(await r.arrayBuffer());
}

O parâmetro format decide o formato de retorno: binary devolve o arquivo direto, útil para mandar adiante para a API de transcrição sem conversão intermediária; json (o padrão) devolve em base64, útil se você precisa guardar ou logar antes de processar.

Passo 2: transcrever

import OpenAI from "openai";
import { toFile } from "openai/uploads";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function transcrever(audioBuffer) {
  const arquivo = await toFile(audioBuffer, "audio.ogg");

  const r = await openai.audio.transcriptions.create({
    file: arquivo,
    model: "whisper-1",
    language: "pt",
  });

  return r.text.trim();
}

Passar language: "pt" evita que o Whisper gaste tempo detectando o idioma e reduz erro de transcrição em sotaques regionais — vale fixar quando você já sabe o idioma predominante da sua base de clientes.

Passo 3: tratar como texto normal

A partir daqui, a transcrição segue o mesmo caminho de qualquer chatbot de IA no WhatsApp: vira a entrada do modelo, que responde normalmente.

app.post("/webhook/wame", async (req, res) => {
  res.sendStatus(200); // responda antes de processar — a transcrição leva alguns segundos

  const audio = extrairAudio(req.body);
  if (!audio) return;

  try {
    const buffer = await baixarAudio(audio.messageId);
    const texto = await transcrever(buffer);

    const resposta = await responder(audio.de, texto); // mesma função de qualquer chatbot de texto
    await enviar(audio.de, resposta, audio.canal);
  } catch (e) {
    console.error("falha ao transcrever áudio", audio.de, e);
    await enviar(audio.de, "Não consegui entender o áudio, pode escrever a mensagem?", audio.canal);
  }
});

O que quebra em produção

Áudio curto demais ou só ruído. Um "oi" gravado sem querer, ou um áudio de meio segundo, gera transcrição vazia ou sem sentido. Vale checar o tamanho do texto retornado antes de mandar para o modelo de resposta — abaixo de um limiar mínimo, peça para o cliente repetir.

Formato incompatível. O WhatsApp entrega áudio majoritariamente em OGG/Opus. A maioria dos provedores de transcrição aceita direto, mas se o seu não aceitar, uma conversão com ffmpeg antes de enviar resolve — é uma linha a mais, não um redesenho.

Latência visível. Transcrever e responder leva alguns segundos a mais do que responder texto direto. Mandar um set_typing ou uma confirmação rápida ("ouvindo seu áudio...") enquanto processa evita que o cliente pense que a mensagem não chegou.

Sotaque e ruído de fundo. Transcrição não é perfeita — em ambiente ruidoso ou sotaque forte, o texto pode sair incompleto ou trocado. Isso é motivo a mais para o system prompt do modelo de resposta admitir incerteza em vez de responder com confiança em cima de uma transcrição ruim, no mesmo espírito de quando a IA deve parar de responder.

Respondendo em áudio (opcional)

Se o seu caso pede resposta em voz — acessibilidade, ou um público que prefere áudio a texto — o caminho é o inverso: gerar a fala com uma API de texto-para-voz e enviar como mensagem de áudio:

async function gerarAudioResposta(texto) {
  const r = await openai.audio.speech.create({
    model: "tts-1",
    voice: "alloy",
    input: texto,
  });
  return Buffer.from(await r.arrayBuffer());
}

O envio segue o endpoint de mensagem de áudio da API. Vale reservar isso para casos específicos — soma custo e latência a cada resposta, e a maioria dos atendimentos por texto continua mais rápida de ler do que de ouvir.

Conclusão

Transcrição de áudio não é uma capacidade separada de um chatbot de IA — é uma etapa a mais antes do texto chegar ao modelo. O código de resposta, memória e escalonamento para humano continua o mesmo de um bot de texto; muda só o que acontece entre receber o evento audio no webhook e ter uma string pronta para processar. Feito isso, o resto da arquitetura — RAG, function calling, regras de escalonamento — se aplica sem alteração.