> ## Documentation Index
> Fetch the complete documentation index at: https://docs.robbu.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronización de historial

> Importe el historial de mensajes de su número de WhatsApp Business al activar la coexistencia.

# Sincronización de historial

Al activar la coexistencia, puede importar el historial de mensajes de su número de WhatsApp Business a Positus. La importación es **asincrónica** y los mensajes llegan a su **webhook** en el mismo formato que los mensajes recibidos normalmente.

## Cómo disparar la sincronización

Realice una solicitud `POST` al endpoint a continuación. No se requiere cuerpo (body).

```
POST https://api.positus.global/v2/whatsapp/numbers/{NUMBER_ID}/onboarding-smb-app/sync-message-history
Authorization: Bearer <su-token>
```

**Parámetros:**

* `{NUMBER_ID}` — ID del número de WhatsApp ya activado con coexistencia.

<Info>
  La importación puede ser disparada **una sola vez por onboarding**, dentro de la **ventana de 24 horas** después de la activación de la coexistencia. El servidor solo confirma la recepción de la solicitud; los mensajes se entregan después, a lo largo de varios webhooks.
</Info>

## Lo que recibirá

Cada mensaje del historial se entrega a su webhook en el **mismo formato que un mensaje recibido** en Positus — el sobre `{ "contacts": [...], "messages": [...] }`. Recibe **un webhook por mensaje** del historial; su manejador de webhook existente ya procesa estos mensajes sin cambios.

```json theme={null}
{
  "contacts": [
    {
      "profile": { "name": "Nombre del contacto" },
      "wa_id": "5511999999999"
    }
  ],
  "messages": [
    {
      "from": "5511999999999",
      "id": "wamid.xyz",
      "timestamp": "1739230955",
      "type": "text",
      "text": { "body": "mensaje del historial" },
      "history_context": { "status": "READ" }
    }
  ]
}
```

<Info>
  Este es el mismo formato descrito en [Webhook](/es/positus/integracion/webhook). La diferencia es que los mensajes del historial traen el campo adicional `history_context`, indicando el estado que el mensaje tenía en la aplicación. Los metadatos internos del progreso de la importación (fase, orden del lote) **no se pasan** a su webhook.
</Info>

### Campos del mensaje

| Campo                    | Descripción                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `from`                   | Número del remitente del mensaje                                                          |
| `id`                     | ID único del mensaje (wamid)                                                              |
| `timestamp`              | Fecha/hora del envío original (timestamp de Unix)                                         |
| `type`                   | Tipo de mensaje: `text`, `media_placeholder`, `image`, `video`, `audio`, `document`, etc. |
| `text.body`              | Cuerpo del mensaje (para `type: "text"`)                                                  |
| `history_context.status` | Estado que el mensaje tenía en la aplicación (ver tabla a continuación)                   |

### Valores de `history_context.status`

| Estado      | Significado                             |
| ----------- | --------------------------------------- |
| `READ`      | Mensaje leído                           |
| `PLAYED`    | Medios (audio/video) reproducidos       |
| `DELIVERED` | Mensaje entregado al dispositivo        |
| `SENT`      | Mensaje enviado al servidor de WhatsApp |
| `PENDING`   | Todavía esperando confirmación de envío |
| `ERROR`     | Error en el envío                       |

## Ventana de cobertura del historial

Meta proporciona el historial en tres fases, definiendo **cuánto tiempo atrás** se importan los mensajes:

| Fase   | Período cubierto                 |
| ------ | -------------------------------- |
| Fase 0 | Día 0 → Día 1 (últimas 24 horas) |
| Fase 1 | Día 1 → Día 90                   |
| Fase 2 | Día 90 → Día 180                 |

Los mensajes con más de **180 días** no se importan. No necesita tratar estas fases: solo determinan el alcance de la importación — los mensajes llegan a su webhook uno a uno, como se describe arriba.

## Medios en dos etapas

Los mensajes de medios más antiguos (con más de \~14 días) llegan en **dos etapas**:

1. Primero, un mensaje con `type: "media_placeholder"` — **sin el contenido** del medio.
2. Después, un nuevo webhook entrega el mismo mensaje con el contenido real del medio.

<Warning>
  Espere la segunda etapa antes de considerar el medio completo. El `media_placeholder` indica que el medio existe, pero aún no ha sido entregado.
</Warning>

## Historial rechazado por la empresa

Si el compartir historial está desactivado en la aplicación WhatsApp Business, Meta rechaza la importación (error `2593109` — *"History sync is turned off by the business"*).

<Warning>
  Cuando el historial es rechazado, la importación **no procede** y ningún mensaje se entrega. El usuario necesita habilitar el compartir historial en la aplicación WhatsApp Business y rehacer el onboarding.
</Warning>

## Próximos pasos

* [Introducción a la coexistencia](/es/positus/coex/introduccion) — concepto y elegibilidad.
* [Sincronización de contactos](/es/positus/coex/sincronizacion-de-contactos) — importar la lista de contactos.
* [Webhook](/es/positus/integracion/webhook) — formato completo del sobre de mensajes.