Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Cómo importar el historial de chats y los contactos de la app de WhatsApp Business a través de la API

Un número de la app de WhatsApp Business conectado mediante Coexistencia puede enviar una sola vez a la API sus contactos existentes y hasta 180 días de chats uno a uno, dentro de las 24 horas posteriores a la incorporación. Los contactos llegan como webhooks smb_app_state_sync y los chats como webhooks history, en fragmentos ordenados por metadata.chunk_order; metadata.progress en 100 marca la importación como completa. La empresa elige en la app si comparte los chats.

easyCoexistence conecta los números de la app de WhatsApp Business de tus clientes mediante Coexistencia y pide a Meta sus contactos e historial de chats en cuanto tu webhook está listo, así que el historial llega directo a tu endpoint sin almacenarse en el camino, y cada número se monitoriza las 24 horas.

180 days

Hasta dónde llegan los webhooks de historial, contando desde que la empresa se incorporó a la Cloud API.

24 hours

Plazo tras la incorporación para sincronizar los contactos y el historial de mensajes de una empresa.

2593109

Código de error en el webhook de historial cuando la empresa ha desactivado el uso compartido del historial en la app de WhatsApp Business.

Once

Frecuencia máxima con la que puede ejecutarse cada sincronización; repetirla exige que el cliente dé de baja el número y vuelva a completar Embedded Signup.

100

El valor de progress que marca una sincronización del historial como completada.

¿Cómo empieza la importación?

Con un destino de webhook en el número. Cuando se conecta con webhook_url ya definido en la sesión de conexión, o cuando lo defines con PUT /connections/{id}/webhook dentro de las 24 horas posteriores a la conexión, easyCoexistence pide a Meta los datos una sola vez: POST /{phone_number_id}/smb_app_data con sync_type smb_app_state_sync para los contactos, y después history para los chats, en el orden que documenta Meta. El registro de eventos del número anota history_sync_requested con los valores request_id de Meta para soporte, o history_sync_failed con el motivo.

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

¿Qué transportan los webhooks de contactos?

El campo smb_app_state_sync, con un array state_sync en el value. Cada elemento tiene type contact; un objeto contact con full_name, first_name y phone_number; una action de add o remove; y metadata.timestamp. Los nombres se omiten en remove. Meta sigue enviando estos webhooks después de la importación cada vez que la empresa añade, edita o elimina un contacto en la app de WhatsApp Business, para que tu libreta de direcciones se mantenga alineada con el teléfono.

¿Qué transportan los webhooks de historial?

El campo history, con un array history en el value. Cada elemento contiene metadata, con phase, chunk_order y progress, y threads, uno por cliente: el id del hilo es el número del cliente, y messages recoge esa conversación uno a uno, entrante y saliente, con from indicando qué lado envió cada mensaje. Un mensaje incluye id, timestamp, type, su contenido bajo el nombre del tipo y history_context.status, como READ o DELIVERED. Los chats de grupo no se incluyen.

A history webhook, as Meta sends it
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "history",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
            "history": [
              {
                "metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
                "threads": [
                  {
                    "id": "<CUSTOMER_NUMBER>",
                    "messages": [
                      {
                        "from": "<CUSTOMER_NUMBER>",
                        "id": "wamid.<ID>",
                        "timestamp": "1790726400",
                        "type": "text",
                        "text": { "body": "<MESSAGE_TEXT>" },
                        "history_context": { "status": "READ" }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

¿Cómo se importan los mensajes multimedia?

Primero como marcadores. Un mensaje multimedia llega con type media_placeholder, sin contenido y sin ID de medio. Después Meta envía webhooks de historial aparte con los ID de medio, pero solo para medios enviados dentro de los 14 días de la incorporación; descarga esos archivos desde Meta con el token del cliente. Los medios más antiguos siguen siendo marcadores, así que muéstralos como un adjunto no disponible en lugar de dejar un hueco en la conversación.

¿En qué orden llegan los fragmentos y cuándo termina la importación?

No necesariamente en orden. Meta divide los chats en tres fases, de más reciente a más antigua: la fase 0 es el día anterior a la incorporación, la fase 1 llega hasta el día 90 y la fase 2 hasta el día 180. Los fragmentos pueden llegar desordenados, así que ordénalos por metadata.chunk_order. metadata.progress es el porcentaje de la sincronización completa, y 100 significa que ha terminado; el número de fase por sí solo no indica que una fase haya terminado.

¿Qué pasa si la empresa no comparte los chats?

Durante la conexión, la app de WhatsApp Business pregunta a la empresa si quiere compartir su historial de chats. Si lo rechaza, llega un webhook de historial sin messages y con un array errors cuyo code es 2593109, con el título History sync is turned off by the business from the WhatsApp Business App. Los contactos siguen llegando, y los mensajes en vivo fluyen con normalidad desde el momento en que se conectó el número.

¿Se puede volver a ejecutar la importación?

No en la misma conexión. Meta permite cada sincronización una vez, dentro de las 24 horas posteriores a la incorporación, y no puede reproducirse. Para repetirla, el cliente tiene que desconectar el número y volver a conectarlo, lo que cuenta como una nueva incorporación: si tu destino sigue guardado, easyCoexistence vuelve a pedir la importación, así que deduplica por el id de cada mensaje. Eso incluye un número que regresa después de la regla de los 14 días.

¿Qué debe estar listo antes de enviar el enlace de conexión?

Tu endpoint, activo y respondiendo. Meta verifica la URL con su handshake GET cuando se aplica el destino, y la importación se solicita una vez, justo después. Si el handshake falla, el número se conecta igualmente pero sin destino, el last_error de la sesión explica por qué, y no se importa nada a menos que corrijas el endpoint y lo definas con PUT /connections/{id}/webhook dentro de las 24 horas. Un número sin webhook_url no recibe ninguna importación, porque el contenido enviado a easyCoexistence se descarta.

Cómo configurarlo

  1. Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.

Errores comunes

  • Rechazar fragmentos de historial grandes. Las cargas de Meta pueden llegar a 3 MB, mientras que Express analiza JSON solo hasta 100 KB por defecto, así que sube el límite o los fragmentos fallarán y Meta seguirá reintentándolos.
  • Procesar los fragmentos en el orden de llegada. Pueden llegar desordenados, así que ordénalos por metadata.chunk_order y espera a progress 100 antes de dar la importación por completada.
  • Insertar historial sin deduplicar. Los mensajes en vivo pueden solaparse con la importación y una reconexión la vuelve a ejecutar, así que identifica cada mensaje por su id.
  • Enviar el enlace de conexión antes de que el endpoint responda al handshake de Meta. Entonces el destino no se aplica, y si no lo defines en 24 horas, el historial del número nunca se importa.
Hacerlo con EasyCoexistence

De US$ 9 a US$ 0.75 por conexión al mes, con descuento a medida que añades conexiones, y con los primeros 3 días gratis.

Preguntas frecuentes

¿Hasta dónde llega la importación del historial de chats de WhatsApp?

Hasta 180 días antes de que el número se incorporara a la Cloud API, cubriendo chats uno a uno en ambas direcciones.

¿Se importan los chats de grupo?

No. Meta deja fuera los mensajes que forman parte de un chat de grupo.

¿Llegarán a mi webhook los chats antiguos de WhatsApp de un cliente?

Sí, hasta 180 días de chats uno a uno, enviados una vez dentro de las 24 horas posteriores a la incorporación, si la empresa elige en la app compartirlos.

¿easyCoexistence guarda una copia de los chats importados?

No. Meta envía el historial directamente a tu webhook_url, igual que los mensajes en vivo, y nada se almacena en el camino.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el