Stats API

Este endpoint es el núcleo del sistema de estadísticas de uContact. Permite obtener datos históricos y agregados sobre el rendimiento de agentes y campañas. Es configurable a través de parámetros para agrupar, filtrar y personalizar las métricas devueltas.

• Método: POST
• URL: https://<dominio>.ucontactcloud.com/api/stats

Descripción General

El endpoint consulta una base de datos de telemetría (ccrepo) para recuperar métricas. La petición se realiza mediante POST, enviando los parámetros de configuración en la URL (Query Params) y los filtros de recursos (agentes o campañas) en el cuerpo de la petición (Request Body).

Query Params

Estos son los parámetros que se envían en la URL.

Parámetros Obligatorios

Parámetro	Tipo	Descripción	Ejemplo
type	String	El tipo de recurso sobre el cual se desea obtener estadísticas.	agent, campaign
initialdate	String	La fecha y hora de inicio del rango de consulta, incluyendo la zona horaria. El formato debe ser "AAAA-MM-DD HH:mm:ss ZonaHoraria".	2025-09-01 00:00:00 America/Chicago
finaldate	String	La fecha y hora de fin del rango de consulta, incluyendo la zona horaria. Mismo formato que initialdate.	2025-09-07 23:59:59 America/Chicago
groupnum	String	Define el intervalo de agrupación. Puede ser un número en minutos o una cadena predefinida.	Numérico: 15, 30, 60 Texto: mth (mes), bim (bimestre), tri (trimestre), sem (semestre), yer (año)
channels	String	Lista de canales separados por coma. Es obligatorio únicamente si type es campaign.	telephony,sms,email,whatsapp,messenger,instagram

Parámetros opcionales

Parámetro	Tipo	Descripción	Ejemplo
metrics	String	Una lista separada por comas de las métricas específicas que se desean obtener. Si no se envía, se devuelven todas las métricas por defecto. La lista de métricas se puede encontrar acá: campañas y agentes.	connected,inboundAnswered
byResource	Boolean	Si es true, los resultados se agruparán por cada recurso individual (ej. se retornará una fila por cada agente). Por defecto es false.	true
byChannel	Boolean	Si es true, los resultados se agruparán por canal. Útil principalmente cuando type es campaign. Por defecto es false.	true

Request Body

El cuerpo de la petición se utiliza para especificar los recursos exactos que se desean consultar.

• Content-Type: application/json
• Cuerpo (Body): Un objeto JSON que contiene una clave stats. El valor de stats es una cadena de texto con identificadores de los recursos separados por comas.

Para filtrar usuarios

{
   "stats": "Agent1,Agent2,Agent3"
}

Para filtrar campañas

{
   "stats": "Sales,Support"
}

Códigos de respuesta

• 200 OK: La solicitud fue exitosa y la respuesta contiene los datos.
• 400 Bad Request: Faltan parámetros obligatorios o alguno tiene un formato incorrecto.
• 408 Request Timeout: La consulta a la base de datos tardó demasiado en ejecutarse.
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor.

Ejemplos de Uso

Estadísticas de agentes por recurso

Obtener las métricas específicas de los agentes Agent1, Agent2 y Agent3 para un dia específico, agrupadas cada hora y desglosadas por cada agente.

URL

/api/stats
?type=agent
&initialdate=2025-09-08 00:00:00 America/Mexico_City
&finaldate=2025-09-08 23:59:59 America/Mexico_City
&groupnum=60
&metrics=inInteractions,outInteractions,connected
&byResource=true

Body

{
   "stats": "Agent1,Agent2,Agent3"
}

Respuesta de Ejemplo

[
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent1",
        "inInteractions": 10,
        "outInteractions": 5,
        "connected": 3540
    },
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent2",
        "inInteractions": 12,
        "outInteractions": 3,
        "connected": 3480
    },
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent3",
        "inInteractions": 4,
        "outInteractions": 3,
        "connected": 3440
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent1",
        "inInteractions": 8,
        "outInteractions": 6,
        "connected": 3510
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent2",
        "inInteractions": 15,
        "outInteractions": 2,
        "connected": 3550
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent3",
        "inInteractions": 9,
        "outInteractions": 4,
        "connected": 3490
    }
]

Métricas específicas de una campaña por canal

Obtener solo las métricas de cantidad de interacciones entrantes y salientes para la campaña Ventas en los canales de telephony y whatsapp, con los resultados desglosados por canal.

URL

/api/stats
?type=campaign
&initialdate=2025-09-01 00:00:00 UTC
&finaldate=2025-09-30 23:59:59 UTC
&groupnum=mth
&channels=telephony,whatsapp
&metrics=inInteractions,outInteractions
&byChannel=true

Body

{
   "stats": "Ventas"
}

Respuesta de Ejemplo

[
    {
        "date": "Sep 1, 2025, 12:00:00 AM",
        "resource": "Ventas",
        "channel": "telephony",
        "inInteractions": 1500,
        "outInteractions": 350
    },
    {
        "date": "Sep 1, 2025, 12:00:00 AM",
        "resource": "Ventas",
        "channel": "whatsapp",
        "inInteractions": 2200,
        "outInteractions": 150
    }
]