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 — viestimäärien laskurit (lähetetyt, toimitetut, luetut, vastatut, varatut, luodut yhteystiedot, krediitit).
• Krediitit — yksityiskohtainen, sivutettu kirjanpito krediittien käytöstä summineen ja erittelyineen.
• Tekoälyn kustannukset — päiväkohtainen yhteenveto tekoälyn kuluista.
• Metriikkasarjat — kaavioita varten valmis aikasarja yhdelle tai useammalle metriikalle, ryhmiteltynä kampanjan, kanavan, tekoälyagentin tai numeron mukaan.
• Keskustelujen tulokset — miten keskustelut päättyivät tekoälyn määrittämän tulostunnisteen mukaan.
• 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 tapahtumamäärät — vanha, camelCase-muotoinen yhteenveto, 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.

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

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.

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 tiedon siitä, miten keskustelut päättyivät tietyllä aikavälillä: päiväkohtainen määrä jokaiselle tekoälyn määrittämälle tulostunnisteelle, sekä alueen kokonaissummat vastauksille, varauksille, ihmiselle siirroille ja keskusteluille, joita tekoäly ei koskaan luokitellut.

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

Kenttähuomautukset:

• by_tag[].tag — null keskusteluille, joille tekoäly ei koskaan määrittänyt tulostunnistetta.
• totals.human_alerted — ihmiselle siirretyt keskustelut; tämä kirjataan jokaisen siirron yhteydessä, eikä se aiemmin näkynyt missään päätepisteessä.
• Sama 503/analytics_unavailable-toimintatapa kuin Metric-sarjassa, kun raportointitietokanta ei pysty vastaamaan.

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öä/min -rajoitus.
• Kampanjoiden API — kampanjat, joiden mukaan nämä luvut voidaan suodattaa.