Your AI Connector Docs

Analytics & Reports API

Disse skrivebeskyttede slutpunkter lader dig trække din kontos aktivitet ind i dine egne dashboards og rapporter: antal beskedhændelser, kreditforbrug, AI-forbrug og de samme grafer og indsigter, som dashboardet i appen viser. Denne guide dækker:

  • Oversigt — tællere for beskedvolumen (sendt, leveret, læst, besvaret, booket, kontakter oprettet, kreditter).
  • Kreditter — en detaljeret, pagineret hovedbog over kreditforbrug med totaler og opdelinger.
  • AI-omkostninger — en daglig oversigt over AI-forbrug.
  • Metrikserier — en grafklar tidsserie for en eller flere metrikker, grupperet efter kampagne, kanal, AI-agent eller nummer.
  • Samtaleresultater — hvordan samtaler sluttede, efter AI-tildelt resultat-tag.
  • Dashboard-indsigter og Dashboard AI-indsigter — de fulde data bag dashboardet i appen, inklusive AI-skrevne resuméer.
  • Enhedsaktivitet — tidslinjen for en enkelt kontakt, aftale eller opgave.
  • Aggregerede hændelsestællinger — en ældre, camelCase-form af Oversigt, der er bevaret til eksisterende integrationer.

Hvert slutpunkt på denne side kræver et præcist scope, ikke begge: angiv højst ét af campaign_id (ældre) eller agent_id, hvor slutpunktet accepterer det. Hvis du sender begge, returneres 400, og et id, der ikke findes på din konto, returnerer 404 i stedet for 403, så andre kontos id’er forbliver umulige at gætte.

Alle stier herunder er relative til API’ets base-URL:

https://api.youraiconnector.com/v1

Enhver anmodning skal godkendes. Se Godkendelse for de fire accepterede metoder. Eksemplerne her bruger X-API-Key-headeren (og én forespørgselsparameter-form til cURL).


Datointerval

Alle tre slutpunkter accepterer de samme valgfrie datofiltre:

Parameter Beskrivelse
from Start på intervallet, YYYY-MM-DD, inklusive. Standard er 30 dage siden.
to Slut på intervallet, YYYY-MM-DD, inklusive. Standard er i dag.

Datoer tolkes i UTC. Intervallet er som standard de sidste 30 dage og er begrænset til 366 dage — et bredere interval returnerer 400. from må ikke være efter to.

truncated-flaget

Summary- og Credits-slutpunkterne begrænser, hvor mange poster en enkelt anmodning scanner. Hvis dit interval er travlt nok til at ramme denne grænse, inkluderer svaret "truncated": true. Når du ser det, er tallene baseret på en delvis scanning — indsnæv dit datointerval (eller side igennem med et mindre vindue) for at få komplette tal.

Bemærk: Omkostnings- og tokental er kun inkluderet for AI-kald, der faktureres til dine egne udbyder-API-nøgler. Når omkostningstal er skjult for din konto, sætter svaret "costs_redacted": true, og omkostningsfelterne returneres som nul.


Oversigt over beskedvolumen

Returnerer aggregerede tællere for beskedhændelser for din konto, både som totaler for intervallet og som en daglig serie. Hver dag i intervallet vises i by_date — stille dage udfyldes med nul. Filtrer eventuelt til en enkelt kampagne med campaign_id.

GET /analytics/summary

Parameter Påkrævet Beskrivelse
from Nej Områdestart, YYYY-MM-DD.
to Nej Områdeslut, YYYY-MM-DD.
campaign_id Nej Tæl kun hændelser, der tilhører denne kampagne.

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

Svar

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

Hver post i by_date har de samme tællerfelter som totals, plus en date.

Hvis du sender en campaign_id, der ikke tilhører din konto, er svaret 404 med { "success": false, "error": "Campaign not found" }.


Kreditforbrug

Returnerer kreditforbrug over området: en pagineret liste over individuelle poster, plus områdets totaler og opdelinger efter årsag og kampagne.

GET /analytics/credits

