Analytics & Reports API #

Näiden vain luku -päätepisteiden avulla voit tuoda tilisi toiminnan omiin koontinäyttöihisi ja raportteihisi: viestitapahtumien määrät, krediittien kulutuksen, tekoälyn kustannukset sekä samat kaaviot ja oivallukset, jotka näkyvät sovelluksen sisäisessä koontinäytössä. Tämä opas kattaa:

• Yhteenveto — viestien määrän laskurit (lähetetyt, toimitetut, luetut, vastatut, varatut, luodut yhteystiedot, krediitit).
• Krediitit — yksityiskohtainen, sivutettu loki krediittien käytöstä summineen ja erittelyineen.
• AI-kustannukset — päiväkohtainen kooste tekoälyn käytön kustannuksista.
• Metriikkasarjat — kaavioita varten valmis aikasarja yhdelle tai useammalle metriikalle, ryhmiteltynä kampanjan, kanavan, tekoälyagentin tai numeron mukaan.
• Keskustelujen tulokset — keskustelut ajan mittaan, ryhmiteltynä niihin liitettyjen yhteystietotunnisteiden mukaan (päättävät tunnisteet, jotka agenttisi lisää).
• Keskustelukustannukset: keskimääräiset krediittikustannukset keskustelulle, jonka tekoäly hoiti yksin, verrattuna keskusteluun, johon tiimisi osallistui.
• Koontinäytön oivallukset ja Koontinäytön tekoälyoivallukset — sovelluksen sisäisen koontinäytön taustalla oleva täydellinen data, mukaan lukien tekoälyn kirjoittamat yhteenvedot.
• Entiteetin toiminta — yksittäisen yhteystiedon, sopimuksen tai tehtävän aikajana.
• Aggregoidut tapahtumalaskurit — vanha, camelCase-muotoinen Yhteenveto-versio, joka on säilytetty olemassa olevia integraatioita varten.

Jokainen tämän sivun päätepiste vaatii tarkan laajuuden (scope), ei molempia: välitä enintään yksi campaign_id (vanha) tai agent_id, jos päätepiste hyväksyy sen. Molempien lähettäminen palauttaa 400, ja tunnus, jota ei ole tililläsi, palauttaa 404 eikä 403, jotta muiden tilien tunnukset pysyvät arvaamattomina.

Vain kaksi päätepistettä suodattaa yhteystunnisteen mukaan. tag_ids (yhdessä tag_match kanssa) huomioidaan Dashboard insights ja Aggregated event counts -kohdissa – nämä ovat ne kaksi, joita sovelluksen sisäisen hallintapaneelin Kaikki tunnisteet -suodatin käyttää. Yhteenveto, Metriikkasarjat ja Keskustelujen tulokset validoivat parametrin (virheellinen tunnusluettelo palauttaa silti 400), mutta ne eivät sovella** sitä: saat takaisin koko tilin kattavat luvut ilman virheilmoitusta. Älä tulkitse suodattamatonta kokonaissummaa tunnisteella suodatetuksi.

Kaikki alla olevat polut ovat suhteessa rajapinnan perus-URL-osoitteeseen:

https://api.youraiconnector.com/v1

Jokainen pyyntö on todennettava. Katso kohdasta Todennus neljä hyväksyttyä menetelmää. Tässä olevissa esimerkeissä käytetään X-API-Key-otsikkoa (ja yhtä kyselyparametrimuotoa cURL-kutsulle).

Päivämääräväli #

Kaikki kolme päätepistettä hyväksyvät samat valinnaiset päivämääräsuodattimet:

Päivämäärät tulkitaan UTC-ajassa. Välin oletusarvo on viimeiset 30 päivää, ja se on rajoitettu 366 päivään — tätä laajempi väli palauttaa 400-virheen. from ei saa olla päivämäärä, joka on to-päivämäärän jälkeen.

truncated-lippu #

Yhteenveto- ja Krediitit-päätepisteet rajoittavat sitä, kuinka monta tietuetta yksi pyyntö voi skannata. Jos valitsemasi väli on niin vilkas, että se saavuttaa tämän rajan, vastaus sisältää "truncated": true-arvon. Kun näet sen, luvut perustuvat osittaiseen skannaukseen — rajaa päivämääräväliäsi (tai selaa sivuja pienemmillä ikkunoilla) saadaksesi täydelliset luvut.

