Início › Tutoriais › Transcrever áudio para agente de IA
Seu agente de IA não escuta áudio. Isso resolve em uma chamada.
Medido em produção: um áudio de 4 segundos volta transcrito em ~1,2 segundo. Teto padrão de 500 minutos por mês e 300 segundos por áudio.
Por que o agente ignora áudio
O webhook de um áudio recebido traz a URL do arquivo, o mime type e a duração — nada de texto. Um agente de IA recebe isso e não tem o que responder, porque modelo de linguagem lê texto, não escuta arquivo. A saída de sempre é montar um pipeline: baixar o arquivo, mandar para um serviço de speech-to-text, esperar, juntar com o resto da conversa e só então chamar o modelo. É trabalho que não tem nada a ver com o produto que você está construindo.
Ligando em uma chamada
curl -X PUT "https://wafly.com.br/api-bridge-whats/instances/SUA_INSTANCIA/token/SEU_TOKEN/ai-config" \
-H "Client-Token: SEU_CLIENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider": "openai",
"api_key": "sk-proj-...",
"transcription": { "enabled": true }
}'Ou, sem código: painel → sua instância → aba Webhooks → card "Transcrever áudio".
A chave é gravada criptografada, vinculada à instância, e nunca é devolvida por nenhuma API — no GET ela vem mascarada.
O que chega no webhook
O payload de áudio continua o mesmo. Ganha um campo:
{
"phone": "5511999999999",
"audio": {
"audioUrl": "https://storage.googleapis.com/.../audio.oga",
"mimeType": "audio/ogg; codecs=opus",
"seconds": 4
},
"transcription": {
"status": "ok",
"text": "oi, queria saber o preço do plano",
"provider": "openai",
"latency_ms": 1180
}
}Seu agente lê transcription.text e responde como se fosse mensagem escrita. Instância sem a transcrição ligada não recebe nem o campo — nada muda para quem não usa.
Custo e limites
A chave é sua e a fatura é sua. A Wafly não intermedia cobrança nem aplica markup: você cadastra sua chave da OpenAI e paga o preço de tabela dela, direto. Dois limites protegem você de surpresa:
| Campo | Padrão | O que faz |
|---|---|---|
max_audio_seconds | 300 | Áudios mais longos são ignorados. |
monthly_minutes_cap | 500 | Teto de minutos por mês. Ao atingir, a transcrição para até o mês virar. |
Se você não informar o teto mensal, aplicamos 500 minutos por padrão. É deliberado: deixar ilimitado faria você descobrir o custo pela fatura do provedor, e isso é o tipo de surpresa que ninguém quer.
O consumo do mês aparece no GET e no painel.
Quando o provedor falha
A mensagem nunca se perde. Se a OpenAI recusar ou o teto for atingido, o webhook sai igual ao de sempre, só com o motivo:
"transcription": { "status": "error", "reason": "quota_exceeded" }Motivos possíveis: invalid_api_key, quota_exceeded, cap_reached, audio_too_long, provider_timeout.
Teste com o seu agente
Instância conectada por QR em ~2 minutos, transcrição ligada com um curl. 3 dias grátis, sem cartão.
Perguntas frequentes
Como transcrever áudio do WhatsApp automaticamente?
Ligando a transcrição na instância: a plataforma baixa o áudio recebido, envia para o speech-to-text da OpenAI e entrega o texto no mesmo webhook da mensagem, no campo transcription. Você não monta download nem pipeline.
Quanto custa transcrever áudio do WhatsApp?
O custo é o da própria OpenAI, cobrado direto na sua conta, porque a chave é sua. A Wafly não cobra nada a mais e não aplica markup.
O agente de IA consegue entender áudio no WhatsApp?
Não diretamente — modelos de linguagem recebem texto. Com a transcrição ligada na camada da API, o áudio chega já convertido e o agente responde como se fosse uma mensagem escrita.
Funciona com n8n, Dify, Flowise ou LangChain?
Com qualquer coisa que receba webhook: a transcrição acontece antes de sair da Wafly. No n8n existe a operação Set Audio Transcription no node oficial.
Precisa ser OpenAI?
Hoje sim. O campo provider existe para outros provedores entrarem sem quebrar quem já usa.
A minha chave fica segura?
Ela é gravada com criptografia autenticada e vinculada à instância, então o registro não funciona se for copiado para outra. Nunca é devolvida por API nem gravada em log — no GET vem mascarada.
Continue
OpenAI é marca de seus respectivos detentores, sem relação com a Wafly. Encontrou algo impreciso? Fale com a gente que corrigimos.