Checklist de migração de outra API de WhatsApp para a ZapZap sem perder o histórico

Liste, por número: cliente, quem usa, volume diário, integrações que chamam a API (CRM, n8n, chatbot), o endereço de webhook atual e o formato dos eventos que seu sistema espera. Marque os números críticos e os de baixo risco. O primeiro a migrar é o de menor risco, não o maior cliente.

Faça também o inventário do histórico: o que está no seu banco (conversas, leads) e o que existe só na API antiga. Exporte o que só existe lá antes de cancelar qualquer coisa. Para a comparação do que cada alternativa entrega, veja os comparativos.

Crie uma camada pequena no seu código (uma função enviarTexto) e deixe a troca de API acontecer só nela. Na ZapZap, o envio de texto é POST https://api.zapzapapi.com/api/v1/{instanceId}/send/text, com number e text no corpo e os cabeçalhos x-api-key e x-api-secret. A referência e o arquivo OpenAPI listam os demais endpoints (mídia, botões, enquetes, grupos), e há SDKs em Node.js, Python e PHP.

Faça o mesmo para o webhook: um adaptador que converte o envelope da ZapZap para o formato interno do seu sistema. Valide a assinatura e deduplique, como no guia de webhooks idempotentes.

# 1) Inventory: list the instances already created on ZapZap
curl "https://api.zapzapapi.com/api/v1/instances" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

# 2) Point the new webhook at your system and keep the old one running during the cutover
curl -X PUT "https://api.zapzapapi.com/api/v1/instances/INSTANCE_ID/webhook" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"webhook_url":"https://your-system.example/webhook","events":"messages,messages_update"}'

# 3) Optional: ask for older messages of ONE chat (they arrive through the webhook, not in the response)
curl -X POST "https://api.zapzapapi.com/api/v1/INSTANCE_ID/message/history-sync" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"number":"5511999999999@s.whatsapp.net","count":50}'

# 4) Switch the send call: same idea, new base URL and headers
curl -X POST "https://api.zapzapapi.com/api/v1/INSTANCE_ID/send/text" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"number":"5511999999999","text":"Test after migration"}'

Conectar o número na ZapZap é escanear um QR code, e isso exige o aparelho em mãos: programe a janela com o cliente. Mudar de ferramenta é uma mudança de sessão do número, então evite disparos nas primeiras horas e comece por conversas de quem já fala com o cliente.

Durante o corte, mantenha o webhook antigo e o novo ativos para o mesmo número só se o seu sistema deduplicar. Teste com o POST de teste do webhook, envie uma mensagem de teste e confirme o recebimento de uma resposta real.

O histórico de conversas que está no seu banco continua lá: não precisa migrar nada. O que a API antiga guardava e o seu sistema não, você exporta por ela. Do lado da ZapZap, existe POST /{instanceId}/message/history-sync, que solicita a sincronização de mensagens antigas de um chat; as mensagens chegam pelo webhook ou pelo SSE, não na resposta, e os parâmetros são o JID do chat, uma mensagem de referência e a quantidade. Peça por chat e trate o volume recebido, porque o que o WhatsApp devolve depende do que ele ainda mantém.

Não prometa ao cliente o histórico completo. Combine o que fica: o que está no seu banco, mais o que a sincronização trouxer. Consulte mensagens já recebidas com POST /{instanceId}/message/find.

Migre um número, observe um dia útil inteiro (entregas, respostas, erros no webhook, status da instância) e só então migre o próximo. Mantenha a API antiga paga até o último número estabilizar, porque ela é o seu plano de volta. O custo da ZapZap é R$15 por número ativo ao mês, pré-pago e sem cobrança por mensagem, mais a taxa de ativação por instância: consulte o GET /instances/cost e a página de preços.

Feche cada número com uma revisão curta: webhook com taxa de erro baixa, taxa de resposta parecida com a anterior e o cliente avisado. Para quem opera em escala, veja agências com IA, revenda com a marca do cliente e o aquecimento de chip.