Viestimäärien yhteenveto #

Palauttaa tilisi aggregoidut viestitapahtumien laskurit sekä välin kokonaissummina että päiväkohtaisena sarjana. Jokainen päivä välillä näkyy by_date-kohdassa — hiljaiset päivät täytetään nollilla. Voit halutessasi suodattaa tulokset yhteen kampanjaan käyttämällä campaign_id-parametria.

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

Vastaus

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

Jokaisella by_date-kohdan merkinnällä on samat laskurikentät kuin totals-kohdassa, sekä lisäksi date.

Jos annat campaign_id-arvon, joka ei kuulu tilillesi, vastauksena on 404 ja { "success": false, "error": "Campaign not found" }.

Krediittien käyttö #

Palauttaa krediittien käytön määritetyllä välillä: sivutettu luettelo yksittäisistä tietueista sekä alueen kokonaissummat ja erittelyt syyn ja kampanjan mukaan.

GET /analytics/credits

Oikaisut vs. kulutus: Saldon muutokset, kuten bonukset, tilauksen uusimiset ja korjaukset, on jätetty pois totals-kohdasta ja erittelyistä – ne eivät ole varsinaista kulutusta. Ne näkyvät edelleen records-luettelossa, merkittynä "is_adjustment": true-tunnisteella.

Kokonaissummat ja erittelyt näkyvät vain ensimmäisellä sivulla (kun cursor-arvoa ei ole annettu). Seuraavilla sivuilla totals, by_reason, by_reason_cost ja by_campaign palautetaan muodossa null – vain records-taulukko jatkuu. Tämä estää koko alueen uudelleenskannauksen jokaisen sivun kohdalla.

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.

Vastaus (ensimmäinen sivu)

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

Kenttähuomautukset:

• amount — tietueesta veloitetut krediitit. Nolla, jos tietueet laskutetaan oman palveluntarjoajan API-avaimesi kautta.
• is_adjustment — true saldomuutoksille (jätetty pois kokonaissummista/erittelyistä).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — täytetään vain tietueissa, jotka laskutetaan oman palveluntarjoajan API-avaimesi kautta; muussa tapauksessa nolla tai null.
• is_test — true leikkikenttä-/testiajoille, joita ei koskaan laskuteta.
• next_cursor — seuraavan sivun kohdistin tai null, kun tietueita ei ole enää jäljellä.

Käyttösaldo #

GET /users/me/credits — tilisi nykyinen saldo yhdellä kutsulla: paljonko on käytettävissä, kuukausittainen kiintiö sekä automaattisen latauksen ja alhaisen saldon asetukset. Yllä oleva luottojen käyttö on historiatietoa; tämä on nykyinen saldo. Tiimin jäsenet, jotka kutsuvat tätä, tarvitsevat laskutusoikeudet; tilin omistajan avaimella on ne aina.

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

Vastaus (200)

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

Toimistot voivat välittää sub_account_id-parametrin lukeakseen asiakastilin saldon. Automaation sisällä Tarkista krediitit -vaihe palauttaa samat kentät.

AI-kustannusten yhteenveto #

Palauttaa tilisi päivittäisen AI-kulujen yhteenvedon. Tämä lukee valmiiksi koostetut päivittäiset summat, joten se on nopea myös pitkillä aikaväleillä. Jokainen alueen päivä näkyy days-kohdassa – hiljaiset päivät täytetään nollilla.

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

Vastaus

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

Kenttähuomautukset:

• byok_usd — laskutettu käyttö omilla palveluntarjoajan API-avaimillasi.
• platform_usd — se osa käytöstä, joka suoritettiin alustalla oman avaimesi sijaan.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — kustannuskomponentit, jotka muodostavat kohdan total_usd.
• by_provider — USD-määräinen käyttö AI-palveluntarjoajan nimen mukaan jaoteltuna.
• USD-summat palautetaan vain tileille, jotka käyttävät omaa palveluntarjoajan avaintaan. Luottoa käyttäville tileille jokainen USD-kenttä on nolla ja costs_redacted on true (kutsulaskurit pysyvät näkyvissä).

Metriikkasarjat #

