# Historial

> Conversaciones, contactos y mensajes guardados por Messajo: filtros, paginación por cursor y cómo la retención limita el intervalo.

Messajo guarda lo que pasa por las conexiones y permite consultarlo por la API con el permiso `read`. Todo respeta las conexiones de la clave: una clave limitada a algunas conexiones solo ve lo que es de ellas.

## Rutas

| Ruta | Filtros | Orden |
|---|---|---|
| `GET /v1/conversations` | `connection_id`, `contact_id`, `window=open\|closed`, `since`, `until` (sobre `last_message_at`) | `last_message_at` más reciente primero |
| `GET /v1/conversations/{id}/messages` | `direction`, `type`, `since`, `until`, `order=desc\|asc` | `created_at` |
| `GET /v1/messages` | `connection_id`, `contact_id`, `conversation_id`, `direction`, `status`, `type`, `source`, `campaign_id`, `since`, `until`, `order` | `created_at` |
| `GET /v1/contacts` | `connection_id`, `channel`, `identity`, `q`, `since` | `last_seen_at` más reciente primero |

Cada una tiene su versión por id (`GET /v1/conversations/{id}`, `GET /v1/messages/{id}`, `GET /v1/contacts/{id}`). Fechas en ISO 8601.

- `identity` busca exacto por teléfono (solo dígitos), BSUID, @usuario de Instagram, IGSID o PSID.
- `q` busca por el comienzo del nombre del contacto (hasta 64 caracteres).
- `source` dice de dónde vino el mensaje: `customer` (el contacto), `api`, `campaign`, `business_app` (la app del celular, en coexistencia) o `history` (historial importado); `campaign_id` trae solo los mensajes de una campaña.
- Los medios aparecen como parte del mensaje, con `id`. El archivo sale en `GET /v1/media/{id}/content`.

## Paginación por cursor

Toda lista devuelve `{ data, next_cursor }`. Pasa `limit` (hasta 100) y, para la página siguiente, el `next_cursor` recibido en `cursor`. Terminó cuando `next_cursor` llega en `null`.

```bash
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg_...",
      "conversation_id": "cnv_...",
      "contact_id": "ctc_...",
      "direction": "inbound",
      "type": "text",
      "text": { "body": "¡Hola! ¿Sigue vigente el cupón?" },
      "source": "customer",
      "status": "received",
      "campaign": null,
      "created_at": "2026-11-10T14:03:11.000Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0"
}
```

- El cursor es opaco: no lo armes ni lo cambies. Cursor roto → `400` [`invalid_cursor`](/es/errors#invalid_cursor).
- El cursor guarda una posición, no una foto de la lista: lo que llegue después no duplica ni salta elementos ya leídos.
- Usa los mismos filtros en todas las páginas.

Con el [SDK](/es/sdk/typescript/), `paginate` sigue el cursor solo:

```ts
for await (const message of messajo.paginate(messajo.messages.list, {
  conversation_id: "cnv_...",
})) {
  console.log(message.id);
}
```

## Intervalo y retención

Los mensajes se guardan por mes. Toda consulta de mensajes tiene un intervalo `since`/`until`:

- sin `since`, vale el inicio de la [retención](/es/operate/data-privacy/#retención) de la organización (90 días por defecto); sin `until`, ahora;
- un `since` más antiguo que la retención se recorta al límite, sin error: lo que pasó el plazo ya se borró;
- los intervalos cortos responden más rápido.

La retención cuenta desde que el dato se **guardó** en Messajo. El historial de 6 meses importado en la coexistencia se guarda el día de la importación y sale junto con el resto cuando vence el plazo.
