Ir al contenido

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.

  • 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.

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.

Ventana de terminal
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 → 400 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, paginate sigue el cursor solo:

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

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); 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.