API de analíticas e informes #

Estos endpoints de solo lectura le permiten extraer la actividad de su cuenta a sus propios paneles e informes: recuentos de eventos de mensajes, consumo de créditos, gasto en IA y los mismos gráficos e información que muestra el panel dentro de la aplicación. Esta guía cubre:

• Resumen — contadores de volumen de mensajes (enviados, entregados, leídos, respondidos, reservados, contactos creados, créditos).
• Créditos — un registro detallado y paginado del uso de créditos con totales y desgloses.
• Coste de IA — un resumen diario del gasto en IA.
• Series de métricas — una serie temporal lista para gráficos de una o más métricas, agrupadas por campaña, canal, agente de IA o número.
• Resultados de las conversaciones — conversaciones a lo largo del tiempo, agrupadas por las etiquetas de contacto que contienen (las etiquetas de cierre que aplica su agente).
• Costes de las conversaciones: el coste medio en créditos de una conversación gestionada únicamente por la IA frente a una en la que intervino su equipo.
• Perspectivas del panel y Perspectivas de IA del panel — los datos completos detrás del panel de la aplicación, incluidos los resúmenes escritos por la IA.
• Actividad de la entidad — la línea de tiempo de un contacto, trato o tarea individual.
• Recuentos de eventos agregados — una forma heredada en camelCase del Resumen que se mantiene para integraciones existentes.

Cada endpoint en esta página necesita un ámbito exacto, no ambos: pase como máximo uno de campaign_id (heredado) o agent_id donde el endpoint lo acepte. Enviar ambos devuelve 400, y un id que no está en su cuenta devuelve 404 en lugar de 403, por lo que los ids de otras cuentas permanecen imposibles de adivinar.

Solo dos endpoints filtran por etiqueta de contacto. tag_ids (con tag_match) es respetado por Perspectivas del panel y Recuentos de eventos agregados: esos son los dos que utiliza el filtro Todas las etiquetas del panel en la aplicación. Resumen, Series de métricas y Resultados de la conversación validan el parámetro (una lista de ID mal formada aún devuelve 400) pero no lo aplican: obtienes números de toda la cuenta, sin ningún error que te lo indique. No interpretes un total sin filtrar como uno filtrado por etiqueta.

Todas las rutas a continuación son relativas a la URL base de la API:

https://api.youraiconnector.com/v1

Cada solicitud debe estar autenticada. Consulte Autenticación para conocer los cuatro métodos aceptados. Los ejemplos aquí utilizan el encabezado X-API-Key (y una forma de parámetro de consulta para cURL).

Rango de fechas #

Los tres endpoints aceptan los mismos filtros de fecha opcionales:

Las fechas se interpretan en UTC. El rango es, por defecto, los últimos 30 días y tiene un límite de 366 días; un rango más amplio devuelve 400. from no debe ser posterior a to.

El indicador truncated #

Los endpoints de Resumen y Créditos limitan la cantidad de registros que escanea una sola solicitud. Si su rango es lo suficientemente activo como para alcanzar ese límite, la respuesta incluye "truncated": true. Cuando lo vea, los números se basan en un escaneo parcial; reduzca su rango de fechas (o navegue por páginas con una ventana más pequeña) para obtener cifras completas.

Resumen del volumen de mensajes #

Devuelve contadores de eventos de mensajes agregados para su cuenta, tanto como totales de rango como una serie diaria. Cada día en el rango aparece en by_date; los días sin actividad se rellenan con ceros. Opcionalmente, filtre por una sola campaña con campaign_id.

GET /analytics/summary

cURL

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Respuesta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}

Cada entrada en by_date tiene los mismos campos de contador que totals, además de un date.

Si proporciona un campaign_id que no pertenece a su cuenta, la respuesta será 404 con { "success": false, "error": "Campaign not found" }.

Uso de créditos #

Devuelve el uso de créditos durante el rango: una lista paginada de registros individuales, además de totales del rango y desgloses por motivo y por campaña.

GET /analytics/credits

Ajustes frente a consumo: Los cambios de saldo, como bonificaciones, renovaciones de planes y correcciones, están excluidos de totals y de los desgloses; no son consumo real. Aún aparecen en la lista records, marcados con "is_adjustment": true.

