# API d'analytique et de rapports Ces points de terminaison en lecture seule vous permettent d'intégrer l'activité de votre compte dans vos propres tableaux de bord et rapports : nombre d'événements de message, consommation de crédits, dépenses en IA, ainsi que les mêmes graphiques et informations que ceux affichés dans le tableau de bord de l'application. Ce guide couvre : - **Résumé** — compteurs de volume de messages (envoyés, délivrés, lus, répondus, réservés, contacts créés, crédits). - **Crédits** — un registre détaillé et paginé de l'utilisation des crédits avec totaux et ventilations. - **Coût de l'IA** — un cumul quotidien des dépenses en IA. - **Séries de métriques** — une série temporelle prête à être utilisée dans un graphique pour une ou plusieurs métriques, regroupées par campagne, canal, agent IA ou numéro. - **Résultats des conversations** — comment les conversations se sont terminées, par étiquette de résultat attribuée par l'IA. - **Informations du tableau de bord** et **Informations IA du tableau de bord** — l'intégralité des données derrière le tableau de bord de l'application, y compris les résumés rédigés par l'IA. - **Activité de l'entité** — la chronologie d'un contact, d'une opportunité ou d'une tâche spécifique. - **Nombre d'événements agrégés** — une forme héritée en camelCase du résumé, conservée pour les intégrations existantes. Chaque point de terminaison sur cette page nécessite une portée exacte, et non les deux : transmettez au plus l'une des valeurs `campaign_id` (héritée) ou `agent_id` là où le point de terminaison l'accepte. L'envoi des deux renvoie `400`, et un identifiant qui n'est pas sur votre compte renvoie `404` plutôt que `403`, afin que les identifiants des autres comptes restent impossibles à deviner. Tous les chemins ci-dessous sont relatifs à l'URL de base de l'API : ``` https://api.youraiconnector.com/v1 ``` Chaque requête doit être authentifiée. Consultez [Authentification](authentication.md) pour connaître les quatre méthodes acceptées. Les exemples ici utilisent l'en-tête `X-API-Key` (et une forme de paramètre de requête pour cURL). --- ## Plage de dates Les trois points de terminaison acceptent les mêmes filtres de date optionnels : | Paramètre | Description | |---|---| | `from` | Début de la plage, `YYYY-MM-DD`, inclusif. Par défaut, il y a 30 jours. | | `to` | Fin de la plage, `YYYY-MM-DD`, inclusif. Par défaut, aujourd'hui. | Les dates sont interprétées en UTC. La plage par défaut est fixée aux **30 derniers jours** et est limitée à **366 jours** — une plage plus large renvoie `400`. `from` ne doit pas être postérieur à `to`. ### L'indicateur `truncated` Les points de terminaison **Résumé** et **Crédits** limitent le nombre d'enregistrements qu'une seule requête peut analyser. Si votre plage est suffisamment chargée pour atteindre cette limite, la réponse inclut `"truncated": true`. Lorsque vous le voyez, les chiffres sont basés sur une analyse partielle — réduisez votre plage de dates (ou paginez avec une fenêtre plus petite) pour obtenir des chiffres complets. ::: note **Remarque :** Les chiffres relatifs aux coûts et aux jetons ne sont inclus que pour les appels d'IA facturés via vos propres clés API de fournisseur. Lorsque les chiffres de coût sont masqués pour votre compte, la réponse définit `"costs_redacted": true` et les champs de coût sont renvoyés à zéro. ::: --- ## Résumé du volume de messages Renvoie des compteurs d'événements de messages agrégés pour votre compte, à la fois sous forme de totaux sur la plage et de série quotidienne. Chaque jour de la plage apparaît dans `by_date` — les jours sans activité sont remplis de zéros. Filtrez éventuellement sur une seule campagne avec `campaign_id`. `GET /analytics/summary` | Paramètre | Requis | Description | |---|---|---| | `from` | Non | Début de la plage, `YYYY-MM-DD`. | | `to` | Non | Fin de la plage, `YYYY-MM-DD`. | | `campaign_id` | Non | Compter uniquement les événements appartenant à cette campagne. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** ```json { "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 } ``` Chaque entrée dans `by_date` possède les mêmes champs de compteur que `totals`, plus un `date`. Si vous transmettez un `campaign_id` qui n'appartient pas à votre compte, la réponse sera `404` avec `{ "success": false, "error": "Campaign not found" }`. --- ## Utilisation des crédits Renvoie l'utilisation des crédits sur la plage définie : une liste paginée d'enregistrements individuels, ainsi que les totaux de la plage et les répartitions par motif et par campagne. `GET /analytics/credits` | Paramètre | Requis | Description | |---|---|---| | `from` | Non | Début de la plage, `YYYY-MM-DD`. | | `to` | Non | Fin de la plage, `YYYY-MM-DD`. | | `campaign_id` | Non | Inclure uniquement l'utilisation attribuée à cette campagne. | | `limit` | Non | Taille de page pour `records`, de 1 à 100. Par défaut à 50. | | `cursor` | Non | Transmettez le `next_cursor` de la page précédente pour récupérer la page suivante. | > **Ajustements vs consommation :** Les changements de solde tels que les bonus, les renouvellements de forfait et les corrections sont **exclus** de `totals` et des répartitions — il ne s'agit pas d'une consommation réelle. Ils apparaissent toujours dans la liste `records`, marqués avec `"is_adjustment": true`. **Les totaux et les répartitions n'apparaissent que sur la première page** (lorsqu'aucun `cursor` n'est fourni). Sur les pages suivantes, `totals`, `by_reason`, `by_reason_cost` et `by_campaign` sont renvoyés comme `null` — seul le tableau `records` continue. Cela évite de re-scanner toute la plage pour chaque page. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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. ``` **Réponse** (première page) ```json { "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 } ``` **Notes sur les champs :** - `amount` — crédits facturés pour l'enregistrement. Zéro pour les enregistrements facturés à votre propre clé API de fournisseur. - `is_adjustment` — `true` pour les changements de solde (exclus des totaux/répartitions). - `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `ai_model`, `request_id` — renseignés uniquement sur les enregistrements facturés à votre propre clé API de fournisseur ; zéro ou `null` sinon. - `is_test` — `true` pour les exécutions de test/bac à sable, qui ne sont jamais facturées. - `next_cursor` — le curseur pour la page suivante, ou `null` lorsqu'il n'y a plus d'enregistrements. --- ## Récapitulatif des coûts IA Renvoie le récapitulatif des dépenses IA par jour pour votre compte. Cette fonction lit des totaux quotidiens pré-agrégés, elle est donc rapide même sur de longues plages. Chaque jour de la plage apparaît dans `days` — les jours sans activité sont remplis avec des zéros. `GET /analytics/ai-cost` | Paramètre | Requis | Description | |---|---|---| | `from` | Non | Début de la plage, `YYYY-MM-DD`. | | `to` | Non | Fin de la plage, `YYYY-MM-DD`. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** ```json { "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 } ``` **Notes sur les champs :** - `byok_usd` — dépenses facturées sur vos propres clés API de fournisseur. - `platform_usd` — la part des dépenses exécutées sur la plateforme plutôt qu'avec votre propre clé. - `input_usd`, `output_usd`, `cache_creation_usd`, `cache_read_usd` — les composantes de coût qui constituent `total_usd`. - `by_provider` — dépenses en USD classées par nom de fournisseur d'IA. - Les chiffres en USD ne sont renvoyés qu'aux comptes qui utilisent leur propre clé de fournisseur. Pour les comptes payant par crédit, chaque champ USD est à zéro et `costs_redacted` est `true` (le nombre d'appels reste visible). --- ## Séries de métriques Renvoie une ou plusieurs séries temporelles de métriques en un seul appel, éventuellement regroupées par deux dimensions au maximum — le point de terminaison pour lier un graphique. Une seule requête peut répondre à « envoyés et répondus par jour, par canal, pour cette campagne » sans avoir à effectuer un appel par campagne. `GET /analytics/series` Chaque réponse contient un tableau `labels` (l'axe temporel, rempli de zéros sur toute la plage) et une entrée dans `series` par groupe, chacune contenant un tableau par métrique demandée aligné sur `labels`. Les séries au-delà de `limit` ne sont pas supprimées — elles sont regroupées dans `other_bucket`, calculé comme le total de la plage moins les séries renvoyées, de sorte qu'un graphique rendu correspond toujours à vos chiffres réels ; `truncated` est `true` chaque fois que cela se produit. D'où proviennent les chiffres : `sent`, `delivered`, `read` et `replied` proviennent des enregistrements de messages, qui portent le canal et le numéro d'envoi. `booked`, `contact_created` et `credits_spent` proviennent du flux d'événements, qui ne porte aucun numéro d'envoi, donc ces métriques atterrissent dans le compartiment `null`-number lorsque vous regroupez par `number`. | Paramètre | Requis | Description | |---|---|---| | `from` | Non | Début de la plage, `YYYY-MM-DD`. Par défaut, il y a 30 jours. | | `to` | Non | Fin de la plage, `YYYY-MM-DD`. Par défaut, aujourd'hui. | | `metrics` | Non | Liste séparée par des virgules parmi `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. Par défaut `sent,replied`. Une métrique inconnue renvoie `400`. | | `group_by` | Non | Liste séparée par des virgules de deux dimensions maximum parmi `date`, `campaign`, `channel`, `agent`, `number`. `date` est accepté mais n'a aucun effet — chaque réponse contient déjà l'axe temporel. Omettez pour une seule série à l'échelle du compte. | | `granularity` | Non | `day` (par défaut), `week` ou `month`. Les compartiments hebdomadaires commencent le lundi, les mensuels le 1er. | | `limit` | Non | Combien de séries renvoyer avant que le reste ne soit regroupé dans `other_bucket`, de 1 à 50. Par défaut 12. | | `campaign_id` | Non | Compter uniquement l'activité appartenant à cette campagne. Hérité ; préférez `agent_id`. | | `agent_id` | Non | Compter uniquement l'activité appartenant à cet agent IA. | | `channel` | Non | Compter uniquement l'activité sur ce canal, par exemple `whatsapp`. | La plage de dates de ce point de terminaison est limitée à **92 jours** (plus stricte que la limite de 366 jours utilisée ailleurs sur cette page). **cURL** ```bash 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** ```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** ```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() ``` **Réponse** ```json { "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 } ``` **Notes sur les champs :** - `key` — l'identité d'une série. Seules les clés des dimensions `group_by` demandées sont présentes ; une dimension dont la valeur est inconnue pour une ligne (un message sans campagne, un événement sans canal) revient sous la forme `null` plutôt que d'être supprimée, afin que les séries s'ajoutent toujours aux totaux. - `other_bucket` — `null` lorsque rien n'a été regroupé. - Ce point de terminaison renvoie `503` avec `"error_code": "analytics_unavailable"` lorsque la base de données de rapports ne peut pas répondre pour votre compte, plutôt qu'un `200` rempli de zéros — un graphique à zéro serait interprété comme un fait. --- ## Résultats des conversations Renvoie la manière dont les conversations se sont terminées sur une plage de dates : un décompte quotidien pour chaque étiquette de résultat attribuée par l'IA, plus les totaux de la plage pour les réponses, les réservations, les transferts à un humain et les conversations que l'IA n'a jamais classées. `GET /analytics/outcomes` Transmettez `group_by=tag` pour réduire l'axe temporel et obtenir uniquement les totaux de la plage par étiquette — dans ce mode, `labels` est vide et le tableau `counts` de chaque étiquette est vide, tandis que `total` est toujours renseigné. | Paramètre | Requis | Description | |---|---|---| | `from` | Non | Début de la plage, `YYYY-MM-DD`. Par défaut, il y a 30 jours. | | `to` | Non | Fin de la plage, `YYYY-MM-DD`. Par défaut, aujourd'hui. | | `campaign_id` | Non | Compter uniquement les conversations avec des contacts actuellement dans cette campagne. Obsolète ; préférez `agent_id`. | | `agent_id` | Non | Compter uniquement les résultats appartenant à cet agent IA. | | `group_by` | Non | `date` (par défaut) conserve les totaux par jour ; `tag` agrège les données sur le total de la plage. | La plage de dates de ce point de terminaison est limitée à **92 jours**. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** ```json { "success": true, "from": "2026-05-01", "to": "2026-05-31", "group_by": "date", "labels": ["2026-05-01", "2026-05-02"], "by_tag": [ { "tag": "interested", "total": 84, "counts": [3, 5] }, { "tag": "not_interested", "total": 40, "counts": [1, 2] }, { "tag": null, "total": 12, "counts": [0, 1] } ], "totals": { "sessions": 260, "replied": 210, "booked": 35, "human_alerted": 18, "unresolved": 12 } } ``` **Notes sur les champs :** - `by_tag[].tag` — `null` pour les conversations auxquelles l'IA n'a jamais attribué de balise de résultat. - `totals.human_alerted` — conversations transférées à un humain ; ceci est inscrit lors de chaque transfert et n'était pas précédemment exposé par un point de terminaison. - Même posture `503`/`analytics_unavailable` que la série de métriques lorsque la base de données de rapports ne peut pas répondre. --- ## Informations du tableau de bord Renvoie la charge utile complète du tableau de bord pour une plage de dates en un seul appel : une carte thermique du taux de réponse par jour de la semaine et par heure, le classement des campagnes, le volume par canal, les totaux exacts par connexion, les ventilations des métriques par jour (à l'échelle du compte, par canal et par numéro), l'origine des contacts, le temps de réponse de la boîte de réception et un flux d'activité récent. Il s'agit de la charge utile de rapport la plus riche de l'API — elle alimente directement le tableau de bord de l'application. `GET /analytics/dashboard-insights` | Paramètre | Requis | Description | |---|---|---| | `startDate` | Oui | Début de la plage, `YYYY-MM-DD`. | | `endDate` | Oui | Fin de la plage, `YYYY-MM-DD`. | | `campaignId` | Non | Inclure uniquement l'activité appartenant à cette campagne (`campaign_id` également accepté). Obsolète ; préférez `agent_id`. | | `agent_id` | Non | Inclure uniquement l'activité appartenant à cet agent IA (`agentId` également accepté). Dans le cadre d'un agent, le classement des campagnes est établi uniquement à partir de l'activité de cet agent. | Ce point de terminaison utilise `startDate`/`endDate` (et non `from`/`to`) car il partage son implémentation avec le tableau de bord de l'application. La plage est limitée à 92 jours et est **tronquée, et non rejetée**, lorsqu'elle est plus large. > **Null signifie indisponible, pas zéro.** Plusieurs blocs (`numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`) sont calculés à partir de la base de données de rapports et renvoient `null` lorsqu'elle ne peut pas répondre pour votre compte. Ne rendez pas un bloc `null` comme un graphique vide. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** (abrégée — cette charge utile est volumineuse ; consultez la [Référence de l'API](reference.md) pour le schéma complet) ```json { "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 } } ``` **Notes sur les champs :** - `heatmap.buckets[].weekday` — `0` correspond au dimanche et `6` au samedi. - `numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`, `ai_human_split` — chacun est indépendamment `null` lorsque la base de données de rapports est indisponible pour votre compte ; tous les autres blocs sont toujours renvoyés. --- ## Informations IA du tableau de bord Renvoie trois courtes informations rédigées par l'IA sur la messagerie du compte sur une plage de dates : une réussite, un point à surveiller et un conseil — des phrases que vous pouvez copier directement dans un rapport plutôt que des chiffres que vous devez encore interpréter. Généré uniquement à partir des métriques de message du compte. `GET /analytics/dashboard-ai-insights` | Paramètre | Requis | Description | |---|---|---| | `startDate` | Oui | Début de la plage, `YYYY-MM-DD`. | | `endDate` | Oui | Fin de la plage, `YYYY-MM-DD`. | Ce point de terminaison s'applique à l'ensemble du compte — il ne nécessite aucune portée de campagne ou d'agent. **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** ```json { "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." } ] } } ``` L'absence de `startDate` ou `endDate` renvoie `400`. --- ## Chronologie de l'activité de l'entité Renvoie l'activité d'un seul contact, d'une seule transaction ou d'une seule tâche sous forme de chronologie, du plus récent au plus ancien : ce qui s'est passé et quand, à travers les messages, les rendez-vous, les notes et les changements de statut. Utilisez-le pour répondre à la question « que s'est-il passé avec cette personne » sans avoir à combiner plusieurs points de terminaison de liste. `GET /analytics/entity-activity` | Paramètre | Requis | Description | |---|---|---| | `entityType` | Oui | `contact`, `deal` ou `task`. | | `entityId` | Oui | ID de l'enregistrement dont la chronologie doit être renvoyée. | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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() ``` **Réponse** ```json { "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\"" } ] } } ``` Un `entityType`/`entityId` manquant ou invalide renvoie `400`. Une entité qui n'existe pas sur votre compte renvoie `404`, afin que les identifiants des autres comptes restent impossibles à deviner. --- ## Nombre d'événements agrégés (hérité) Renvoie les mêmes nombres d'événements agrégés que le [Résumé du volume de messages](#message-volume-summary), mais au format camelCase (`contactCreated` plutôt que `contact_created`, `byDate` plutôt que `by_date`) sur lequel certaines intégrations plus anciennes ont été construites. Privilégiez `/analytics/summary` pour les nouvelles intégrations — ce point de terminaison n'existe que pour que le tableau de bord intégré et l'API partagent une seule implémentation. `GET /analytics/aggregate` | Paramètre | Requis | Description | |---|---|---| | `startDate` | Non | Début de la plage, date ou date-heure ISO. Utilise par défaut la même fenêtre que `/analytics/summary`. | | `endDate` | Non | Fin de la plage, date ou date-heure ISO. | | `campaignId` | Non | Compter uniquement les événements appartenant à cette campagne (`campaign_id` également accepté). Hérité ; privilégiez `agent_id`. | | `agent_id` | Non | Compter uniquement les événements appartenant à cet agent IA (`agentId` également accepté). | **cURL** ```bash curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY" ``` **Réponse** ```json { "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 } } ] } } ``` --- ## Regroupement des sous-comptes d'agence --- ## Erreurs de l'API Analytics Les points de terminaison Analytics renvoient l'enveloppe d'erreur standard : ```json { "success": false, "error": "Date range too large. Maximum is 366 days." } ``` Sur un point de terminaison analytique, un format de date invalide ou une fenêtre hors plage renvoie `400`, et un `campaign_id` ou `agent_id` inconnu renvoie `404`. Envoyer à la fois `campaign_id` et `agent_id` sur un point de terminaison qui accepte l'un ou l'autre est également une `400` — passez au maximum un seul paramètre. Les points de terminaison de rapport réservés à PG (Série de métriques, Résultats de conversation, Regroupement d'agence) renvoient `503` avec `"error_code": "analytics_unavailable"` plutôt qu'un `200` rempli de zéros lorsque la base de données de rapport ne peut pas répondre pour votre compte — réessayez sous peu. Les codes partagés que chaque point de terminaison peut renvoyer — `401`, `403` (votre forfait n'inclut pas l'accès à l'API, ou, sur le regroupement d'agence, votre compte n'est pas de type Agence/Développeur), `429` (limite de débit) et `500` — sont listés avec des conseils de nouvelle tentative dans [Erreurs et pagination](errors-and-pagination.md). --- ## Étapes suivantes - [Authentification](authentication.md) — les quatre méthodes pour authentifier une requête. - [Erreurs et limites de débit](errors-and-pagination.md) — codes d'état et la limite de 300 requêtes/min. - [API Campagnes](campaigns.md) — les campagnes par lesquelles ces chiffres peuvent être filtrés.