Saltar al contenido principal

Espelho · Sincronização

Sincroniza el historial de conversaciones y la lista de contactos de la aplicación WhatsApp Business (modo coexistencia) hacia la Cloud API.

La sincronización se dispara manualmente después de que el cliente conecta el número mediante Embedded Signup — y debe hacerse dentro de 24 horas.

Requisitos previos​

  1. El cliente autorizó el compartir en su móvil. Durante el Embedded Signup, la aplicación WhatsApp Business pide permiso para compartir historial y contactos. Si lo rechazó, no se enviará nada.
  2. Los campos de webhook están suscritos. Activa history y smb_app_state_sync en el endpoint de webhook del número.

Ventana de 24 horas, un solo intento​

Tienes exactamente 24 horas desde el Embedded Signup. Si se pasa el plazo no hay forma de recuperarlo — el cliente debe rehacer el onboarding.

Cada tipo de sincronización (history y smb_app_state_sync) puede dispararse una sola vez por integración.

Cómo llega el historial​

En múltiples webhooks asíncronos, divididos en fases y bloques:

phasePeríodo nominal
0día 0 → día 1
1día 1 → día 90
2día 90 → día 180

En la práctica las fases se solapan — pueden aparecer mensajes de cualquier fecha en cualquier fase. No uses la fase para inferir un período; ordena todo por timestamp.

Cada fase puede llegar en varios bloques (chunk_order), no necesariamente en orden. El campo progress (0–100) indica el avance general: progress: 100 en la última fase significa historial completo.

Un solo webhook puede llevar miles de mensajes:

webhook (1 POST)
└── value.history[]
    └── threads[]       ← 1 hilo = 1 conversación con 1 contacto
        └── messages[]  ← mensajes de esa conversación

Duplicados — regla obligatoria​

El mismo thread.id aparece en varios webhooks y el mismo mensaje puede llegar repetido. Al procesar:

  1. Reúne todos los mensajes con el mismo thread.id de todos los webhooks.
  2. Deduplica por wamid (message.id).
  3. Ordena por timestamp (Unix en segundos, 10 dígitos).

Usa history_context.from_me para saber la dirección: true = enviado por la empresa, false o ausente = recibido.

Medios dentro del historial​

Los medios no viajan dentro de los hilos — aparecen como type: "media_placeholder", sin contenido. El archivo real llega en webhooks separados (value.messages o value.message_echoes), emparejados por el wamid. Solo los medios de los últimos ~14 días tienen archivo disponible.

Contactos​

Normalmente en un único webhook, con todos los contactos en el array state_sync. Las cuentas grandes pueden generar varios, sin orden garantizado.

  • action: "add" → añadir o actualizar un contacto
  • action: "remove" → eliminar un contacto
  • Las marcas de tiempo van en milisegundos (13 dígitos) — a diferencia del historial, que usa segundos.

Tras la sincronización inicial, los cambios posteriores en los contactos siguen llegando automáticamente por smb_app_state_sync, sin necesidad de volver a llamar a este endpoint.