Los totales y desgloses solo aparecen en la primera página (cuando no se proporciona cursor). En las páginas siguientes, totals, by_reason, by_reason_cost y by_campaign se devuelven como null; solo continúa la matriz records. Esto evita volver a analizar todo el rango para cada página.

cURL

curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.

Respuesta (primera página)

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}

Notas de campo:

• amount — créditos cargados por el registro. Cero para registros facturados a su propia clave de API de proveedor.
• is_adjustment — true para cambios de saldo (excluidos de totales/desgloses).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — completados solo en registros facturados a su propia clave de API de proveedor; de lo contrario, cero o null.
• is_test — true para ejecuciones de prueba o en el entorno de pruebas (playground), que nunca se facturan.
• next_cursor — el cursor para la página siguiente, o null cuando no hay más registros.

Saldo de crédito #

GET /users/me/credits — la posición de crédito actual de su cuenta en una sola llamada: lo que queda por gastar, la asignación mensual y los ajustes de recarga automática y crédito bajo. El uso de crédito anterior es un historial; este es el saldo en este momento. Los miembros del equipo que lo soliciten necesitan acceso a la facturación; la clave del propietario de la cuenta siempre lo tiene.

curl "https://api.youraiconnector.com/v1/users/me/credits?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/users/me/credits", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { balance } = await res.json();

Respuesta (200)

{
  "success": true,
  "balance": 1837.5,
  "monthly_credits": 2000,
  "used_this_month": null,
  "auto_recharge_enabled": true,
  "low_credit_threshold": null
}

Las agencias pueden pasar sub_account_id para leer el saldo de una cuenta de cliente. Dentro de una automatización, el paso Verificar créditos devuelve los mismos campos.

Resumen de costes de IA #

Devuelve el resumen del gasto diario en IA de su cuenta. Esto lee totales diarios pre-agregados, por lo que es rápido incluso en rangos largos. Cada día en el rango aparece en days; los días sin actividad se rellenan con cero.

GET /analytics/ai-cost

cURL

curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Respuesta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}

Notas de campo:

• byok_usd — gasto facturado a las claves de API de su propio proveedor.
• platform_usd — la parte del gasto que se ejecutó en la plataforma en lugar de con su propia clave.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — los componentes de coste que conforman total_usd.
• by_provider — gasto en USD clasificado por nombre de proveedor de IA.
• Las cifras en USD solo se devuelven a las cuentas que utilizan su propia clave de proveedor. Para las cuentas que pagan con crédito, todos los campos de USD son cero y costs_redacted es true (los recuentos de llamadas permanecen visibles).

Series de métricas #

Devuelve una o más series temporales de métricas en una sola llamada, opcionalmente agrupadas por hasta dos dimensiones: el endpoint para vincular un gráfico. Una sola solicitud puede responder “enviados y respondidos por día, por canal, para esta campaña” sin necesidad de una llamada por campaña.

GET /analytics/series

Cada respuesta lleva una matriz labels (el eje temporal, relleno con ceros en todo el rango) y una entrada en series por grupo, cada una con una matriz por métrica solicitada alineada con labels. Las series posteriores a limit no se descartan: se colapsan en other_bucket, calculado como el total del rango menos las series devueltas, por lo que un gráfico renderizado siempre suma sus números reales; truncated es true siempre que eso sucede.

De dónde provienen los números: sent, delivered, read y replied provienen de los registros de mensajes, que llevan el canal y el número de envío. booked, contact_created y credits_spent provienen del flujo de eventos, que no lleva número de envío, por lo que esas métricas aterrizan en el depósito de número null cuando agrupa por number.

conversations cuenta las conversaciones (sesiones de chat) que comenzaron en cada segmento, y conversation_credits cuánto costaron esas conversaciones, calculadas exactamente igual que en Costes de conversación. Divida una por la otra por segmento para obtener el coste promedio por conversación a lo largo del tiempo. Cuando agrupa o filtra por campaña, agente, canal o número, una conversación cuenta para aquel al que pertenece su primer mensaje.

El rango de fechas de este endpoint está limitado a 92 días (más estricto que el límite de 366 días utilizado en otras partes de esta página).

cURL

curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()

Respuesta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}

Notas de campo:

