Saltar al contingut principal
L’API d’analítiques és un endpoint de només lectura que retorna les dades de les converses de la teva empresa. Té dos modes:
  • type=metrics: xifres agregades per agent i canal (converses, transferències a humà, contenció de la IA, durada de les trucades, notificacions de WhatsApp, recontactes i sèries per dia i per hora). Per a informes i quadres de comandament.
  • type=chats: una fila per conversa amb tots els seus paràmetres, paginada. Per exportar o quadrar les dades en brut.

🔑 Autenticació

Cada petició necessita una clau API amb el permís analytics_api. Crea-la des del teu perfil a Lovi (Perfil → API Key), marcant el permís Analítiques (API); no és la mateixa clau que fa servir el widget web. Envia la clau a la capçalera x-api-key (recomanat) o al paràmetre access_key de l’URL.
L’empresa surt sempre de la clau. Una clau només pot llegir les dades de la seva pròpia empresa i no hi ha cap paràmetre per triar-ne una altra.

Endpoint

Paràmetres de l’URL

Els dies s’interpreten a tz: date_from=2026-10-01&date_to=2026-10-31 amb tz=Europe/Madrid cobreix de l’1 d’octubre a les 00:00 a l’1 de novembre a les 00:00, hora de Madrid. Els canvis d’hora estan contemplats. Totes les dates de les respostes van en UTC (ISO 8601 acabat en Z).

Mètriques (type=metrics)

Retorna una entrada per agent i canal, ordenades per nombre de converses.
Comparar amb el mes anterior: crida l’endpoint dues vegades, una per mes, i calcula’n la diferència. Contenció només els dies amb agents humans: fes servir daily i queda’t amb els dies amb escalated > 0.

Converses (type=chats)

Retorna les converses de l’interval una a una, de la més antiga a la més recent, 100 per pàgina per defecte. Només inclou converses tancades (amb ended_at): les que encara són obertes no apareixen fins que acaben.

Paginació

Mentre next_cursor no sigui null, demana la pàgina següent amb els mateixos paràmetres més cursor=<next_cursor>. Les converses van ordenades per created_at i id, de manera que cap no es repeteix ni se salta entre pàgines.

Errors

Els errors retornen un JSON { "success": false, "message": "…" }.

Límits i bones pràctiques

  • Fins a 31 dies per petició i 100 converses per pàgina.
  • Una petició de metrics d’un mes sencer triga uns segons. Per a un informe mensual o diari n’hi ha prou amb una crida per període: no cal consultar en bucle.
  • Per exportar un mes sencer de converses, recorre les pàgines una darrere l’altra, no en paral·lel.
  • Guarda la clau en secret i al teu servidor. No la facis servir en un navegador ni en una app mòbil.