Checklist técnico: integrar WhatsApp CRM sem perder mensagens, mídia e histórico

Introdução

Este checklist mostra como integrar WhatsApp CRM sem surpresas: verificação da modalidade do número, backups testados, mapeamento de IDs, webhooks confiáveis, rehosting de mídia, deduplicação e testes E2E. Use-o como roteiro que sua equipe de TI, operação e comercial pode executar em algumas horas.

Verificações pré-migração: escolha da conta e backups obrigatórios

Antes de qualquer alteração, identifique se você está usando WhatsApp Business App (número pessoal), WhatsApp Business API on‑premises ou WhatsApp Cloud API e registre impactos esperados (fila de mensagens, limits, handoff). Produza uma justificativa técnica clara para a escolha da modalidade.

Faça backups obrigatórios e testados antes do corte: exporte conversas críticas em JSON/CSV e compacte toda a mídia associada (ZIP). Para CRM, gere snapshots do banco (leads, conversas, mapeamentos) e registre um rollback point (T0) com dump do DB e pasta de mídia.

Checklist mínimo antes do corte:

• confirmar modalidade alvo e justificar tecnicamente
• exportar conversas-chave + mídia e validar integridade
• validar tokens/credentials e certificados (se on‑premises)
• agendar janela de migração com time de operação disponível para rollback
• testar restauração do dump em staging

Mapeamento de identificadores e metadata essenciais

Preserve os identificadores originais para manter rastreabilidade: armazene phone_id/wa_id, conversation_id (chat_id), message_id e message_timestamp como campos externos no CRM (ex.: external_id, message_external_id). Nunca reescreva esses IDs como valores primários — mantenha uma tabela de mapping (original_id ↔ crm_id) para re-hydration.

Defina e sincronize metadata mínimas por lead: delivery_status, read_timestamp, origem do lead (campanha/QR/flow), tags e última_interaction. Formalize esquema obrigatório no CRM e políticas de TTL/retention (por exemplo, delivery/read por 180 dias) para auditoria e conformidade.

Como integrar WhatsApp CRM: configurar webhooks, retries e idempotência

Assine webhooks com verificação HMAC e TLS; valide headers e timestamps para evitar replay attacks. No CRM, documente onde inserir as chaves e como validar a assinatura.

Implemente idempotência usando message_id + event_id como idempotency_key; qualquer evento com a mesma chave deve ser ignorado ou reconciliado sem recriar entidades. Para ordenação, persista sequence_number/timestamp do evento e reordene no consumidor usando esses campos.

Gerencie retries da API com backoff e trate múltiplos POSTs idênticos: registre attempts e rejeite duplicatas já processadas. Monitore failed webhooks e crie alertas para 5+ falhas consecutivas, latência alta ou filas de processamento em crescimento.

Mídia, links expirados e armazenamento externo

Links de mídia retornados pela API costumam expirar (ex.: 24h). Baixe a mídia assim que possível e armazene em seu bucket/CDN, vinculando o novo URL no CRM e guardando o GUID original para referência.

Prefira proxyar a mídia via seu servidor/CDN em vez de depender do link direto da API — isso evita perda por expiração. Salve sempre mime_type, filename, size e checksum (SHA256) da mídia para validação e deduplicação.

Implemente rotina de recuperação: quando detectar 404/expired, tente rebaixar da API; se falhar, registre incidente e notifique operação para mídia crítica (contratos, notas fiscais, imagens de pedido).

Concorrência, deduplicação, templates (HSM) e limites da API

Ao ter múltiplos agentes/instâncias concorrendo pelo mesmo lead, use locking otimista (version/timestamp) ou uma fila central de mensagens para garantir que apenas uma instância atualize o lead por vez.

Regra de deduplicação proposta:

• primária: phone_number + message_id
• fallback (quando message_id ausente): phone_number + primeiros_30_chars_da_mensagem + timestamp_bucket

Defina conflict-resolution (merge automático quando campos não conflitam; criar thread separado quando conflitam).

Liste e exporte todas as HSM/templates ativas e seus IDs; verifique dependência desses templates em fluxos automáticos antes do corte e planeje reprovações quando a modalidade mudar.

Identifique limites da API (mensagens/segundo, chamadas de mídia). Implemente retries exponenciais, circuit breaker e filas para desacelerar envio em picos e evitar 429s. Sinais de problema: 429/5xx, filas de envio crescendo ou templates rejeitados — tenha um playbook (reduzir taxa, limpar backlog, reprovar template).

Testes end-to-end, plano de rollback, monitoramento e próximos passos práticos

Testes mínimos E2E (rodáveis em staging e em produção após corte):

• Inbound (criar lead): enviar mensagem do número X e verificar webhook chegou e lead criado/atualizado no CRM.
• Outbound template (HSM): disparar HSM aprovado e checar status de envio/entrega.
• Mídia: enviar imagem grande, validar download via API e rehosting no bucket.
• Duplicata/retry: forçar duplicate webhook POST e confirmar idempotência e ausência de leads duplicados.

Comandos de exemplo para testes (playbook):

• Expor webhook local com ngrok e testar recebimento:

ngrok http 8080
# copiar URL públicA e configurar webhook no console da API

• Simular POST de webhook para validar assinatura e idempotência:

curl -X POST -H "Content-Type: application/json" -d '{"message_id":"abc","timestamp":1630000000}' https://seu-crm.example.com/webhook

Checkpoints de rollback:

• antes do corte: T0 DB dump + backup de mídia (verificado)
• após migração: validar 100% dos testes E2E por 1 hora antes de descomissionar a integração antiga
• passo a passo de rollback: restaurar dump, reapontar webhook para integração anterior, restaurar mídia do backup

Logs e alertas essenciais a configurar:

• failed_webhooks > X vezes consecutivas
• fila_processing > Y mensagens
• média_404_rate > Z%
• 429_rate_limit observados
• diferença entre message_timestamp e ingest_timestamp > threshold

Verificações rápidas de compliance:

• consent_flag e timestamp por lead
• mascaramento de dados sensíveis em exibições e exportações
• políticas de retenção alinhadas com LGPD/GDPR

Responsabilidades e estimativa de tempo:

• TI/Integrador: 4–8 horas para configurar webhooks, mapping de IDs e rehosting de mídia em staging
• Operação/Comercial: 2–4 horas para validar templates, fluxos e rodar testes E2E
• Coordenação: janela de migração recomendada de 1–3 horas com 1 hora de validação e 1 hora de rollback disponível

Próximo passo prático: execute a checklist de 'Verificações pré-migração', gere o T0 DB dump e rode os testes E2E em staging. Se quiser, solicite ao time Space Sales uma revisão técnica do playbook para sua arquitetura específica.

Erros comuns, sinais e correções rápidas

Mensagens fora de ordem — sinal: mensagens com timestamps não correlacionados; ação: validar idempotência, sequence_number e reordenação por timestamp no consumidor.

Mídia faltando — sinal: mensagens sem mídia ou 404 em links; ação: verificar expiração de links, rehostear mídia e conferir rotina de recuperação.

Leads duplicados em volume — sinal: pico de leads com mesmos phone_number; ação: aplicar regra de deduplicação (phone+message_id), revisar table de mapping e reprocessar duplicatas com merge.

Templates rejeitados após corte — sinal: HSM retornando erro de validação; ação: exportar HSM antigos, validar IDs na nova modalidade e reprovar/atualizar templates conforme necessário.

Taxa de 429 e filas crescentes — sinal: many 429/5xx e backlog; ação: ativar backoff, reduzir taxa de envio, processar backlog com batch controlado.