Copy page

Guías

Métricas de las conversaciones para tu bodega de datos

Una fila por conversación con sus tiempos: cuándo entró, cuándo el agente la derivó a una persona, cuándo alguien la tomó, cuándo se cerró y quién la cerró. Sirve para llevarlas cada hora a BigQuery u otra bodega y medir ahí cuántas resuelve el agente solo, cuántas pasan a una persona y cuánto esperan.

Base de la API de Lelemon: https://api.lelemon.cl

Antes de empezar

Necesitas una credencial con el alcance conversations:read, la misma con la que lees una conversación. Se emite en Integraciones API del dashboard.

Los tiempos salen de un registro de cada paso de la conversación que existe desde el 19 de octubre de 2026. Una conversación anterior aparece recién cuando cambia, y le faltan los pasos de antes de esa fecha.

El pedido

Code
GET https://api.lelemon.cl/v1/external/metrics/conversations?from=2026-10-19T13:00:00Z&to=2026-10-19T14:00:00Z
Authorization: Bearer <tu credencial>

• from (obligatorio) y to (opcional, por omisión ahora) son fechas ISO 8601. Traen las conversaciones cuyo último cambio fue en ese rango, to sin incluir. El rango puede ser de hasta 31 días.
• limit (por omisión 50, hasta 500) y offset paginan. Mientras hasMore sea true, pide la página siguiente sumando limit al offset.

Para bajarlas cada hora: pide la última hora y guarda cada fila por conversationId, reemplazando la que tenías. Una conversación vuelve a venir cada vez que cambia, con todos sus tiempos al día.

Manda siempre to fijo, el mismo en todas las páginas de un barrido. Si una conversación cambia mientras paginas, pasa a la ventana siguiente y vuelve a venir ahí.

La respuesta

200 con data, limit, offset y hasMore. Cada fila de data trae:

Campo	Qué es
conversationId	El id de la conversación.
pipelineId, pipelineName	El embudo.
status, controlStatus, outcome	Cómo está ahora: su estado, quién la tiene (agent, escalated, human) y el motivo de cierre, si lo hay.
createdAt	Cuándo entró.
escalatedAt	La primera vez que el agente la derivó a una persona, o null.
takenAt, takenBy	La primera vez que una persona la tomó, y quién (null si la tomaron desde el celular).
closedAt	Cuándo se cerró, o null si sigue abierta.
closedBy	Quién la cerró: ai (el agente), human (una persona) o system (cierre por inactividad o seguimiento agotado).
resolvedByAi	true si la cerró el agente sin derivarla ni que nadie la tomara.
waitSeconds	Segundos entre la última derivación y que una persona la tomara, la primera vez que eso pasó. null si nadie la tomó después de una derivación.
aiSeconds, humanSeconds	Segundos que la atendió el agente y que la atendió una persona. El tiempo esperando a una persona no cuenta en ninguno. En una conversación abierta corren hasta su último cambio.
updatedAt	Su último cambio. Es el campo por el que filtra el rango.

Con eso salen, por ejemplo:

• Chats entrados: las filas con createdAt en el período, contadas sobre tu tabla completa (no sobre lo que bajaste en la última hora).
• Resueltos por el agente: las que tienen resolvedByAi en true.
• Pasados a una persona: las que tienen takenAt.
• Espera: el promedio de waitSeconds.

Errores

• 400 si falta from, si una fecha no es ISO 8601, si to no es posterior a from o si el rango pasa de 31 días.
• 401 sin credencial o con una revocada, y 403 si la credencial no tiene conversations:read.