API y SDK
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.
| 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.
identitybusca exacto por teléfono (solo dígitos), BSUID, @usuario de Instagram, IGSID o PSID.qbusca por el comienzo del nombre del contacto (hasta 64 caracteres).sourcedice de dónde vino el mensaje:customer(el contacto),api,campaign,business_app(la app del celular, en coexistencia) ohistory(historial importado);campaign_idtrae solo los mensajes de una campaña.- Los medios aparecen como parte del mensaje, con
id. El archivo sale enGET /v1/media/{id}/content.
Paginación por cursor
Sección titulada «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.
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \ -H "Authorization: Bearer $MESSAJO_API_KEY"{ "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 →
400invalid_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, paginate sigue el cursor solo:
for await (const message of messajo.paginate(messajo.messages.list, { conversation_id: "cnv_...",})) { console.log(message.id);}Intervalo y retención
Sección titulada «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 de la organización (90 días por defecto); sinuntil, ahora; - un
sincemá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.