Palauttaa yhden tai useamman metriikan aikasarjan yhdellä kutsulla, valinnaisesti ryhmiteltynä enintään kahden ulottuvuuden mukaan – päätepiste kaavion sitomiseen. Yksi pyyntö voi vastata kysymykseen “lähetetyt ja vastatut per päivä, per kanava, tälle kampanjalle” ilman kutsua per kampanja.

GET /analytics/series

Jokainen vastaus sisältää labels-taulukon (aikakseli, nollatäytetty koko alueella) ja yhden merkinnän series-kohdassa per ryhmä, joista jokainen sisältää yhden taulukon per pyydetty metriikka kohdistettuna labels-kohtaan. limit-kohdan jälkeisiä sarjoja ei hylätä – ne tiivistyvät other_bucket-kohtaan, joka lasketaan alueen kokonaissummana miinus palautetut sarjat, joten renderöity kaavio vastaa aina todellisia lukuja; truncated on true aina kun näin tapahtuu.

Mistä luvut tulevat: sent, delivered, read ja replied tulevat viestitietueista, jotka sisältävät kanavan ja lähettävän numeron. booked, contact_created ja credits_spent tulevat tapahtumavirrasta, joka ei sisällä lähettävää numeroa, joten nämä metriikat päätyvät null-numeroiseen säiliöön, kun ryhmittelet number-kohdan mukaan.

conversations laskee kussakin ryhmässä alkaneet keskustelut (chat-istunnot) ja conversation_credits sen, mitä nämä keskustelut maksoivat, laskettuna täsmälleen kuten Keskustelukustannukset. Jaa toinen toisella ryhmittäin saadaksesi keskimääräiset kustannukset per keskustelu ajan mittaan. Kun ryhmittelet tai suodatat kampanjan, agentin, kanavan tai numeron mukaan, keskustelu lasketaan kuuluvaksi siihen, johon sen ensimmäinen viesti kuuluu.

Tämän päätepisteen päivämääräväli on rajoitettu 92 päivään (tiukempi kuin muualla tällä sivulla käytetty 366 päivän rajoitus).

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

Vastaus

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

Kenttähuomautukset:

• key — yhden sarjan identiteetti. Vain pyydettyjen group_by-ulottuvuuksien avaimet ovat läsnä; ulottuvuus, jonka arvo on tuntematon riville (viesti ilman kampanjaa, tapahtuma ilman kanavaa), palautuu muodossa null sen sijaan, että se hylättäisiin, joten sarjat summautuvat edelleen kokonaissummiin.
• other_bucket — null, kun mitään ei tiivistetty.
• Tämä päätepiste palauttaa 503 ja "error_code": "analytics_unavailable", kun raportointitietokanta ei pysty vastaamaan tilisi osalta, sen sijaan että palauttaisi 200 täynnä nollia – nollattu kaavio tulkittaisiin faktaksi.

Keskustelujen tulokset #

Palauttaa keskustelujen tulokset tietyllä aikavälillä: päiväkohtainen määrä keskusteluja kunkin yhteystietotunnisteen alla, sekä aikavälin kokonaismäärät vastauksille, varauksille, ihmiselle siirroille ja keskusteluille, joiden yhteystiedolla ei ole tunnisteita.

Tunniste on yhteystietotunniste: tunnisteet, joita AI-agenttisi käyttää tunnisteryökalullaan, automaattisilla tunnistesäännöillä, API:n kautta tai tiimisi toimesta. Se ei ole keskustelukohtainen merkintä. Keskustelu lasketaan niiden tunnisteiden alle, jotka yhteystiedolla on pyyntöhetkellä, joten useita tunnisteita sisältävä yhteystieto lasketaan kerran jokaisen tunnisteen kohdalla, ja myöhemmin poistettu tunniste poistuu myös menneiltä päiviltä. Anna agentillesi yksi päättävä tunniste per tulos (esimerkiksi resolved_ai, handoff_asked_for_human), niin tämä päätepiste palauttaa keskustelujen sisällön ja siirtosyyt ajan kuluessa.

GET /analytics/outcomes

Välitä group_by=tag tiivistääksesi aikakselin ja saadaksesi vain alueen kokonaissummat per tunniste – tässä tilassa labels on tyhjä ja jokaisen tunnisteen counts-taulukko on tyhjä, kun taas total on edelleen täytetty.

