API pentru Analize și Rapoarte #

Aceste endpoint-uri de tip read-only vă permit să extrageți activitatea contului dvs. în propriile tablouri de bord și rapoarte: numărul de evenimente de mesagerie, consumul de credite, cheltuielile AI și aceleași diagrame și perspective pe care le afișează tabloul de bord din aplicație. Acest ghid acoperă:

• Rezumat — contoare pentru volumul de mesaje (trimise, livrate, citite, răspunsuri, rezervări, contacte create, credite).
• Credite — un registru detaliat, paginat, al utilizării creditelor, cu totaluri și defalcări.
• Cost AI — o centralizare zilnică a cheltuielilor cu AI-ul.
• Serii de metrici — o serie temporală pregătită pentru grafice pentru una sau mai multe metrici, grupate pe campanie, canal, agent AI sau număr.
• Rezultatele conversațiilor — conversații în timp, grupate după etichetele de contact pe care le poartă (etichetele de închidere pe care le aplică agentul tău).
• Costurile conversațiilor: costul mediu în credite al unei conversații gestionate exclusiv de AI față de una în care a intervenit echipa ta.
• Informații din tablou de bord și Informații AI din tablou de bord — datele complete din spatele tabloului de bord din aplicație, inclusiv rezumatele scrise de AI.
• Activitatea entității — cronologia unui singur contact, a unei tranzacții sau a unei sarcini.
• Număr total de evenimente — o formă legacy, camelCase, a Rezumatului, păstrată pentru integrările existente.

Fiecare endpoint de pe această pagină necesită un domeniu exact, nu ambele: transmiteți cel mult unul dintre campaign_id (legacy) sau agent_id acolo unde endpoint-ul îl acceptă. Trimiterea ambelor returnează 400, iar un id care nu se află în contul dvs. returnează 404 în loc de 403, astfel încât id-urile altor conturi să rămână imposibil de ghicit.

Doar două endpoint-uri filtrează după eticheta de contact. tag_ids (cu tag_match) este respectat de Dashboard insights și Aggregated event counts — acestea sunt cele două pe care le folosește filtrul Toate etichetele din tabloul de bord al aplicației. Summary, Metric series și Conversation outcomes validează parametrul (o listă de id-uri malformată returnează totuși 400), dar nu îl aplică: primiți înapoi cifre la nivel de cont, fără nicio eroare care să vă avertizeze. Nu interpretați un total nefiltrat ca fiind unul filtrat după etichetă.

Toate căile de mai jos sunt relative la URL-ul de bază al API-ului:

https://api.youraiconnector.com/v1

Fiecare cerere trebuie autentificată. Consultați Autentificare pentru cele patru metode acceptate. Exemplele de aici utilizează antetul X-API-Key (și o formă de parametru de interogare pentru cURL).

Interval de date #

Toate cele trei endpoint-uri acceptă aceleași filtre opționale de dată:

Datele sunt interpretate în UTC. Intervalul implicit este de ultimele 30 de zile și este limitat la 366 de zile — un interval mai mare va returna 400. from nu trebuie să fie după to.

Indicatorul truncated #

Endpoint-urile Rezumat și Credite limitează numărul de înregistrări pe care o singură cerere le scanează. Dacă intervalul dvs. este suficient de încărcat pentru a atinge acea limită, răspunsul include "truncated": true. Când îl vedeți, cifrele se bazează pe o scanare parțială — restrângeți intervalul de date (sau navigați prin pagini cu o fereastră mai mică) pentru a obține cifre complete.

Rezumat volum mesaje #

Returnează contoare agregate pentru evenimentele de mesagerie din contul dvs., atât ca totaluri pe interval, cât și ca serie zilnică. Fiecare zi din interval apare în by_date — zilele fără activitate sunt completate cu zero. Filtrați opțional pentru o singură campanie cu 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()

Răspuns

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

Fiecare intrare din by_date are aceleași câmpuri de contorizare ca totals, plus un date.

Dacă transmiți un campaign_id care nu aparține contului tău, răspunsul va fi 404 cu { "success": false, "error": "Campaign not found" }.

Utilizarea creditelor #

Returnează utilizarea creditelor pe intervalul specificat: o listă paginată de înregistrări individuale, plus totalurile pe interval și defalcări pe motiv și pe campanie.

GET /analytics/credits