Parameter Påkrævet Beskrivelse
from Nej Områdestart, YYYY-MM-DD.
to Nej Områdeslut, YYYY-MM-DD.
campaign_id Nej Medtag kun forbrug, der er tilskrevet denne kampagne.
limit Nej Sidestørrelse for records, 1–100. Standard er 50.
cursor Nej Send den forrige sides next_cursor for at hente den næste side.

Justeringer vs. forbrug: Saldoforandringer såsom bonusser, abonnementsfornyelser og rettelser er ekskluderet fra totals og opdelingerne – de er ikke reelt forbrug. De vises stadig i records-listen, markeret med "is_adjustment": true.

Totaler og opdelinger vises kun på den første side (når ingen cursor er angivet). På efterfølgende sider returneres totals, by_reason, by_reason_cost og by_campaign som null – kun records-arrayet fortsætter. Dette undgår at gen-scanne hele området for hver side.

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.

Svar (første side)

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

Feltnoter:

  • amount — kreditter debiteret for posten. Nul for poster faktureret til din egen udbyder-API-nøgle.
  • is_adjustmenttrue for saldoforandringer (ekskluderet fra totaler/opdelinger).
  • cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — udfyldes kun på poster faktureret til din egen udbyder-API-nøgle; ellers nul eller null.
  • is_testtrue for legeplads-/testkørsler, som aldrig faktureres.
  • next_cursor — markøren for den næste side, eller null når der ikke er flere poster.

AI-omkostningsopgørelse

Returnerer den daglige AI-omkostningsopgørelse for din konto. Dette læser præ-aggregerede daglige totaler, så det er hurtigt selv over lange områder. Hver dag i området vises i days – stille dage er udfyldt med nul.

GET /analytics/ai-cost

Parameter Påkrævet Beskrivelse
from Nej Områdestart, YYYY-MM-DD.
to Nej Områdeslut, YYYY-MM-DD.

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

Svar

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

Feltnoter:

  • byok_usd — forbrug faktureret til dine egne udbyder-API-nøgler.
  • platform_usd — den del af forbruget, der kørte på platformen i stedet for din egen nøgle.
  • input_usd, output_usd, cache_creation_usd, cache_read_usd — de omkostningskomponenter, der udgør total_usd.
  • by_provider — USD-forbrug grupperet efter AI-udbydernavn.
  • USD-tal returneres kun til konti, der bruger deres egen udbydernøgle. For konti, der betaler med kredit, er hvert USD-felt nul, og costs_redacted er true (opkaldstællinger forbliver synlige).

Metrikserier

Returnerer en eller flere metrik-tidsserier i ét kald, eventuelt grupperet efter op til to dimensioner — slutpunktet til at binde en graf til. En enkelt forespørgsel kan besvare “sendt og besvaret pr. dag, pr. kanal, for denne kampagne” uden at skulle foretage ét kald pr. kampagne.

GET /analytics/series

Hvert svar indeholder et labels-array (tidsaksen, nul-udfyldt over hele intervallet) og én post i series pr. gruppe, hvor hver indeholder ét array pr. anmodet metrik, der er justeret til labels. Serier efter limit bliver ikke droppet — de kollapser til other_bucket, beregnet som intervallets total minus den returnerede serie, så en gengivet graf altid summerer op til dine reelle tal; truncated er true, når det sker.

Hvor tallene kommer fra: sent, delivered, read og replied kommer fra beskedposter, som indeholder kanal og afsendernummer. booked, contact_created og credits_spent kommer fra hændelsesstrømmen, som ikke indeholder noget afsendernummer, så disse metrikker lander i null-nummer-bucket, når du grupperer efter number.

