Exportar eventos

Recupera lo que pasó en las conversaciones y los contactos de tu negocio en un rango de fechas, del más antiguo al más nuevo: tomas de control manual, alertas, transferencias, sentimiento, archivado, cambios de agente y cambios en los campos de contacto. Se complementa con GET /messages para armar paneles de atención en tu propio sistema.

GET/events

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ámetro	Tipo	Obligatorio	Descripción
`since`	Datetime	Obligatorio	Fecha y hora ISO 8601. Devuelve los eventos creados desde ese momento, incluido.
`until`	Datetime	Opcional	Fecha y hora ISO 8601. Devuelve los eventos creados antes de ese momento. Por defecto, ahora. Entre since y until puede haber como máximo 31 días.
`types`	String	Opcional	Tipos de evento a incluir, separados por coma (por ejemplo alert_triggered,manual_control_activated). Por defecto, todos. Los valores están más abajo.
`channel`	String	Opcional	Canales a incluir, separados por coma. Por defecto, todos. Los cambios de campos de contacto no pertenecen a ningún canal, así que este filtro los deja fuera. Valores: whatsapp, whatsapp_web, instagram, messenger, tiktok, email, sms, web_embed, hubspot_chat, voice.
`limit`	Integer	Opcional	Cantidad de eventos por página (por defecto 100, máximo 500).
`cursor`	String	Opcional	El 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/events?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/events?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z&limit=500&cursor=eyJ0IjoiMjAyNi0wOS0wMVQxMjowNTowMCswMDowMCIsInMiOiJjb252ZXJzYXRpb24iLCJpIjoiYzdkOGU5ZjAtMDAwMy0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0" \
  -H "X-API-Key: ek_live_your_api_key_here"

Ejemplo de respuesta

json

{
  "events": [
    {
      "id": "c7d8e9f0-0001-0000-0000-000000000000",
      "type": "sentiment_analyzed",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "actor_type": "ai_agent",
      "agent": null,
      "user": null,
      "data": { "sentiment": "NEGATIVE" },
      "created_at": "2026-09-01T12:03:40Z"
    },
    {
      "id": "c7d8e9f0-0002-0000-0000-000000000000",
      "type": "alert_triggered",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "actor_type": "ai_agent",
      "agent": {
        "id": "5d6e7f80-0000-0000-0000-000000000000",
        "name": "Agente de ventas"
      },
      "user": null,
      "data": { "reason": "El cliente pide hablar con una persona" },
      "created_at": "2026-09-01T12:04:05Z"
    },
    {
      "id": "c7d8e9f0-0003-0000-0000-000000000000",
      "type": "manual_control_activated",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "actor_type": "human",
      "agent": null,
      "user": {
        "id": "8a9b0c1d-0000-0000-0000-000000000000",
        "name": "Camila Rojas",
        "email": "camila@example.com"
      },
      "data": { "reason": null },
      "created_at": "2026-09-01T12:05:00Z"
    },
    {
      "id": "c7d8e9f0-0004-0000-0000-000000000000",
      "type": "contact_field_changed",
      "conversation_id": null,
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": null,
      "actor_type": "human",
      "agent": null,
      "user": {
        "id": "8a9b0c1d-0000-0000-0000-000000000000",
        "name": "Camila Rojas",
        "email": "camila@example.com"
      },
      "data": {
        "source": "crm",
        "changes": [
          { "field": "caso", "custom": true, "from": "Consulta", "to": "Cambio" }
        ]
      },
      "created_at": "2026-09-01T12:07:30Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQxMjowNTowMCswMDowMCIsInMiOiJjb252ZXJzYXRpb24iLCJpIjoiYzdkOGU5ZjAtMDAwMy0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0"
}

Campos de la respuesta

idUUID del evento.
typeTipo de evento. Ver los valores más abajo.
conversation_idUUID de la conversación, o null en contact_field_changed.
contact_idUUID del contacto.
channelCanal de la conversación, como whatsapp o instagram, o null en contact_field_changed.
actor_typeQuién causó el evento. Ver los valores más abajo.
agentAgente de IA que lo causó (id y name), cuando se conoce, o null.
userPersona del equipo que lo causó desde Eclectic (id, name y email), o null.
dataCampos propios de cada tipo. Ver los tipos más abajo.
created_atFecha y hora del evento (ISO 8601, UTC).

Tipos de evento

Cada tipo indica qué trae en data.

manual_control_activatedUna persona tomó la conversación y la IA dejó de responder. data: reason (puede ser null).
manual_control_releasedLa conversación volvió a la IA, a mano o por tiempo. data: reason.
manual_control_lockedEl control manual quedó fijo y la IA no vuelve sola. data: reason.
manual_control_unlockedSe quitó el bloqueo del control manual. data: reason.
alert_triggeredSe derivó la conversación al equipo con una alerta. data: reason.
transfer_acceptedLa IA transfirió la conversación a una persona o a otro número. data: reason, target_user, attempt_number.
transfer_rejectedUna transferencia no se pudo hacer. data: reason, target_user, attempt_number.
transfer_fallback_requiredNingún destino de la transferencia estaba disponible. data: reason, target_user, attempt_number.
sentiment_analyzedSe analizó el sentimiento de la conversación. data: sentiment (POSITIVE, NEUTRAL o NEGATIVE).
conversation_archivedSe archivó la conversación. data: origin.
conversation_unarchivedSe desarchivó la conversación. data: origin.
conversation_resolvedUna persona marcó el caso como resuelto. data: reason.
agent_assignedSe asignó un agente de IA a la conversación. data: from_agent, to_agent.
agent_switchedSe cambió el agente de IA de la conversación. data: from_agent, to_agent.
agent_removedSe quitó el agente de IA de la conversación. data: from_agent, to_agent.
contact_field_changedCambiaron uno o más campos de un contacto. data: source y changes, una lista con field, custom (true para campos personalizados), from y to.

Valores de actor_type

ai_agentUn agente de IA de Eclectic.
humanUna persona de tu equipo, desde Eclectic o desde la app del canal (como WhatsApp Business). En ese segundo caso user viene en null.
apiUna llamada a la API pública de Eclectic.
systemReglas automáticas, temporizadores e integraciones (por ejemplo, la IA que retoma la conversación tras un tiempo sin respuesta del equipo).

Notas

Repite la solicitud con el next_cursor de cada respuesta hasta que llegue null. Una página puede traer menos eventos 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.
Se exportan los eventos de conversaciones asociadas a un contacto. No se incluyen las conversaciones de prueba, los chats internos ni los eventos internos de la plataforma (pedidos de Shopify, seguimientos, instrucciones al agente).
El historial de campos de contacto existe desde el 4 de agosto de 2026. Un mismo evento contact_field_changed agrupa todos los campos que cambiaron juntos.
Este endpoint tiene un límite de 120 solicitudes por minuto por negocio, aparte del de GET /messages. 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, un tipo desconocido o un cursor inválido), 401 (API key inválida o ausente), 429 (límite de uso).