API di Analisi e Report #

Questi endpoint di sola lettura ti consentono di estrarre l’attività del tuo account nei tuoi dashboard e report: conteggi degli eventi dei messaggi, consumo di crediti, spesa AI e gli stessi grafici e approfondimenti mostrati nel dashboard in-app. Questa guida copre:

• Riepilogo — contatori del volume dei messaggi (inviati, consegnati, letti, risposti, prenotati, contatti creati, crediti).
• Crediti — un registro dettagliato e paginato dell’utilizzo dei crediti con totali e suddivisioni.
• Costo IA — un riepilogo giornaliero della spesa per l’IA.
• Serie di metriche — una serie temporale pronta per il grafico per una o più metriche, raggruppate per campagna, canale, agente IA o numero.
• Esiti delle conversazioni — conversazioni nel tempo, raggruppate in base ai tag di contatto che contengono (i tag di chiusura applicati dal tuo agente).
• Costi delle conversazioni: il costo medio in crediti di una conversazione gestita autonomamente dall’IA rispetto a una in cui è intervenuto il tuo team.
• Approfondimenti della dashboard e Approfondimenti IA della dashboard — i dati completi alla base della dashboard in-app, inclusi i riepiloghi scritti dall’IA.
• Attività dell’entità — la cronologia di un singolo contatto, trattativa o attività.
• Conteggi aggregati degli eventi — una forma legacy in camelCase del Riepilogo mantenuta per le integrazioni esistenti.

Ogni endpoint in questa pagina richiede un ambito esatto, non entrambi: passa al massimo uno tra campaign_id (legacy) o agent_id dove l’endpoint lo accetta. L’invio di entrambi restituisce 400, e un id che non è presente nel tuo account restituisce 404 anziché 403, in modo che gli id degli altri account rimangano non indovinabili.

Solo due endpoint filtrano per tag del contatto. tag_ids (con tag_match) è supportato da Dashboard insights e Aggregated event counts: questi sono i due utilizzati dal filtro Tutti i tag della dashboard in-app. Summary, Metric series e Conversation outcomes convalidano il parametro (un elenco di id non formattato correttamente restituisce comunque 400) ma non lo applicano: si ottengono numeri relativi all’intero account, senza alcun errore che lo segnali. Non interpretare un totale non filtrato come uno filtrato per tag.

Tutti i percorsi seguenti sono relativi all’URL di base dell’API:

https://api.youraiconnector.com/v1

Ogni richiesta deve essere autenticata. Consulta Autenticazione per i quattro metodi accettati. Gli esempi qui utilizzano l’intestazione X-API-Key (e una forma di parametro di query per cURL).

Intervallo di date #

Tutti e tre gli endpoint accettano gli stessi filtri di data opzionali:

Le date sono interpretate in UTC. L’intervallo è impostato per impostazione predefinita sugli ultimi 30 giorni ed è limitato a 366 giorni: un intervallo più ampio restituisce 400. from non deve essere successivo a to.

Il flag truncated #

Gli endpoint Riepilogo e Crediti limitano il numero di record che una singola richiesta può scansionare. Se il tuo intervallo è abbastanza intenso da raggiungere tale limite, la risposta include "truncated": true. Quando lo vedi, i numeri si basano su una scansione parziale: restringi l’intervallo di date (o scorri le pagine con una finestra più piccola) per ottenere cifre complete.

Riepilogo volume messaggi #

Restituisce i contatori aggregati degli eventi dei messaggi per il tuo account, sia come totali dell’intervallo che come serie giornaliera. Ogni giorno nell’intervallo appare in by_date: i giorni di inattività sono riempiti con zero. Filtra facoltativamente per una singola campagna 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()

Risposta

{
  "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
}

Ogni voce in by_date presenta gli stessi campi contatore di totals, più un date.

Se si passa un campaign_id che non appartiene al proprio account, la risposta sarà 404 con { "success": false, "error": "Campaign not found" }.

Utilizzo crediti #

Restituisce l’utilizzo dei crediti nell’intervallo specificato: un elenco paginato di record individuali, oltre ai totali dell’intervallo e alle suddivisioni per motivo e per campagna.

GET /analytics/credits