Tämän päätepisteen aikaväli on rajoitettu 92 päivään.

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

Vastaus

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

Kenttähuomautukset:

• by_tag[].tag / by_tag[].tag_id — yhteystietotunnisteen nimi ja id; molemmat ovat null sillä rivillä, joka sisältää keskustelut, joiden yhteystiedolla ei ole tunnisteita. Enintään 20 tunnistetta palautetaan, suurimman volyymin mukaan järjestettynä.
• totals.sessions — kyseisellä aikavälillä aloitetut erilliset keskustelut. Tämä ei ole by_tag[].total-arvojen summa: yhteystieto, jolla on kolme tunnistetta, lisää yhden keskustelun kolmelle eri riville.
• totals.unresolved — keskustelut, joiden yhteystiedolla ei ole tunnisteita.
• totals.human_alerted — ihmiselle siirretyt keskustelut; tämä kirjataan jokaisen siirron yhteydessä, eikä se ollut aiemmin saatavilla minkään päätepisteen kautta.
• Sama 503/analytics_unavailable-toimintatapa kuin Metriikkasarjoissa, kun raportointitietokanta ei pysty vastaamaan.

Keskustelukustannukset #

Palauttaa keskustelun keskimääräiset kustannukset tietyllä aikavälillä jaoteltuna sen mukaan, miten keskustelu eteni. Tämä on luku, joka kannattaa näyttää asiakkaalle sijoitetun pääoman tuottona: mitä tekoälyn yksin hoitama keskustelu maksaa verrattuna siihen, johon tiimisi joutui puuttumaan.

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"

Vastaus

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

Kenttähuomautukset:

• Laskee keskustelut (chat-istunnot), jotka alkoivat kyseisellä aikavälillä, mukaan lukien kunkin keskustelun aikana veloitetut krediitit, hyvitykset vähennettynä. Keskustelujen ulkopuolella käytetyt krediitit (päivittäiset yhteenvedot, kuukausimaksut, automaatiot, joita yhteyshenkilö ei käynnistänyt, kuten webhook- tai RSS-laukaisimet) eivät sisälly tähän. Yhteyshenkilön käynnistämät automaatioajot ja tekoälyvaiheet lasketaan kyseisen yhteyshenkilön keskusteluun 26. syyskuuta 2026 alkaen.
• contained: tekoäly vastasi eikä kenenkään tiimistä tarvinnut puuttua asiaan. handed_off: joku lähetti viestin tekoälyn vastattua tai tekoäly hälytti ihmisen. no_ai: tekoäly ei koskaan vastannut (esimerkiksi keskustelut, joita tiimisi hoitaa tekoälyn ollessa tauolla).
• Enintään 20 000 keskustelua lasketaan; sessions_truncated on true, kun aikavälillä oli enemmän keskusteluja, joten rajaa aikaväliä.
• Vaatii tiimin jäseniltä laskutusoikeudet. Sama 503/analytics_unavailable-asettelu kuin mittarisarjoissa.
• Yhteyshenkilökohtainen erittely löytyy kohdasta Hae yhteyshenkilön kustannukset.

Koontinäytön oivallukset #

Palauttaa koko koontinäytön hyötykuorman yhdellä kutsulla: vastausprosentin lämpökartta viikonpäivän ja tunnin mukaan, kampanjoiden tulostaulu, kanavakohtainen volyymi, tarkat yhteyskohtaiset summat, päiväkohtaiset mittarikoosteet (tili-, kanava- ja numerokohtaisesti), yhteyshenkilöiden alkuperä, saapuneiden viestien vastausaika ja viimeisimpien toimintojen syöte. Tämä on API:n kattavin raportointihyötykuorma — se ohjaa suoraan sovelluksen sisäistä koontinäyttöä.

GET /analytics/dashboard-insights

Tämä päätepiste käyttää startDate/endDate-muotoa (ei from/to), koska se jakaa toteutuksensa sovelluksen sisäisen koontinäytön kanssa. Aikaväli on rajoitettu 92 päivään, ja jos se on tätä laajempi, se rajataan, ei hylätä.

