> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API d'analítiques

> Consulta les analítiques de les teves converses: mètriques agregades per agent i canal, i el detall de cada conversa

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.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31"
```

> [!NOTE]
>
> 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

```
GET https://cloud.lovi.ai/functions/v1/analytics
```

### Paràmetres de l'URL

| Paràmetre | Obligatori | Descripció |
| - | - | - |
| `type` | Sí | `metrics` o `chats`. |
| `date_from` | Sí | Primer dia, `YYYY-MM-DD`, inclòs. |
| `date_to` | Sí | Últim dia, `YYYY-MM-DD`, inclòs. L'interval pot abastar fins a **31 dies**. |
| `tz` | No | Zona horària IANA amb què s'interpreten els dies i es construeixen les sèries diària i horària. Per defecte `Europe/Madrid`. Exemples: `UTC`, `America/Bogota`. |
| `channels` | No | Canals separats per comes: `voice`, `whatsapp`, `web`, `instagram`, `facebook`… |
| `agents` | No | Ids d'agent (UUID) separats per comes. |
| `languages` | No | Codis d'idioma de l'usuari separats per comes, p. ex. `es,pt`. |
| `limit` | No | Només `chats`. Converses per pàgina, d'1 a 100. Per defecte 100. |
| `cursor` | No | Només `chats`. El `next_cursor` que va retornar la pàgina anterior. |

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.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31&channels=voice"
```

```json theme={null}
{
  "tz": "Europe/Madrid",
  "from": "2026-09-30T22:00:00.000Z",
  "to": "2026-10-31T23:00:00.000Z",
  "data": [
    {
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "channel": "voice",
      "conversations": 12480,
      "escalated": 4120,
      "contained_pct": 67.0,
      "avg_duration_s": { "all": 109, "without_transfer": 120, "with_transfer": 86 },
      "whatsapp_notifications": 1210,
      "unique_users": 7950,
      "recontacts": 2480,
      "daily": [
        { "date": "2026-10-01", "conversations": 410, "escalated": 151 }
      ],
      "hourly": [
        { "hour": 9, "conversations": 1320 },
        { "hour": 10, "conversations": 1544 }
      ]
    }
  ]
}
```

| Camp | Descripció |
| - | - |
| `agent` | Agent d'IA que va atendre les converses (`id`, `name`). `null` si la conversa no té agent. |
| `channel` | Canal de la conversa. `n/a` si no va quedar registrat. |
| `conversations` | Converses iniciades a l'interval (en veu, trucades). |
| `escalated` | Converses transferides a un humà (tenen un esdeveniment `chat_escalated`). |
| `contained_pct` | `(conversations − escalated) / conversations × 100`. Part que gestiona la IA sense transferir. **No és una taxa de resolució.** |
| `avg_duration_s` | Durada mitjana de la trucada en segons: global, sense transferència i amb transferència. `null` en canals sense durada (només la veu la registra). |
| `whatsapp_notifications` | Notificacions de WhatsApp enviades des d'aquestes converses (esdeveniments `notification_sent`). |
| `unique_users` | Usuaris diferents (en veu, números de telèfon diferents). |
| `recontacts` | Usuaris amb 2 converses o més a l'interval. Taxa de recontacte = `recontacts / unique_users`. |
| `daily` | Converses i transferències per dia, a `tz`. Els dies sense converses no hi apareixen. |
| `hourly` | Converses per hora del dia (0–23), a `tz`. Les hores sense converses no hi apareixen. |

> [!TIP]
>
> **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.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=chats&date_from=2026-10-01&date_to=2026-10-01&channels=voice&limit=100"
```

```json theme={null}
{
  "data": [
    {
      "id": "29d67962-119b-406c-b172-d66cf179975e",
      "created_at": "2026-10-01T05:58:40.4431Z",
      "ended_at": "2026-10-01T05:58:48Z",
      "last_message_at": null,
      "status": "aiagent",
      "channel": "voice",
      "phone": "34600000000",
      "language": "es",
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "escalated_to_human": true,
      "escalated_at": "2026-10-01T05:58:45.12Z",
      "attended_by_human": false,
      "human_agents": [],
      "whatsapp_notifications": 0,
      "inquiry_set": null,
      "parameters": {
        "channel": "voice",
        "call_length": 8,
        "phone_call": "+34600000000",
        "voice_inbound": true,
        "conversation_recording_url": "https://…"
      }
    }
  ],
  "next_cursor": "MjAyNi0xMC0wMVQwNjowMjoxMS4xMjM0NTZ8…"
}
```

| Camp | Descripció |
| - | - |
| `id` | Id de la conversa. |
| `created_at`, `ended_at`, `last_message_at` | Inici, final i últim missatge, en UTC. |
| `status` | Amb qui és la conversa: `aiagent`, `human`, `queue` (esperant un humà) o `push` (iniciada per una notificació). |
| `channel`, `language` | Copiats de `parameters.channel` i `parameters.lang_user` per comoditat. Si una trucada no va desar `channel`, es retorna `voice`. |
| `phone` | Telèfon del contacte, només dígits i sense `+` (format E.164), o `null` si la conversa no té cap número (per exemple, al widget web). |
| `agent` | Agent d'IA de la conversa (`id`, `name`). |
| `escalated_to_human`, `escalated_at` | Si es va transferir a un humà i quan (primera transferència). |
| `attended_by_human` | Si un agent humà va escriure almenys un missatge. |
| `human_agents` | Agents humans que van escriure a la conversa (`id`, `name`). Pot anar buit encara que `attended_by_human` sigui `true`: els missatges enviats des d'un CRM extern no s'atribueixen a una persona. |
| `whatsapp_notifications` | Notificacions de WhatsApp enviades des de la conversa. |
| `inquiry_set` | Campanya d'enviament (inquiry set) de la qual ve la conversa: `id` i `name` (el nom que se li va donar en crear l'enviament). `null` si la conversa no ve d'un enviament. `name` pot ser `null` si la campanya ja no existeix. |
| `parameters` | **Tots** els paràmetres desats de la conversa, sense filtrar. Les claus depenen del canal i de la configuració del teu agent (en veu: `call_length`, `phone_call`, `voice_inbound`, `session_call_id`, `conversation_recording_url`…; a més de qualsevol paràmetre propi que desi el teu agent). Si la conversa ve d'un enviament, `parameters.inquiry_set_id` porta el **nom** de la campanya; l'id és a `inquiry_set.id`. |

### 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.

```python theme={null}
import requests

URL = "https://cloud.lovi.ai/functions/v1/analytics"
HEADERS = {"x-api-key": "YOUR_API_KEY"}
params = {"type": "chats", "date_from": "2026-10-01", "date_to": "2026-10-31", "channels": "voice"}

chats = []
while True:
    page = requests.get(URL, headers=HEADERS, params=params, timeout=60).json()
    chats.extend(page["data"])
    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

print(len(chats), "converses")
```

## Errors

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

| Codi | Quan |
| - | - |
| `400` | Falta la clau (`Missing access_key parameter`), `type` no vàlid, dates no vàlides, interval de més de 31 dies, o `tz`, `limit`, `agents`, `channels` o `cursor` no vàlids. |
| `403` | La clau existeix però no té el permís `analytics_api`. |
| `404` | Clau no vàlida o revocada. |
| `405` | Mètode diferent de `GET`. |
| `500` | Error intern. Torna-ho a provar al cap d'uns segons; si persisteix, contacta amb el suport indicant l'hora de la petició. |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.