Parameter Påkrævet Beskrivelse
from Nej Intervalstart, YYYY-MM-DD. Standard er 30 dage siden.
to Nej Intervalslut, YYYY-MM-DD. Standard er i dag.
metrics Nej Komma-separeret liste fra sent, ai_sent, human_sent, delivered, read, replied, booked, contact_created, credits_spent. Standard er sent,replied. En ukendt metrik returnerer 400.
group_by Nej Komma-separeret liste af op til to dimensioner fra date, campaign, channel, agent, number. date accepteres, men har ingen effekt — hvert svar indeholder allerede tidsaksen. Udelad for en enkelt kontodækkende serie.
granularity Nej day (standard), week eller month. Uge-buckets starter mandag, måneds-buckets den 1.
limit Nej Hvor mange serier der skal returneres, før resten kollapser til other_bucket, 1–50. Standard er 12.
campaign_id Nej Tæl kun aktivitet, der tilhører denne kampagne. Ældre; foretræk agent_id.
agent_id Nej Tæl kun aktivitet, der tilhører denne AI-agent.
channel Nej Tæl kun aktivitet på denne kanal, for eksempel whatsapp.

Dette slutpunkts datointerval er begrænset til 92 dage (strammere end 366-dages grænsen, der bruges andre steder på denne side).

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

Svar

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

Feltnoter:

  • key — identiteten på én serie. Kun nøglerne for de anmodede group_by-dimensioner er til stede; en dimension, hvis værdi er ukendt for en række (en besked uden kampagne, en hændelse uden kanal), kommer tilbage som null i stedet for at blive droppet, så serier stadig summerer op til totalerne.
  • other_bucketnull når intet blev kollapset.
  • Dette slutpunkt returnerer 503 med "error_code": "analytics_unavailable", når rapporteringsdatabasen ikke kan svare for din konto, i stedet for en 200 fuld af nuller — en nulstillet graf ville blive læst som fakta.

Samtaleresultater

Returnerer hvordan samtaler sluttede over et datointerval: en daglig tælling for hvert resultat-tag, som AI’en tildelte, plus intervaltotaler for svar, bookinger, overdragelser til et menneske og samtaler, som AI’en aldrig klassificerede.

GET /analytics/outcomes

Angiv group_by=tag for at kollapse tidsaksen og kun få intervaltotaler pr. tag — i den tilstand er labels tom, og hvert tags counts-array er tomt, mens total stadig er udfyldt.

Parameter Påkrævet Beskrivelse
from Nej Områdestart, YYYY-MM-DD. Standard er for 30 dage siden.
to Nej Områdeslut, YYYY-MM-DD. Standard er i dag.
campaign_id Nej Tæl kun samtaler med kontakter, der i øjeblikket er i denne kampagne. Legacy; foretræk agent_id.
agent_id Nej Tæl kun resultater, der tilhører denne AI-agent.
group_by Nej date (standard) beholder optællinger pr. dag; tag samler til områdets totaler.

Dette endpunkts datointerval er begrænset til 92 dage.

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

Svar

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

Feltnoter:

  • by_tag[].tagnull for samtaler, som AI’en aldrig tildelte et resultat-tag.
  • totals.human_alerted — samtaler overdraget til et menneske; dette skrives ved hver overdragelse og blev tidligere ikke vist af noget endpunkt.
  • Samme 503/analytics_unavailable-holdning som Metric-serien, når rapporteringsdatabasen ikke kan svare.

Dashboard-indsigt

Returnerer den fulde dashboard-nyttelast for et datointerval i ét kald: et heatmap for svarprocent pr. ugedag og time, kampagne-ranglisten, volumen pr. kanal, nøjagtige totaler pr. forbindelse, opdeling af metrikker pr. dag (konto-dækkende, pr. kanal og pr. nummer), hvor kontakter kommer fra, svartid i indbakken og et feed med nylig aktivitet. Dette er den mest omfattende rapporteringsnyttelast på API’et — den driver dashboardet direkte i appen.

GET /analytics/dashboard-insights

Parameter Påkrævet Beskrivelse
startDate Ja Områdestart, YYYY-MM-DD.
endDate Ja Områdeslut, YYYY-MM-DD.
campaignId Nej Inkluder kun aktivitet, der tilhører denne kampagne (campaign_id accepteres også). Legacy; foretræk agent_id.
agent_id Nej Inkluder kun aktivitet, der tilhører denne AI-agent (agentId accepteres også). Under et agent-scope bygges kampagne-ranglisten kun ud fra denne agents aktivitet.

Dette endpunkt bruger startDate/endDate (ikke from/to), fordi det deler implementering med dashboardet i appen. Intervallet er begrænset til 92 dage og bliver beskåret, ikke afvist, hvis det er bredere.