Ajustări vs. consum: Modificările de sold, cum ar fi bonusurile, reînnoirile de plan și corecțiile, sunt excluse din totals și din defalcări — acestea nu reprezintă un consum real. Ele apar în continuare în lista records, marcate cu "is_adjustment": true.

Totalurile și defalcările apar doar pe prima pagină (când nu este furnizat niciun cursor). Pe paginile ulterioare, totals, by_reason, by_reason_cost și by_campaign sunt returnate ca null — doar matricea records continuă. Acest lucru evită scanarea întregului interval pentru fiecare pagină.

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.

Răspuns (prima pagină)

{
  "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 de teren:

• amount — credite taxate pentru înregistrare. Zero pentru înregistrările facturate către propria cheie API de furnizor.
• is_adjustment — true pentru modificările de sold (excluse din totaluri/defalcări).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — completate doar pentru înregistrările facturate către propria cheie API de furnizor; zero sau null în caz contrar.
• is_test — true pentru rulările de test/playground, care nu sunt niciodată facturate.
• next_cursor — cursorul pentru pagina următoare sau null când nu mai există înregistrări.

Soldul de credite #

GET /users/me/credits — situația curentă a creditelor din contul tău dintr-un singur apel: cât a mai rămas de cheltuit, alocația lunară și setările pentru reîncărcare automată și credit scăzut. Utilizarea creditelor de mai sus reprezintă un istoric; acesta este soldul actual. Membrii echipei care apelează acest lucru au nevoie de acces la facturare; cheia proprietarului contului îl are întotdeauna.

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

Răspuns (200)

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

Agențiile pot transmite sub_account_id pentru a citi soldul unui cont de client. În cadrul unei automatizări, pasul Verificare credite returnează aceleași câmpuri.

Centralizator costuri AI #

Returnează centralizatorul cheltuielilor AI pe zi pentru contul tău. Această funcție citește totalurile zilnice pre-agregate, deci este rapidă chiar și pe intervale lungi. Fiecare zi din interval apare în days — zilele fără activitate sunt completate cu 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()

Răspuns

{
  "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 de teren:

• byok_usd — cheltuieli facturate către propriile chei API ale furnizorului tău.
• platform_usd — partea din cheltuieli care a fost rulată pe platformă în loc de propria cheie.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — componentele de cost care alcătuiesc total_usd.
• by_provider — cheltuieli în USD grupate după numele furnizorului AI.
• Cifrele în USD sunt returnate doar conturilor care își folosesc propria cheie de furnizor. Pentru conturile care plătesc prin credite, fiecare câmp USD este zero, iar costs_redacted este true (numărul de apeluri rămâne vizibil).

Serie de metrici #

Returnează una sau mai multe serii temporale de metrici într-un singur apel, grupate opțional pe până la două dimensiuni — endpoint-ul pentru a lega o diagramă. O singură cerere poate răspunde la „trimise și răspunsuri pe zi, pe canal, pentru această campanie” fără a face un apel per campanie.

GET /analytics/series

Fiecare răspuns conține o matrice labels (axa timpului, completată cu zero pe tot intervalul) și o intrare în series per grup, fiecare conținând o matrice per metrică solicitată aliniată la labels. Seriile de după limit nu sunt eliminate — ele se comprimă în other_bucket, calculat ca totalul intervalului minus seria returnată, astfel încât o diagramă redată să însumeze întotdeauna cifrele dvs. reale; truncated este true ori de câte ori se întâmplă acest lucru.

De unde provin cifrele: sent, delivered, read și replied provin din înregistrările mesajelor, care conțin canalul și numărul de trimitere. booked, contact_created și credits_spent provin din fluxul de evenimente, care nu conține niciun număr de trimitere, deci acele metrici ajung în bucket-ul null-number atunci când grupați după number.

conversations numără conversațiile (sesiunile de chat) care au început în fiecare interval, iar conversation_credits reprezintă costul acestor conversații, calculat exact ca la Costurile conversațiilor. Împarte una la cealaltă per interval pentru a obține costul mediu per conversație în timp. Atunci când grupezi sau filtrezi după campanie, agent, canal sau număr, o conversație este contorizată în funcție de primul mesaj al acesteia.

Intervalul de date al acestui endpoint este limitat la 92 de zile (mai strict decât limita de 366 de zile utilizată în altă parte pe această pagină).

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

Răspuns

{
  "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 de teren:

• key — identitatea unei serii. Sunt prezente doar cheile pentru dimensiunile group_by solicitate; o dimensiune a cărei valoare este necunoscută pentru un rând (un mesaj fără campanie, un eveniment fără canal) revine ca null în loc să fie eliminată, astfel încât seriile să însumeze în continuare totalurile.
• other_bucket — null când nimic nu a fost comprimat.
• Acest endpoint returnează 503 cu "error_code": "analytics_unavailable" atunci când baza de date de raportare nu poate oferi un răspuns pentru contul dvs., în loc de un 200 plin de zerouri — o diagramă cu zerouri ar fi interpretată ca fapt.

Rezultatele conversațiilor #

Returnează rezultatele conversațiilor pe un interval de date: un număr zilnic de conversații sub fiecare etichetă de contact, plus totalurile intervalului pentru răspunsuri, rezervări, transferuri către un operator uman și conversații al căror contact nu poartă nicio etichetă.

Eticheta este o etichetă de contact: etichetele pe care agentul tău AI le aplică cu instrumentul său de etichetare, regulile de etichetare automată, API-ul sau echipa ta. Nu este o etichetă per conversație. O conversație este numărată sub etichetele pe care le poartă contactul său în momentul solicitării, deci un contact cu mai multe etichete este numărat o dată sub fiecare, iar o etichetă eliminată ulterior dispare și din zilele trecute. Oferă agentului tău o etichetă de închidere per rezultat (de exemplu resolved_ai, handoff_asked_for_human), iar acest endpoint va returna în timp util motivele de includere și transfer.

GET /analytics/outcomes

Transmiteți group_by=tag pentru a comprima axa timpului și a obține doar totalurile pe interval per etichetă — în acel mod labels este gol și matricea counts a fiecărei etichete este goală, în timp ce total este încă populat.

Intervalul de date al acestui endpoint este limitat la 92 de zile.

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

Răspuns

{
  "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 de teren:

• by_tag[].tag / by_tag[].tag_id — numele și id-ul etichetei de contact; ambele null pe rândul conversațiilor al căror contact nu poartă nicio etichetă. Sunt returnate cel mult 20 de etichete, în ordinea descrescătoare a volumului.
• totals.sessions — conversații distincte începute în interval. Nu este suma by_tag[].total: un contact cu trei etichete contribuie cu o conversație la trei rânduri.
• totals.unresolved — conversații al căror contact nu poartă nicio etichetă.
• totals.human_alerted — conversații transferate către un operator uman; acest lucru este scris la fiecare transfer și nu a fost prezentat anterior de niciun endpoint.
• Aceeași postură 503/analytics_unavailable ca la Seriile de metrici atunci când baza de date de raportare nu poate oferi un răspuns.

Costurile conversațiilor #

Returnează costul mediu al unei conversații pe un interval de date, defalcat în funcție de modul în care a decurs. Acesta este numărul care trebuie arătat unui client ca rentabilitate a investiției: cât costă o conversație gestionată exclusiv de AI, comparativ cu una în care echipa ta a trebuit să intervină.

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"

Răspuns

{
  "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 de teren:

• Numără conversațiile (sesiunile de chat) care au început în intervalul respectiv, cu creditele taxate în fereastra fiecărei conversații, din care se scad rambursările. Creditele cheltuite în afara oricărei conversații (rezumate zilnice, taxe lunare, automatizări care nu au fost inițiate de un contact, cum ar fi declanșatoarele webhook sau RSS) nu sunt incluse. Execuțiile de automatizare și pașii AI inițiați de un contact sunt contorizați în conversația acelui contact începând cu 26 septembrie 2026.
• contained: AI-ul a răspuns și nimeni din echipa ta nu a trebuit să intervină. handed_off: cineva a trimis un mesaj după ce AI-ul a răspuns sau AI-ul a alertat un om. no_ai: AI-ul nu a răspuns niciodată (de exemplu, chat-urile pe care echipa ta le gestionează cu AI-ul întrerupt).
• Sunt contorizate cel mult 20.000 de conversații; sessions_truncated va fi true dacă intervalul a conținut mai multe, deci restrânge-l.
• Necesită permisiunea de facturare pentru membrii echipei. Aceeași postură 503/analytics_unavailable ca la seriile de metrici.
• Per contact, aceeași împărțire se regăsește la Obținere cost contact.

Informații din tablou de bord #

Returnează întregul payload al tabloului de bord pentru un interval de date într-un singur apel: o hartă termică a ratei de răspuns pe zi a săptămânii și oră, clasamentul campaniilor, volumul pe canal, totaluri exacte pe conexiune, defalcări ale metricilor pe zi (la nivel de cont, pe canal și pe număr), proveniența contactelor, timpul de răspuns în inbox și un flux de activitate recentă. Acesta este cel mai bogat payload de raportare din API — alimentează direct tabloul de bord din aplicație.

GET /analytics/dashboard-insights

Acest endpoint utilizează startDate/endDate (nu from/to) deoarece își împarte implementarea cu tabloul de bord din aplicație. Intervalul este limitat la 92 de zile și este ajustat, nu respins, atunci când este mai mare.

Null înseamnă indisponibil, nu zero. Mai multe blocuri (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) sunt calculate din baza de date de raportare și returnează null atunci când aceasta nu poate oferi un răspuns pentru contul dumneavoastră. Nu redați un bloc null ca pe un grafic gol.

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

Răspuns (prescurtat — acest payload este mare; consultați Referința API pentru schema completă)

{
  "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 de teren:

• heatmap.buckets[].weekday — 0 este duminică până la 6 care este sâmbătă.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — fiecare este în mod independent null atunci când baza de date de raportare este indisponibilă pentru contul dumneavoastră; toate celelalte blocuri returnează în continuare date.

Informații AI din tablou de bord #

Returnează trei scurte informații scrise de AI despre mesajele contului pe un interval de date: un succes, un aspect de urmărit și un sfat — propoziții pe care le puteți insera direct într-un raport, în loc de cifre pe care trebuie să le interpretați. Generate exclusiv din metricile de mesagerie ale contului.

GET /analytics/dashboard-ai-insights

Acest endpoint este la nivel de cont — nu necesită un domeniu de campanie sau agent.

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

Răspuns

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

Lipsa startDate sau endDate returnează 400.

Cronologia activității entității #

Returnează activitatea unui singur contact, unei tranzacții sau a unei sarcini sub forma unei cronologii, cu cele mai recente elemente primele: ce s-a întâmplat și când, incluzând mesaje, programări, notițe și schimbări de stare. Folosiți-l pentru a răspunde la întrebarea „ce s-a întâmplat cu această persoană” fără a combina mai multe endpoint-uri de listare.

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

Răspuns

{
  "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 lipsă sau invalid returnează 400. O entitate care nu există în contul dumneavoastră returnează 404, astfel încât ID-urile altor conturi rămân imposibil de ghicit.

Număr total de evenimente agregate (legacy) #

Returnează aceleași numărători agregate de evenimente ca Rezumatul volumului de mesaje, dar în formatul camelCase (contactCreated în loc de contact_created, byDate în loc de by_date) pe care au fost construite unele integrări mai vechi. Preferați /analytics/summary pentru integrări noi — acest endpoint există doar pentru ca tabloul de bord din aplicație și API-ul să partajeze aceeași implementare.

GET /analytics/aggregate

cURL

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

Răspuns

{
  "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 pentru sub-conturi de agenție #

Erori API Analytics #

Endpoint-urile Analytics returnează plicul de eroare standard:

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

Pe un endpoint de analiză, un format de dată invalid sau o fereastră în afara intervalului returnează 400, iar un campaign_id sau agent_id necunoscut returnează 404. Trimiterea ambelor campaign_id și agent_id pe un endpoint care acceptă oricare dintre ele este, de asemenea, o eroare 400 — transmiteți cel mult unul. Endpoint-urile de raportare doar pentru PG (Serii de metrici, Rezultate conversații, Rollup agenție) returnează 503 cu "error_code": "analytics_unavailable" în loc de un 200 plin de zerouri atunci când baza de date de raportare nu poate oferi un răspuns pentru contul dumneavoastră — reîncercați în scurt timp. Codurile partajate pe care le poate returna orice endpoint — 401, 403 (planul dumneavoastră nu include acces API sau, în cazul rollup-ului de agenție, contul dumneavoastră nu este de tip Agenție/Dev), 429 (limită de rată) și 500 — sunt listate cu instrucțiuni de reîncercare în Erori și Paginare.

Pașii următori #

• Autentificare — cele patru modalități de autentificare a unei cereri.
• Erori și limite de rată — coduri de stare și limita de 300 cereri/min.
• API Agenți AI — agenții după care pot fi filtrate aceste cifre.