Checklist de migración de otra API de WhatsApp a ZapZap sin perder el historial

Lista, por número: cliente, quién lo usa, volumen diario, integraciones que llaman a la API (CRM, n8n, chatbot), la dirección de webhook actual y el formato de eventos que tu sistema espera. Marca los números críticos y los de bajo riesgo. El primero en migrar es el de menor riesgo, no el mayor cliente.

Haz también el inventario del historial: lo que está en tu base (conversaciones, leads) y lo que existe solo en la API antigua. Exporta lo que solo existe allí antes de cancelar nada. Para comparar lo que entrega cada alternativa, mira los comparativos.

Crea una capa pequeña en tu código (una función enviarTexto) y deja que el cambio de API ocurra solo en ella. En ZapZap, el envío de texto es POST https://api.zapzapapi.com/api/v1/{instanceId}/send/text, con number y text en el cuerpo y los encabezados x-api-key y x-api-secret. La referencia y el archivo OpenAPI listan los demás endpoints (medios, botones, encuestas, grupos), y hay SDKs en Node.js, Python y PHP.

Haz lo mismo con el webhook: un adaptador que convierte el sobre de ZapZap al formato interno de tu sistema. Valida la firma y deduplica, como en la guía 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 el número en ZapZap es escanear un código QR, y eso exige el aparato en mano: programa la ventana con el cliente. Cambiar de herramienta es un cambio de sesión del número, así que evita envíos en las primeras horas y empieza por conversaciones de quien ya habla con el cliente.

Durante el corte, mantén el webhook antiguo y el nuevo activos para el mismo número solo si tu sistema deduplica. Prueba con el POST de prueba del webhook, envía un mensaje de prueba y confirma la recepción de una respuesta real.

El historial de conversaciones que está en tu base sigue allí: no hay nada que migrar. Lo que la API antigua guardaba y tu sistema no, lo exportas por ella. Del lado de ZapZap existe POST /{instanceId}/message/history-sync, que solicita la sincronización de mensajes antiguos de un chat; los mensajes llegan por el webhook o por SSE, no en la respuesta, y los parámetros son el JID del chat, un mensaje de referencia y la cantidad. Pide por chat y maneja el volumen recibido, porque lo que WhatsApp devuelve depende de lo que aún conserve.

No le prometas al cliente el historial completo. Acuerda lo que queda: lo que está en tu base, más lo que traiga la sincronización. Consulta mensajes ya recibidos con POST /{instanceId}/message/find.

Migra un número, observa un día hábil completo (entregas, respuestas, errores en el webhook, estado de la instancia) y solo entonces migra el siguiente. Mantén la API antigua pagada hasta que el último número se estabilice, porque es tu plan de vuelta. El costo de ZapZap es R$15 por número activo al mes, prepago y sin cobro por mensaje, más la tarifa de activación por instancia: consulta GET /instances/cost y la página de precios.

Cierra cada número con una revisión corta: webhook con baja tasa de error, tasa de respuesta parecida a la anterior y el cliente avisado. Para quien opera a escala, mira agencias con IA, reventa con la marca del cliente y el calentamiento de chip.