Pedidos por voz no WhatsApp: webhook antes da IA

Para receber pedidos por texto, áudio e chamada no WhatsApp Business com IA, mantenha o webhook curto: autentique o evento, registre-o, envie-o a uma fila e responda antes de baixar mídia, consultar o modelo ou acessar o sistema comercial. A interpretação acontece depois, fora desse caminho crítico.

Os canais podem compartilhar cardápio, carrinho e memória, mas cada um deve ter processamento próprio. Assim, uma nota de voz demorada ou uma chamada em andamento não bloqueia novos eventos, enquanto preços, disponibilidade e criação do pedido continuam sob controle do backend.

1. Valide o percurso mínimo no sandbox

Comece com uma mensagem de texto e o menor fluxo funcional: receber o evento, autenticar o webhook, enfileirar o trabalho, consultar um item no backend e enviar a resposta. A Central do Desenvolvedor do WhatsApp Business disponibiliza números de teste, exemplos de código, webhooks e sandbox para iniciar a integração.

Separe teste e produção desde o início. Token de acesso, segredo do aplicativo e token de verificação devem ficar em um cofre de segredos, fora do repositório e dos logs. Durante o piloto, limite os números autorizados e use um cardápio reduzido para validar o percurso sem misturar mensagens reais com dados de teste.

2. Encerre o webhook antes do trabalho pesado

Webhook confirma uma nota de voz e envia o trabalho a uma fila antes do processamento de áudio.

O endpoint público deve verificar a autenticidade da chamada, extrair somente os campos necessários e publicar um envelope na fila. A arquitetura multimodal documentada pela AWS confirma o recebimento com HTTP 200 antes do processamento assíncrono, usa uma fila com fila de mensagens mortas e direciona texto, nota de voz e chamada a runtimes distintos.

Inclua no envelope o identificador recebido do provedor, o tipo de canal, a referência da mídia, um identificador interno do cliente e o horário de entrada. O worker baixa o conteúdo e aciona o processamento com timeout, número limitado de tentativas e um destino explícito para falhas; o handler do webhook não deve esperar por essas operações.

Trate o identificador do evento como chave de idempotência. Antes de alterar o carrinho ou criar o pedido, o backend consulta se essa chave já foi concluída e, em caso positivo, reutiliza o resultado armazenado. É uma proteção de implementação contra reentregas e repetições, não uma capacidade que deve ser delegada ao modelo.

3. Dê à IA interpretação, não autoridade comercial

Pedido falado vira campos estruturados, e o backend calcula disponibilidade e total antes da confirmação.

O modelo pode converter “manda dois sem cebola para retirar às sete” em campos estruturados, mas preço, disponibilidade, desconto, imposto e número do pedido precisam vir de funções determinísticas. O backend permanece como registro oficial de cardápio, carrinho e pedido.

Exponha operações estreitas: consultar cardápio, verificar disponibilidade, adicionar item, ler carrinho e solicitar a criação do pedido. Valide no servidor códigos de produto, quantidades, modificações, endereço, unidade, horário e estado do carrinho. Controles de permissão para um agente conectado ao backend também reduzem o risco de uma instrução da conversa alcançar funções administrativas.

Antes da gravação final, apresente um resumo calculado pelo sistema comercial com itens, modificações, modalidade de atendimento, unidade e total. A ferramenta de criação só deve ser executada após confirmação inequívoca. Ambiguidade, item indisponível, mudança de preço ou falha no backend deve preservar o carrinho e encaminhar o contexto a uma pessoa.

4. Separe nota de voz e chamada

A nota de voz é uma mídia finita: o worker obtém o arquivo, processa o áudio, interpreta o pedido e produz a resposta. A chamada mantém uma sessão em tempo real e exige transporte contínuo de áudio, controle de interrupções, latência previsível e encerramento consistente. Mesmo que ambos usem o mesmo modelo de voz, são cargas operacionais diferentes.

Calcule custos e limites por canal. Para texto, considere mensagens, inferência e chamadas ao backend; para nota de voz, acrescente transferência, armazenamento temporário e processamento de áudio; para chamadas, inclua os recursos mantidos durante toda a sessão. Defina duração máxima, tamanho de mídia, timeout e uma rota para texto ou atendimento humano quando o áudio não puder ser interpretado com segurança.

5. Use memória pseudonimizada sem prometer anonimato

Número do cliente é substituído por identificador pseudonimizado, com dados de envio mantidos em camada separada.

Para preservar a continuidade entre canais, derive o identificador interno do telefone com uma função criptográfica e um segredo mantido separadamente. Restrinja a camada que conserva a informação necessária para enviar respostas e estabeleça retenções próprias para áudio original, transcrição, carrinho e histórico de pedidos.

A pseudonimização reduz exposição, mas não retira automaticamente os dados do alcance da lei. A orientação pública sobre dados abrangidos pela LGPD inclui telefone e identificadores eletrônicos entre os possíveis dados pessoais e esclarece que pseudonimização não equivale a anonimização.

Documente finalidade, necessidade, prazo de retenção, operadores envolvidos e hipótese legal aplicável a cada tratamento. Se a empresa adotar consentimento em uma operação específica, registre finalidade e momento da manifestação, sem transformá-lo em autorização genérica. Logs técnicos devem priorizar estados do fluxo, identificadores internos e códigos de erro, evitando telefone, áudio e transcrição integral.

6. Libere por canal e preserve a saída humana

Coloque texto em produção primeiro, com um conjunto limitado de produtos e ferramentas. Acrescente notas de voz quando o mesmo backend já impedir duplicidades e exigir confirmação; só então avalie chamadas, que introduzem estado e latência em tempo real. Em cada fase, simule eventos repetidos e fora de ordem, mídia indisponível, timeout do modelo e indisponibilidade do sistema de pedidos.

O critério de liberação não é compreender toda frase. O sistema precisa recusar o que não consegue concluir, conservar o carrinho, impedir pedidos duplicados e entregar ao atendente um resumo utilizável. Separar o webhook antes de ligar a IA é o que mantém a entrada disponível enquanto interpretação, voz e backend falham ou evoluem de forma independente.

Pedidos por voz no WhatsApp: separe o webhook antes de ligar a IA