Null betyder utilgængelig, ikke nul. Flere blokke (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) beregnes ud fra rapporteringsdatabasen og returneres som null, når den ikke kan svare for din konto. Gengiv ikke en null-blok som et tomt diagram.

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

Svar (forkortet — denne nyttelast er stor; se API-reference for det fulde skema)

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

Feltnoter:

  • heatmap.buckets[].weekday0 er søndag til 6 er lørdag.
  • numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — hver især uafhængigt null, når rapporteringsdatabasen er utilgængelig for din konto; alle andre blokke returneres stadig.

AI-indsigt for dashboard

Returnerer tre korte, AI-skrevne indsigter om kontoens beskeder over et datointerval: én sejr, én ting at holde øje med og ét tip — sætninger, du kan indsætte direkte i en rapport i stedet for tal, som du stadig selv skal fortolke. Genereret udelukkende ud fra kontoens egne beskedmetrikker.

GET /analytics/dashboard-ai-insights

Parameter Påkrævet Beskrivelse
startDate Ja Områdestart, YYYY-MM-DD.
endDate Ja Områdeslut, YYYY-MM-DD.

Dette slutpunkt er konto-dækkende — det kræver ikke kampagne- eller agent-omfang.

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

Svar

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

Manglende startDate eller endDate returnerer 400.


Tidslinje for enhedsaktivitet

Returnerer en enkelt kontakts, aftales eller opgaves aktivitet som én tidslinje, nyeste først: hvad skete der og hvornår, på tværs af beskeder, aftaler, noter og statusændringer. Brug det til at besvare “hvad er der sket med denne person” uden at skulle sammensætte flere listeslutpunkter.

GET /analytics/entity-activity

Parameter Påkrævet Beskrivelse
entityType Ja contact, deal eller task.
entityId Ja ID på den post, hvis tidslinje der skal returneres.

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

Svar

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

Et manglende eller ugyldigt entityType/entityId returnerer 400. En enhed, der ikke findes på din konto, returnerer 404, så andre kontos id’er forbliver umulige at gætte.


Aggregerede begivenhedstællinger (legacy)

Returnerer de samme aggregerede begivenhedstællinger som Beskedvolumen-oversigt, men i camelCase-format (contactCreated i stedet for contact_created, byDate i stedet for by_date), som nogle ældre integrationer er bygget op omkring. Foretræk /analytics/summary til nye integrationer — dette slutpunkt findes kun, så dashboardet i appen og API’et deler én implementering.

GET /analytics/aggregate

Parameter Påkrævet Beskrivelse
startDate Nej Områdestart, ISO-dato eller dato-tid. Standard er det samme vindue, som /analytics/summary bruger.
endDate Nej Områdeslut, ISO-dato eller dato-tid.
campaignId Nej Tæl kun begivenheder, der tilhører denne kampagne (campaign_id accepteres også). Legacy; foretræk agent_id.
agent_id Nej Tæl kun begivenheder, der tilhører denne AI-agent (agentId accepteres også).

cURL

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

Svar

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

Agency-underkonto-rollup


Analytics API-fejl

Analytics-slutpunkter returnerer standardfejl-konvolutten:

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

På et analyseslutpunkt returnerer et ugyldigt datoformat eller et vindue uden for rækkevidde 400, og et ukendt campaign_id eller agent_id returnerer 404. At sende både campaign_id og agent_id på et slutpunkt, der accepterer begge, er også en 400 — send højst én. De PG-specifikke rapporteringsslutpunkter (Metrik-serier, Samtaleudfald, Agency-rollup) returnerer 503 med "error_code": "analytics_unavailable" i stedet for en 200 fuld af nuller, når rapporteringsdatabasen ikke kan svare for din konto — prøv igen kort efter. De delte koder, som ethvert slutpunkt kan returnere — 401, 403 (din plan inkluderer ikke API-adgang, eller på bureau-rollup, din konto er ikke Agency/Dev), 429 (rate limit) og 500 — er angivet med vejledning til genforsøg i Fejl & Sidetal.


Næste skridt