Rettifiche vs. consumo: Le variazioni di saldo come bonus, rinnovi del piano e correzioni sono escluse da totals e dalle suddivisioni: non rappresentano un consumo reale. Compaiono comunque nell’elenco records, contrassegnate con "is_adjustment": true.

I totali e le suddivisioni appaiono solo nella prima pagina (quando non viene fornito alcun cursor). Nelle pagine successive, totals, by_reason, by_reason_cost e by_campaign vengono restituiti come null: solo l’array records continua. Ciò evita di riesaminare l’intero intervallo per ogni pagina.

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.

Risposta (prima pagina)

{
  "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
}

Note sul campo:

• amount — crediti addebitati per il record. Zero per i record fatturati alla propria chiave API del provider.
• is_adjustment — true per le variazioni di saldo (escluse dai totali/suddivisioni).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — popolati solo nei record fatturati alla propria chiave API del provider; zero o null altrimenti.
• is_test — true per esecuzioni di prova/playground, che non vengono mai fatturate.
• next_cursor — il cursore per la pagina successiva, o null quando non ci sono più record.

Saldo crediti #

GET /users/me/credits — la posizione creditizia attuale del tuo account in un’unica chiamata: quanto rimane da spendere, la disponibilità mensile e le impostazioni di ricarica automatica e credito in esaurimento. L’utilizzo dei crediti sopra è una cronologia; questo è il saldo attuale. I membri del team che la richiamano necessitano dell’accesso alla fatturazione; la chiave del proprietario dell’account lo possiede sempre.

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();

Risposta (200)

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

Le agenzie possono passare sub_account_id per leggere il saldo dell’account di un cliente. All’interno di un’automazione, il passaggio Controlla crediti restituisce gli stessi campi.

Riepilogo costi IA #

Restituisce il riepilogo della spesa IA giornaliera per il proprio account. Legge i totali giornalieri pre-aggregati, quindi è veloce anche su intervalli lunghi. Ogni giorno nell’intervallo appare in days: i giorni senza attività sono riempiti con zero.

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()

Risposta

{
  "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
}

Note sul campo:

• byok_usd — spesa addebitata sulle chiavi API del tuo provider.
• platform_usd — la parte di spesa eseguita sulla piattaforma anziché tramite la tua chiave.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — le componenti di costo che costituiscono total_usd.
• by_provider — spesa in USD suddivisa per nome del provider AI.
• Le cifre in USD vengono restituite solo agli account che utilizzano la propria chiave del provider. Per gli account che pagano tramite crediti, ogni campo USD è zero e costs_redacted è true (il conteggio delle chiamate rimane visibile).

Serie di metriche #

Restituisce una o più serie temporali di metriche in un’unica chiamata, raggruppate facoltativamente fino a due dimensioni: l’endpoint a cui associare un grafico. Una singola richiesta può rispondere a “inviati e risposti al giorno, per canale, per questa campagna” senza una chiamata per campagna.

GET /analytics/series

Ogni risposta contiene un array labels (l’asse temporale, riempito con zeri sull’intero intervallo) e una voce in series per gruppo, ciascuna contenente un array per ogni metrica richiesta allineata a labels. Le serie oltre limit non vengono eliminate: si comprimono in other_bucket, calcolato come il totale dell’intervallo meno le serie restituite, in modo che un grafico renderizzato corrisponda sempre ai tuoi numeri reali; truncated è true ogni volta che ciò accade.

Da dove provengono i numeri: sent, delivered, read e replied provengono dai record dei messaggi, che contengono il canale e il numero di invio. booked, contact_created e credits_spent provengono dal flusso di eventi, che non contiene alcun numero di invio, quindi tali metriche finiscono nel bucket null-number quando raggruppi per number.

conversations conta le conversazioni (sessioni di chat) iniziate in ogni bucket e conversation_credits quanto costano tali conversazioni, calcolate esattamente come Costi delle conversazioni. Dividi l’uno per l’altro per bucket per ottenere il costo medio per conversazione nel tempo. Quando raggruppi o filtri per campagna, agente, canale o numero, una conversazione viene conteggiata in quella a cui appartiene il suo primo messaggio.

L’intervallo di date di questo endpoint è limitato a 92 giorni (più restrittivo rispetto al limite di 366 giorni utilizzato altrove in questa pagina).

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()

Risposta

{
  "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
}

Note sul campo:

• key — l’identità di una serie. Sono presenti solo le chiavi per le dimensioni group_by richieste; una dimensione il cui valore è sconosciuto per una riga (un messaggio senza campagna, un evento senza canale) viene restituita come null anziché essere eliminata, in modo che le serie si sommino comunque ai totali.
• other_bucket — null quando nulla è stato compresso.
• Questo endpoint restituisce 503 con "error_code": "analytics_unavailable" quando il database di reportistica non può rispondere per il tuo account, anziché un 200 pieno di zeri: un grafico azzerato verrebbe interpretato come un fatto.

Esiti delle conversazioni #

Restituisce gli esiti delle conversazioni in un intervallo di date: un conteggio giornaliero delle conversazioni per ogni tag di contatto, più i totali dell’intervallo per risposte, prenotazioni, passaggi a un operatore umano e conversazioni il cui contatto non ha alcun tag.

Il tag è un tag di contatto: i tag che il tuo Agente AI applica con il suo strumento di tag, le regole di auto-tag, l’API o il tuo team. Non è un’etichetta per singola conversazione. Una conversazione viene conteggiata sotto i tag che il suo contatto possiede al momento della richiesta, quindi un contatto con diversi tag viene conteggiato una volta per ciascuno, e un tag rimosso in seguito viene eliminato anche dai giorni passati. Assegna al tuo agente un tag di chiusura per esito (ad esempio resolved_ai, handoff_asked_for_human) e questo endpoint restituirà i motivi di inclusione e passaggio nel tempo.

GET /analytics/outcomes

Passa group_by=tag per comprimere l’asse temporale e ottenere solo i totali dell’intervallo per tag: in quella modalità labels è vuoto e l’array counts di ogni tag è vuoto, mentre total è ancora popolato.

L’intervallo di date di questo endpoint è limitato a 92 giorni.

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()

Risposta

{
  "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
  }
}

Note sul campo:

• by_tag[].tag / by_tag[].tag_id — il nome e l’id del tag di contatto; entrambi null nella riga delle conversazioni il cui contatto non ha alcun tag. Vengono restituiti al massimo 20 tag, ordinati per volume decrescente.
• totals.sessions — conversazioni distinte avviate nell’intervallo. Non è la somma di by_tag[].total: un contatto con tre tag contribuisce con una conversazione a tre righe.
• totals.unresolved — conversazioni il cui contatto non ha alcun tag.
• totals.human_alerted — conversazioni passate a un operatore umano; questo viene scritto su ogni passaggio e non era stato precedentemente mostrato da alcun endpoint.
• Stessa postura 503/analytics_unavailable delle Serie di metriche quando il database di reportistica non è in grado di rispondere.

Costi delle conversazioni #

Restituisce il costo medio di una conversazione in un intervallo di date, suddiviso in base al suo esito. Questo è il numero da mostrare a un cliente come ritorno sull’investimento: quanto costa una conversazione gestita autonomamente dall’IA, rispetto a una in cui il tuo team è dovuto intervenire.

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"

Risposta

{
  "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
}

Note sul campo:

• Conta le conversazioni (sessioni di chat) che sono iniziate nell’intervallo, con i crediti addebitati all’interno della finestra di ogni conversazione, rimborsi sottratti. I crediti spesi al di fuori di qualsiasi conversazione (riepiloghi giornalieri, commissioni mensili, automazioni non avviate da un contatto, come webhook o trigger RSS) non ne fanno parte. Le esecuzioni di automazione e i passaggi AI avviati da un contatto vengono conteggiati nella conversazione di quel contatto dal 26 settembre 2026.
• contained: l’AI ha risposto e nessuno del tuo team è dovuto intervenire. handed_off: qualcuno ha inviato un messaggio dopo che l’AI aveva risposto, o l’AI ha avvisato un operatore umano. no_ai: l’AI non ha mai risposto (ad esempio chat gestite dal tuo team con l’AI in pausa).
• Vengono conteggiate al massimo 20.000 conversazioni; sessions_truncated è true quando l’intervallo ne conteneva di più, quindi restringilo.
• Richiede l’autorizzazione di fatturazione per i membri del team. Stessa postura 503/analytics_unavailable della serie Metriche.
• Per contatto, la stessa suddivisione è disponibile su Ottieni costo contatto.

Approfondimenti della dashboard #

