Como integrar o WhatsApp ao sistema da empresa

Integrar o WhatsApp ao sistema da empresa tem duas metades que falham por motivos diferentes: a metade burocrática, que acontece dentro da Meta e é onde o cronograma atrasa, e a metade de engenharia, que acontece no seu backend e é onde a operação quebra em silêncio depois. Quem só planeja a segunda descobre a primeira do jeito difícil.

Primeiro: Cloud API direto ou um BSP

Essa decisão vem antes de qualquer código.

Uma regra prática: se o WhatsApp vai ser mais um canal dentro de um sistema que você já tem (ERP, CRM próprio, plataforma de agendamento), a Cloud API direta costuma compensar. Se o objetivo é dar uma caixa de entrada para dez atendentes na semana que vem, o BSP paga a diferença.

Vale saber que a escolha não é definitiva. O número vive no seu WhatsApp Business Account, e migrar entre BSPs ou para a Cloud API é possível, desde que a propriedade da conta seja sua.

Checklist de pré-requisitos

Reúna isso antes de abrir qualquer tela:

• CNPJ ativo e documentação que comprove o nome da empresa, para a verificação no Meta Business Manager
• Meta Business Manager criado e com a sua empresa como proprietária, não a do fornecedor
• Um número de telefone que possa receber SMS ou chamada, e que não esteja em uso em nenhum aplicativo WhatsApp
• Site com política de privacidade publicada, que a análise costuma verificar
• Nome de exibição compatível com a marca ou com a razão social
• Ambiente de teste das APIs internas que o sistema vai consultar
• Decisão de retenção: por quanto tempo as conversas ficam guardadas e quem pode ler

O item do número derruba mais cronogramas que qualquer outro. Se o número já tem WhatsApp, ele precisa ser desvinculado antes, e o histórico daquele aparelho não vai para a plataforma.

O caminho dentro da Meta

1. Verificação da empresa. No Meta Business Manager, envie a documentação e aguarde a análise. Sem empresa verificada, você fica limitado a testes e a um patamar baixo de envio.

2. Criação do WhatsApp Business Account. É o contêiner que agrupa números, templates e permissões. Ele deve pertencer ao seu Business Manager, com o fornecedor adicionado como parceiro.

3. Cadastro e verificação do número. Você recebe um código por SMS ou chamada e define um PIN de verificação em duas etapas. Guarde esse PIN: ele é exigido em re-registros e em migrações, e recuperá-lo dá trabalho.

4. Nome de exibição em análise. O display name passa por revisão da Meta. Nomes genéricos demais ou que não guardam relação com a marca costumam ser reprovados. Enquanto está em análise, o número opera com restrições.

5. Templates de mensagem. Toda mensagem iniciada pela empresa usa um template aprovado previamente, com variáveis nomeadas por posição. As categorias mudam preço e critério de análise:

• Utility: relacionada a uma transação existente (confirmação de pedido, aviso de entrega, lembrete de agendamento)
• Authentication: código de verificação, com formato restrito
• Marketing: promoção, novidade, reengajamento, a categoria mais cara e mais fiscalizada

Enviar conteúdo promocional dentro de um template cadastrado como utility é a causa número um de reprovação e de reclassificação forçada. A Meta reclassifica, e você paga como marketing.

6. A janela de 24 horas. Quando o cliente manda uma mensagem, abre-se uma janela de atendimento de 24 horas em que a empresa responde livremente, com texto, mídia e botões. Passadas as 24 horas sem nova mensagem do cliente, só template aprovado. Toda a arquitetura de notificação depende disso: se o seu fluxo precisa avisar o cliente três dias depois, ele precisa de template, ponto.

7. Tiers de envio e qualidade do número. O limite de contatos únicos iniciados por 24 horas começa baixo (o patamar inicial costuma ser de 250 contatos) e sobe por degraus conforme você envia com qualidade. O quality rating do número cai quando usuários bloqueiam ou denunciam. Qualidade baixa derruba o tier, e tier derrubado significa campanha travada no meio. A causa quase sempre é a mesma: template irrelevante enviado para lista comprada ou desatualizada.

A metade que é engenharia

Aprovado tudo, o trabalho real começa. Os pontos onde essas integrações quebram são conhecidos:

Webhook que responde rápido. A Meta envia os eventos de mensagem e de status para a sua URL e espera confirmação em poucos segundos. Processar a mensagem dentro do handler é o erro clássico: quando o LLM ou o ERP demora, o webhook estoura o tempo. O padrão correto é gravar o evento, responder imediatamente e processar numa fila.

Deduplicação por id de mensagem. Quando o seu endpoint falha ou demora, a Meta reenvia o mesmo evento. Sem deduplicar pelo id da mensagem, o cliente recebe a mesma resposta três vezes e o pedido é criado em duplicidade. Guarde os ids processados e ignore repetições.

Idempotência nas ações. Toda ação que o agente dispara no seu sistema (abrir chamado, emitir segunda via, agendar) precisa de chave de idempotência. Retry sem idempotência gera dois agendamentos para o mesmo horário.

Agrupamento de mensagens em rajada. O cliente manda três linhas seguidas. Responder cada uma gera três respostas desconexas. Espere alguns segundos de silêncio antes de processar o bloco.

Ordem e concorrência. Eventos podem chegar fora de ordem. Processe por conversa em série, não em paralelo, ou o contexto embaralha.

Mídia. Áudio, foto e PDF chegam como um identificador, não como arquivo. Você baixa o conteúdo com um token autenticado, dentro de um prazo de validade, e decide onde armazenar. Transcrição de áudio é um custo à parte e um ponto de falha à parte.

Retry com recuo. Falhas temporárias existem. Reenvie com espera crescente e um teto, e mande para uma fila de erro depois disso, com alerta. Automação que falha em silêncio é pior que automação que não existe.

Armazenamento e LGPD. Conversa de WhatsApp é dado pessoal, muitas vezes sensível. Defina base legal, prazo de retenção, quem tem acesso ao histórico, e registre o consentimento para comunicação ativa. Guarde log de quem leu o quê. Se o cliente pedir exclusão, você precisa conseguir executar.

O que colocar no ar primeiro

Suba na ordem inversa do risco: primeiro o recebimento com transferência para humano (você já ganha registro e fila), depois as consultas somente leitura, depois as ações reversíveis e por último as que mexem em dinheiro. É esse escalonamento que a Retti Tech usa nas integrações de WhatsApp, porque cada etapa valida a anterior em produção antes de aumentar a superfície de erro.