Pular para o conteúdo principal

Áudio recebido — como transcrever

Resumo: Quando um cliente te manda um áudio, você pode pedir ao gateway para transcrever (converter para texto) automaticamente. Útil para clínicas, jurídico e qualquer atendimento onde 30-40% das mensagens vêm em voz.

Quando usar isso​

Cenário comum: paciente manda um áudio de 2 minutos descrevendo sintomas. Atendente fica 2 minutos ouvindo. Com transcrição, o áudio vira texto em segundos, e o atendente lê (mais rápido) ou cola no prontuário.

Outros usos:

  • Cliente descreve problema técnico em áudio — vira ticket de texto pesquisável
  • Cliente envia depoimento — vira documento de texto para arquivo
  • Cliente fala em áudio para o agente IA — IA processa o texto e responde

Como funciona​

A transcrição é um recurso opcional que você ativa por mídia. Os passos:

  1. Cliente manda um áudio (voice note ou arquivo).
  2. O gateway recebe e armazena o áudio temporariamente.
  3. O seu sistema (ou você, manualmente no painel) solicita a transcrição dessa mídia.
  4. O gateway processa o áudio com o Whisper da OpenAI e devolve o texto.
  5. Você recebe o resultado:
    • Via webhook (evento media:transcribed) quando ficar pronto.
    • Via endpoint de consulta se preferir buscar quando quiser.

Custos pequenos por minuto de áudio (paga ao Whisper). O gateway tem cache: se você já transcreveu aquela mídia, a segunda chamada custa zero.

Pré-requisito: OpenAI API Key​

⚠️ Atenção: Para usar transcrição, sua conta no gateway precisa ter uma OpenAI API Key cadastrada. Sem ela, qualquer solicitação retorna erro OPENAI_KEY_NOT_CONFIGURED (HTTP 400). A key é guardada criptografada no banco do gateway.

Como cadastrar a OpenAI key​

  1. Crie uma conta em platform.openai.com.
  2. Vá em API keys e crie uma nova chave (começa com sk-...).
  3. No painel do gateway, em Configurações → Integrações → OpenAI, cole a chave.
  4. Pronto. Pode usar transcrição, OCR e o agente IA na mesma key.

Como solicitar a transcrição​

Pelo painel (manual)​

  1. Abra a conversa onde está o áudio.
  2. Clique no áudio (ou no menu ao lado).
  3. Selecione Transcrever.
  4. Aguarde alguns segundos. A transcrição aparece logo abaixo do áudio na conversa.

Pelo seu sistema (automático)​

O seu sistema dispara automaticamente assim que recebe o webhook message:received com áudio:

  • Chama um endpoint do gateway com o ID da mídia.
  • O gateway retorna imediatamente "PROCESSING" e em segundos dispara o webhook media:transcribed com o texto.

💡 Dica: Se você quer transcrever todo áudio recebido automaticamente, configure isso no seu sistema (ele dispara a transcrição ao receber o áudio). O gateway não tem ainda um modo "auto-transcrever tudo" nativo — é o seu sistema que decide quando.

O que vem na transcrição​

CampoConteúdo
textO texto completo do áudio
languageIdioma detectado (pt, en, es, etc.)
durationSecondsDuração do áudio em segundos
transcribedAtQuando foi processada

Limitações conhecidas​

  • Funciona para áudios em qualquer idioma suportado pelo Whisper (mais de 50 idiomas), mas a precisão é melhor em português e inglês.
  • Áudio com ruído de fundo intenso pode ter erros (paciente em hospital barulhento, criança gritando perto, etc.).
  • Sotaques regionais fortes podem ter mais erros, mas em geral funciona bem para PT-BR.
  • Áudios muito longos (>1 hora) podem demorar 1-2 minutos para processar. O webhook avisa quando fica pronto.
  • Apenas áudios — vídeo com áudio não é transcrito (use OCR para texto em imagem).

Dúvidas comuns​

Quanto custa cada transcrição? Você paga o Whisper diretamente (sua key OpenAI). O preço atual é de cerca de US$ 0,006 por minuto de áudio. Um áudio de 30 segundos custa centavos.

O áudio fica armazenado depois? A mídia em si fica 7 dias no gateway. A transcrição (texto) fica salva indefinidamente associada à mídia — então mesmo após 7 dias, você pode consultar o texto.

E se o cliente mandar áudio em outro idioma? O Whisper detecta automaticamente. Se quiser, você pode pedir transcrição com idioma forçado (ex.: "tratar como espanhol") para casos onde a detecção erra.

Posso usar para call recording (chamadas gravadas)? Sim — o gateway também transcreve chamadas WhatsApp gravadas pelo gateway. O fluxo é parecido, mas em vez de mídia, você solicita transcrição da call.

Quanto tempo demora? Audio de 1 minuto fica pronto em ~5 segundos. De 10 minutos, em ~30 segundos. O Whisper é rápido.

Artigos relacionados​