Restituisce il payload completo della dashboard per un intervallo di date in un’unica chiamata: una mappa di calore del tasso di risposta per giorno della settimana e ora, la classifica delle campagne, il volume per canale, i totali esatti per connessione, le suddivisioni delle metriche giornaliere (a livello di account, per canale e per numero), la provenienza dei contatti, il tempo di risposta della posta in arrivo e un feed delle attività recenti. Questo è il payload di reportistica più ricco dell’API: alimenta direttamente la dashboard in-app.

GET /analytics/dashboard-insights

Questo endpoint utilizza startDate/endDate (non from/to) perché condivide la sua implementazione con la dashboard in-app. L’intervallo è limitato a 92 giorni e viene troncato, non rifiutato, quando è più ampio.

Null significa non disponibile, non zero. Diversi blocchi (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) sono calcolati dal database di reportistica e restituiscono null quando non è in grado di rispondere per il tuo account. Non visualizzare un blocco null come un grafico vuoto.

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()

Risposta (abbreviata — questo payload è grande; consulta il Riferimento API per lo schema 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
  }
}

Note sul campo:

• heatmap.buckets[].weekday — 0 va da domenica a 6 che è sabato.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — ognuno è indipendentemente null quando il database di reportistica non è disponibile per il tuo account; ogni altro blocco viene comunque restituito.

Approfondimenti AI della dashboard #

Restituisce tre brevi approfondimenti scritti dall’AI sulla messaggistica dell’account in un intervallo di date: un successo, un aspetto da monitorare e un suggerimento — frasi che puoi incollare direttamente in un report invece di numeri che dovresti ancora interpretare. Generato solo dalle metriche dei messaggi dell’account.

GET /analytics/dashboard-ai-insights

Questo endpoint è valido per l’intero account: non richiede l’ambito di una campagna o di un 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()

Risposta

{
  "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." }
    ]
  }
}

Se mancano startDate o endDate, viene restituito 400.

Cronologia delle attività dell’entità #

Restituisce l’attività di un singolo contatto, trattativa o attività come un’unica cronologia, dalla più recente alla meno recente: cosa è successo e quando, tra messaggi, appuntamenti, note e cambi di stato. Usalo per rispondere alla domanda “cosa è successo con questa persona” senza dover unire diversi endpoint di elenco.

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()

Risposta

{
  "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\""
      }
    ]
  }
}

Se entityType/entityId mancano o non sono validi, viene restituito 400. Un’entità che non esiste nel tuo account restituisce 404, in modo che gli ID di altri account rimangano impossibili da indovinare.

Conteggi aggregati degli eventi (legacy) #

Restituisce gli stessi conteggi aggregati degli eventi di Riepilogo volume messaggi, ma nel formato camelCase (contactCreated invece di contact_created, byDate invece di by_date) su cui sono state costruite alcune integrazioni meno recenti. Preferisci /analytics/summary per le nuove integrazioni: questo endpoint esiste solo affinché la dashboard in-app e l’API condividano la stessa implementazione.

GET /analytics/aggregate

cURL

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

Risposta

{
  "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 } }
    ]
  }
}

Rollup dei sub-account dell’agenzia #

Errori dell’API Analytics #

Gli endpoint di Analytics restituiscono il formato di errore standard:

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

Su un endpoint di analisi, un formato data non valido o una finestra fuori intervallo restituiscono 400, mentre un campaign_id o agent_id sconosciuto restituisce 404. Inviare sia campaign_id che agent_id su un endpoint che ne accetta solo uno è anch’esso un 400: passane al massimo uno. Gli endpoint di reportistica solo PG (Serie di metriche, Esiti conversazione, Rollup agenzia) restituiscono 503 con "error_code": "analytics_unavailable" invece di un 200 pieno di zeri quando il database di reportistica non può rispondere per il tuo account: riprova a breve. I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso API o, nel rollup agenzia, il tuo account non è Agenzia/Sviluppatore), 429 (limite di frequenza) e 500 — sono elencati con indicazioni su come riprovare in Errori e Paginazione.

Passaggi successivi #

• Autenticazione — i quattro modi per autenticare una richiesta.
• Errori e limiti di frequenza — codici di stato e il limite di 300 richieste/min.
• API degli Agenti IA — gli Agenti in base ai quali queste figure possono essere filtrate.