Conversación unificada de un contacto

Recupera todos los mensajes de un contacto en todos los canales (WhatsApp, Instagram, email, chat web y otros), unidos en una sola conversación, del más antiguo al más nuevo.

GET/contacts/:uuid/timeline

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 ruta

ParámetroTipoObligatorioDescripción
uuidUUIDObligatorioUUID del contacto.

Parámetros de consulta

ParámetroTipoObligatorioDescripción
sinceDatetimeOpcionalFecha 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.
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/contacts/eb2b914a-977e-4ab8-96e7-b886698b3eac/timeline?limit=100" \
  -H "X-API-Key: ek_live_your_api_key_here"

Ejemplo de respuesta

json
{
  "contact": {
    "id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
    "first_name": "Ana",
    "last_name": "Pérez",
    "phone_number": "56912345678"
  },
  "messages": [
    {
      "id": "c0ffee00-0001-0000-0000-000000000000",
      "conversation_id": "7a1c2d3e-0000-0000-0000-000000000000",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "instagram",
      "direction": "inbound",
      "sender_type": "contact",
      "agent": null,
      "user": null,
      "type": "text",
      "text": "Vi el producto en su perfil, ¿tiene stock?",
      "media": null,
      "reply_to_id": null,
      "status": "RECEIVED",
      "error": null,
      "created_at": "2026-09-10T15:20:00Z"
    },
    {
      "id": "a1b2c3d4-0005-0000-0000-000000000000",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "direction": "outbound",
      "sender_type": "human",
      "agent": null,
      "user": {
        "id": "0b1c2d3e-0000-0000-0000-000000000000",
        "name": "Camila",
        "email": "camila@example.com"
      },
      "type": "text",
      "text": "Hola Ana, te escribo por acá para coordinar el despacho.",
      "media": null,
      "reply_to_id": null,
      "status": "DELIVERED",
      "error": null,
      "created_at": "2026-09-11T10:05:00Z"
    }
  ],
  "next_cursor": null
}

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.
  • Cada mensaje indica su canal y su conversación, así que puedes reconstruir cada hilo por separado. 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 archivos vienen como referencia en media. Para descargarlos, pide una URL con GET /media/:id usando el id de media.
  • Este endpoint y GET /messages comparten un límite de 120 solicitudes por minuto por negocio.
  • Errores posibles: 400 (parámetros inválidos), 401 (API key inválida o ausente), 404 (contacto no encontrado), 429 (límite de uso).