Null tarkoittaa ei saatavilla, ei nollaa. Useat lohkot (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) lasketaan raportointitietokannasta ja ne palauttavat null, kun tietokanta ei pysty vastaamaan tilisi osalta. Älä renderöi null-lohkoa tyhjänä kaaviona.

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

Vastaus (lyhennetty — tämä hyötykuorma on suuri; katso täydellinen skeema API-viitteestä)

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

Kenttähuomautukset:

• heatmap.buckets[].weekday — 0 on sunnuntai ja 6 on lauantai.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — jokainen palauttaa itsenäisesti null, kun raportointitietokanta ei ole käytettävissä tilillesi; kaikki muut lohkot palautuvat normaalisti.

Tekoälyn koontinäytön oivallukset #

Palauttaa kolme lyhyttä, tekoälyn kirjoittamaa oivallusta tilin viestinnästä tietyllä aikavälillä: yksi onnistuminen, yksi seurattava asia ja yksi vinkki — lauseita, jotka voit kopioida suoraan raporttiin sen sijaan, että joutuisit tulkitsemaan lukuja itse. Luotu vain tilin omien viestimittareiden perusteella.

GET /analytics/dashboard-ai-insights

Tämä päätepiste koskee koko tiliä — se ei vaadi kampanja- tai agenttilaajuutta.

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

Vastaus

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

Puuttuva startDate tai endDate palauttaa 400.

Entiteetin toiminnan aikajana #

Palauttaa yksittäisen yhteystiedon, kaupan tai tehtävän toiminnan yhtenä aikajanana, uusimmasta alkaen: mitä tapahtui ja milloin, sisältäen viestit, tapaamiset, muistiinpanot ja tilamuutokset. Käytä tätä vastataksesi kysymykseen “mitä tälle henkilölle on tapahtunut” ilman, että joudut yhdistelemään useita listauspäätepisteitä.

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

Vastaus

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

Puuttuva tai virheellinen entityType/entityId palauttaa 400. Entiteetti, jota ei ole tililläsi, palauttaa 404, joten muiden tilien tunnukset pysyvät arvaamattomina.

Aggregoidut tapahtumien määrät (vanhentunut) #

Palauttaa samat aggregoidut tapahtumien määrät kuin Viestien määrän yhteenveto, mutta camelCase-muodossa (contactCreated eikä contact_created, byDate eikä by_date), jota jotkin vanhemmat integraatiot käyttävät. Suosi /analytics/summary-päätepistettä uusissa integraatioissa — tämä päätepiste on olemassa vain siksi, että sovelluksen sisäinen hallintapaneeli ja API jakavat saman toteutuksen.

GET /analytics/aggregate

cURL

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

Vastaus

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

Toimiston alitilien yhteenveto #

Analytics API -virheet #

Analytics-päätepisteet palauttavat vakioituneen virhemuodon:

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

Analytiikkapäätepisteessä virheellinen päivämäärämuoto tai sallitun ikkunan ulkopuolinen aikaväli palauttaa 400, ja tuntematon campaign_id tai agent_id palauttaa 404. Sekä campaign_id- että agent_id-parametrien lähettäminen päätepisteeseen, joka hyväksyy vain toisen, on myös 400 — lähetä enintään yksi. Vain PG-raportointipäätepisteet (metrisarjat, keskustelujen tulokset, toimiston yhteenveto) palauttavat 503 ja "error_code": "analytics_unavailable" sen sijaan, että palauttaisivat 200 täynnä nollia, kun raportointitietokanta ei pysty vastaamaan tilisi osalta — yritä pian uudelleen. Jaetut koodit, jotka jokainen päätepiste voi palauttaa — 401, 403 (tilauksesi ei sisällä API-pääsyä tai toimiston yhteenvedossa tilisi ei ole Agency/Dev), 429 (nopeusrajoitus) ja 500 — on lueteltu uudelleenkokeiluohjeiden kanssa kohdassa Virheet ja sivutus.

Seuraavat vaiheet #

• Todennus — neljä tapaa todentaa pyyntö.
• Virheet ja nopeusrajoitukset — tilakoodit ja 300 pyyntöä minuutissa -rajoitus.
• AI Agents API — agentit, joiden mukaan nämä luvut voidaan suodattaa.