• key — la identidad de una serie. Solo están presentes las claves de las dimensiones group_by solicitadas; una dimensión cuyo valor es desconocido para una fila (un mensaje sin campaña, un evento sin canal) vuelve como null en lugar de ser descartada, por lo que las series aún suman los totales.
• other_bucket — null cuando no se colapsó nada.
• Este endpoint devuelve 503 con "error_code": "analytics_unavailable" cuando la base de datos de informes no puede responder por su cuenta, en lugar de un 200 lleno de ceros: un gráfico con ceros se leería como un hecho.

Resultados de las conversaciones #

Devuelve los resultados de las conversaciones en un rango de fechas: un recuento diario de conversaciones bajo cada etiqueta de contacto, además de los totales del rango para respuestas, reservas, transferencias a un humano y conversaciones cuyo contacto no tiene ninguna etiqueta.

La etiqueta es una etiqueta de contacto: las etiquetas que su agente de IA aplica con su herramienta de etiquetas, reglas de autoetiquetado, la API o su equipo. No es una etiqueta por conversación. Una conversación se cuenta bajo las etiquetas que su contacto tiene en el momento de la solicitud, por lo que un contacto con varias etiquetas cuenta una vez bajo cada una, y una etiqueta eliminada posteriormente también desaparece de los días pasados. Asigne a su agente una etiqueta de cierre por resultado (por ejemplo, resolved_ai, handoff_asked_for_human) y este endpoint devolverá la contención y los motivos de la transferencia a lo largo del tiempo.

GET /analytics/outcomes

Pase group_by=tag para colapsar el eje temporal y obtener solo los totales del rango por etiqueta; en ese modo, labels está vacío y la matriz counts de cada etiqueta está vacía, mientras que total sigue estando poblado.

El rango de fechas de este endpoint está limitado a 92 días.

cURL

curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Respuesta

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag_id": "tag_8f2k1", "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag_id": "tag_c91xq", "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag_id": null, "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

Notas de campo:

• by_tag[].tag / by_tag[].tag_id — el nombre y el id de la etiqueta de contacto; ambos null en la fila de conversaciones cuyo contacto no tiene ninguna etiqueta. Se devuelven como máximo 20 etiquetas, empezando por el mayor volumen.
• totals.sessions — conversaciones distintas iniciadas en el rango. No es la suma de by_tag[].total: un contacto con tres etiquetas contribuye con una conversación a tres filas.
• totals.unresolved — conversaciones cuyo contacto no tiene ninguna etiqueta.
• totals.human_alerted — conversaciones transferidas a un humano; esto se registra en cada transferencia y no se mostraba anteriormente en ningún endpoint.
• Misma postura 503/analytics_unavailable que las Series de métricas cuando la base de datos de informes no puede responder.

Costes de las conversaciones #

Devuelve el coste medio de una conversación en un rango de fechas, desglosado según cómo se desarrolló. Este es el número que debe mostrar a un cliente como retorno de la inversión: lo que cuesta una conversación gestionada únicamente por la IA, junto a una en la que su equipo tuvo que intervenir.

GET /analytics/conversation-costs

curl "https://api.youraiconnector.com/v1/analytics/conversation-costs?from=2026-08-26&to=2026-09-24&apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "from": "2026-08-26",
  "to": "2026-09-24",
  "sessions": 564,
  "total_credits": 5957,
  "summary": {
    "contained": { "sessions": 503, "credits": 5168, "avg_credits": 10.2744 },
    "handed_off": { "sessions": 50, "credits": 781, "avg_credits": 15.62 },
    "no_ai": { "sessions": 11, "credits": 8, "avg_credits": 0.7273 }
  },
  "sessions_truncated": false
}

Notas de campo:

• Cuenta las conversaciones (sesiones de chat) que comenzaron en el rango, con los créditos cargados dentro de la ventana de cada conversación, restando los reembolsos. Los créditos gastados fuera de cualquier conversación (resúmenes diarios, tarifas mensuales, automatizaciones que no fueron iniciadas por un contacto, como webhooks o disparadores RSS) no forman parte de esto. Las ejecuciones de automatización y los pasos de IA iniciados por un contacto cuentan para la conversación de ese contacto desde el 26 de septiembre de 2026.
• contained: la IA respondió y nadie de su equipo tuvo que intervenir. handed_off: alguien envió un mensaje después de que la IA hubiera respondido, o la IA alertó a un humano. no_ai: la IA nunca respondió (por ejemplo, chats que su equipo gestiona con la IA pausada).
• Se cuentan como máximo 20 000 conversaciones; sessions_truncated es true cuando el rango contenía más, así que redúzcalo.
• Requiere el permiso de facturación para los miembros del equipo. Misma postura de 503/analytics_unavailable que la serie de métricas.
• Por contacto, la misma división se encuentra en Obtener coste de contacto.

