Exportar mensajes

Recupera todos los mensajes de tu negocio en un rango de fechas, de todos los canales de atención, del más antiguo al más nuevo. Sirve para cargar las conversaciones en tu propio sistema de análisis.

GET/messages

Autenticación

Este endpoint se autentica con tu API key enviada en la cabecera X-API-Key (formato ek_live_...). Puedes gestionar tus API keys desde la sección Dev Tools del panel.

Parámetros de consulta

ParámetroTipoObligatorioDescripción
sinceDatetimeObligatorioFecha y hora ISO 8601. Devuelve los mensajes creados desde ese momento, incluido.
untilDatetimeOpcionalFecha y hora ISO 8601. Devuelve los mensajes creados antes de ese momento. Por defecto, ahora. Entre since y until puede haber como máximo 31 días.
channelStringOpcionalCanales a incluir, separados por coma. Por defecto, todos. Valores: whatsapp, whatsapp_web, instagram, messenger, tiktok, email, sms, web_embed, hubspot_chat, voice.
limitIntegerOpcionalCantidad de mensajes por página (por defecto 100, máximo 500).
cursorStringOpcionalEl next_cursor de la página anterior. Omítelo en la primera solicitud.

Ejemplo de solicitud

bash
curl -X GET "https://api.eclecticlabs.com/api/external/v2/messages?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z&limit=500" \
  -H "X-API-Key: ek_live_your_api_key_here"

Para pedir la página siguiente, repite la solicitud con el next_cursor de la respuesta como cursor:

bash
curl -X GET "https://api.eclecticlabs.com/api/external/v2/messages?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z&limit=500&cursor=eyJ0IjoiMjAyNi0wOS0wMVQxMjowMjowMCswMDowMCIsImMiOiJ3aGF0c2FwcCIsImkiOiJhMWIyYzNkNC0wMDAyLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ" \
  -H "X-API-Key: ek_live_your_api_key_here"

Ejemplo de respuesta

json
{
  "messages": [
    {
      "id": "a1b2c3d4-0001-0000-0000-000000000000",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "direction": "inbound",
      "sender_type": "contact",
      "agent": null,
      "user": null,
      "type": "text",
      "text": "Hola, ¿tienen despacho a regiones?",
      "media": null,
      "reply_to_id": null,
      "status": "RECEIVED",
      "error": null,
      "created_at": "2026-09-01T12:01:10Z"
    },
    {
      "id": "a1b2c3d4-0002-0000-0000-000000000000",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "direction": "outbound",
      "sender_type": "ai_agent",
      "agent": {
        "id": "5d6e7f80-0000-0000-0000-000000000000",
        "name": "Agente de ventas"
      },
      "user": null,
      "type": "text",
      "text": "¡Hola! Sí, despachamos a todo Chile.",
      "media": null,
      "reply_to_id": null,
      "status": "READ",
      "error": null,
      "created_at": "2026-09-01T12:02:00Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQxMjowMjowMCswMDowMCIsImMiOiJ3aGF0c2FwcCIsImkiOiJhMWIyYzNkNC0wMDAyLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ"
}

Campos de la respuesta

  • idUUID del mensaje.
  • conversation_idUUID de la conversación a la que pertenece el mensaje.
  • contact_idUUID del contacto de esa conversación.
  • channelCanal del mensaje, por ejemplo whatsapp o instagram.
  • directioninbound si lo envió el contacto, outbound si lo envió tu negocio.
  • sender_typeQuién envió el mensaje. Ver los valores abajo.
  • agentAgente de IA que respondió (id y name), o null.
  • userPersona de tu equipo que respondió desde Eclectic (id, name y email), o null.
  • typeTipo de mensaje: text, image, audio, document, template, etc.
  • textTexto del mensaje. Puede venir vacío en mensajes solo con archivo.
  • mediaArchivo adjunto (id, filename y content_type), o null.
  • reply_to_idUUID del mensaje al que responde, o null.
  • statusERROR, DELIVERED, RECEIVED o READ.
  • errorDetalle del error de entrega, o null.
  • created_atFecha y hora del mensaje (ISO 8601, UTC).

Valores de sender_type

sender_type permite separar las respuestas de la IA, de tu equipo y de tus integraciones.

  • contactEl cliente.
  • ai_agentUn agente de IA de Eclectic.
  • humanUna persona de tu equipo, desde Eclectic o desde la app del canal (por ejemplo WhatsApp Business).
  • apiUn mensaje enviado a través de la API pública de Eclectic.
  • automationCampañas, flujos y mensajes del sistema.

Notas

  • Repite la solicitud con el next_cursor de cada respuesta hasta que llegue null. Una página puede traer menos mensajes que limit; solo un next_cursor null indica que no quedan más.
  • Cada solicitud cubre como máximo 31 días. Para exportar un período más largo, pide un mes a la vez.
  • Para sincronizar de forma incremental, vuelve a pedir desde el último created_at que guardaste, restando unos minutos, y descarta los id que ya tienes. Algunos canales registran el mensaje un poco después de que ocurrió, y ese margen evita perderlo.
  • Se exportan las conversaciones asociadas a un contacto. No se incluyen los grupos de WhatsApp, las conversaciones de prueba ni los chats internos. Si un número está conectado a la vez a WhatsApp Web y a la API de WhatsApp Business, cada mensaje registrado en ambos aparece una sola vez, con el canal whatsapp; los que solo existen en WhatsApp Web aparecen con el canal whatsapp_web.
  • Los archivos vienen como referencia en media. Para descargarlos, pide una URL con GET /media/:id usando el id de media.
  • Este endpoint y GET /contacts/:uuid/timeline comparten un límite de 120 solicitudes por minuto por negocio. Si lo superas, recibirás un 429.
  • Errores posibles: 400 (parámetros inválidos, por ejemplo una ventana de más de 31 días o un cursor inválido), 401 (API key inválida o ausente), 429 (límite de uso).