Información del panel #

Devuelve la carga útil completa del panel para un rango de fechas en una sola llamada: un mapa de calor de tasa de respuesta por día de la semana y hora, la tabla de clasificación de campañas, el volumen por canal, los totales exactos por conexión, los desgloses de métricas por día (a nivel de cuenta, por canal y por número), el origen de los contactos, el tiempo de respuesta de la bandeja de entrada y un feed de actividad reciente. Esta es la carga útil de informes más completa de la API: impulsa directamente el panel de control de la aplicación.

GET /analytics/dashboard-insights

Este endpoint utiliza startDate/endDate (no from/to) porque comparte su implementación con el panel de control de la aplicación. El rango está limitado a 92 días y se ajusta, no se rechaza, cuando es más amplio.

Nulo significa no disponible, no cero. Varios bloques (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) se calculan a partir de la base de datos de informes y devuelven null cuando no puede responder para su cuenta. No renderice un bloque null como un gráfico vacío.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Respuesta (abreviada: esta carga útil es grande; consulte la Referencia de la API para ver el esquema completo)

{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}

Notas de campo:

• heatmap.buckets[].weekday — 0 es domingo hasta 6 es sábado.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — cada uno devuelve null de forma independiente cuando la base de datos de informes no está disponible para su cuenta; todos los demás bloques siguen respondiendo.

Información de IA del panel #

Devuelve tres breves perspectivas redactadas por IA sobre la mensajería de la cuenta durante un rango de fechas: un logro, algo a tener en cuenta y un consejo; frases que puede pegar directamente en un informe en lugar de números que aún debe interpretar. Generado únicamente a partir de las métricas de mensajes de la propia cuenta.

GET /analytics/dashboard-ai-insights

Este endpoint es a nivel de cuenta; no requiere un ámbito de campaña o agente.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Respuesta

{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}

Si falta startDate o endDate, se devuelve 400.

Cronología de actividad de la entidad #

Devuelve la actividad de un único contacto, trato o tarea como una sola cronología, de la más reciente a la más antigua: qué sucedió y cuándo, a través de mensajes, citas, notas y cambios de estado. Úselo para responder a “qué ha pasado con esta persona” sin tener que combinar varios endpoints de lista.

GET /analytics/entity-activity

cURL

curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()

Respuesta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}

Si falta entityType/entityId o es inválido, se devuelve 400. Una entidad que no existe en su cuenta devuelve 404, por lo que los ID de otras cuentas no se pueden adivinar.

Recuentos de eventos agregados (heredado) #

Devuelve los mismos recuentos de eventos agregados que el Resumen de volumen de mensajes, pero en el formato camelCase (contactCreated en lugar de contact_created, byDate en lugar de by_date) con el que se crearon algunas integraciones antiguas. Prefiera /analytics/summary para nuevas integraciones; este endpoint existe solo para que el panel de control de la aplicación y la API compartan una misma implementación.

GET /analytics/aggregate

cURL

curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}

Resumen de subcuentas de agencia #

Errores de la API de Analytics #

Los endpoints de Analytics devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}

En un endpoint de análisis, un formato de fecha no válido o una ventana fuera de rango devuelve 400, y un campaign_id o agent_id desconocido devuelve 404. Enviar tanto campaign_id como agent_id en un endpoint que acepta cualquiera de los dos también es un 400; pase como máximo uno. Los endpoints de informes exclusivos de PG (Series de métricas, Resultados de conversaciones, Resumen de agencia) devuelven 503 con "error_code": "analytics_unavailable" en lugar de un 200 lleno de ceros cuando la base de datos de informes no puede responder para su cuenta; vuelva a intentarlo en breve. Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API o, en el resumen de agencia, su cuenta no es de tipo Agencia/Desarrollador), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Próximos pasos #

• Autenticación — las cuatro formas de autenticar una solicitud.
• Errores y límites de tasa — códigos de estado y el límite de 300 solicitudes/min.
• API de agentes de IA — los agentes por los cuales se pueden filtrar estas cifras.