API Analitik & Laporan

Endpoint read-only ini memungkinkan Anda menarik aktivitas akun ke dasbor dan laporan Anda sendiri: jumlah peristiwa pesan, konsumsi kredit, pengeluaran AI, serta grafik dan wawasan yang sama seperti yang ditampilkan di dasbor dalam aplikasi. Panduan ini mencakup:

Ringkasan — penghitung volume pesan (terkirim, terkirim ke tujuan, dibaca, dibalas, dipesan, kontak dibuat, kredit).
Kredit — buku besar penggunaan kredit yang terperinci dan berhalaman dengan total dan perincian.
Biaya AI — akumulasi pengeluaran AI per hari.
Seri metrik — deret waktu siap-grafik untuk satu atau beberapa metrik, dikelompokkan berdasarkan kampanye, saluran, Agen AI, atau nomor.
Hasil percakapan — bagaimana percakapan berakhir, berdasarkan tag hasil yang ditetapkan AI.
Wawasan dasbor dan Wawasan AI dasbor — data lengkap di balik dasbor dalam aplikasi, termasuk ringkasan yang ditulis AI.
Aktivitas entitas — linimasa satu kontak, kesepakatan, atau tugas.
Jumlah peristiwa gabungan — bentuk camelCase lama dari Ringkasan yang dipertahankan untuk integrasi yang sudah ada.

Setiap endpoint di halaman ini memerlukan cakupan yang tepat, bukan keduanya: berikan paling banyak satu dari campaign_id (lama) atau agent_id di mana endpoint menerimanya. Mengirim keduanya akan mengembalikan 400, dan id yang tidak ada di akun Anda akan mengembalikan 404 alih-alih 403, sehingga id akun lain tetap tidak dapat ditebak.

Semua jalur di bawah ini bersifat relatif terhadap URL dasar API:

https://api.youraiconnector.com/v1

Setiap permintaan harus diautentikasi. Lihat Autentikasi untuk empat metode yang diterima. Contoh di sini menggunakan header X-API-Key (dan satu bentuk parameter kueri untuk cURL).

Rentang tanggal

Ketiga endpoint menerima filter tanggal opsional yang sama:

Parameter	Deskripsi
`from`	Awal rentang, `YYYY-MM-DD`, inklusif. Default-nya adalah 30 hari yang lalu.
`to`	Akhir rentang, `YYYY-MM-DD`, inklusif. Default-nya adalah hari ini.

Tanggal diinterpretasikan dalam UTC. Rentang default adalah 30 hari terakhir dan dibatasi hingga 366 hari — rentang yang lebih luas akan mengembalikan 400. from tidak boleh setelah to.

Flag `truncated`

Endpoint Ringkasan dan Kredit membatasi berapa banyak catatan yang dipindai oleh satu permintaan. Jika rentang Anda cukup sibuk hingga mencapai batas tersebut, respons akan menyertakan "truncated": true. Saat Anda melihatnya, angka-angka tersebut didasarkan pada pemindaian parsial — persempit rentang tanggal Anda (atau buka halaman dengan jendela yang lebih kecil) untuk mendapatkan angka lengkap.

Catatan: Angka biaya dan token hanya disertakan untuk panggilan AI yang ditagihkan ke kunci API penyedia Anda sendiri. Saat angka biaya disembunyikan untuk akun Anda, respons akan mengatur "costs_redacted": true dan kolom biaya dikembalikan sebagai nol.

Ringkasan volume pesan

Mengembalikan penghitung peristiwa pesan yang diagregasi untuk akun Anda, baik sebagai total rentang maupun sebagai seri per hari. Setiap hari dalam rentang muncul di by_date — hari yang sepi diisi dengan nol. Secara opsional, filter ke satu kampanye dengan campaign_id.

GET /analytics/summary

Parameter	Wajib	Deskripsi
`from`	Tidak	Awal rentang, `YYYY-MM-DD`.
`to`	Tidak	Akhir rentang, `YYYY-MM-DD`.
`campaign_id`	Tidak	Hanya hitung peristiwa yang termasuk dalam kampanye ini.

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

Respons

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

Setiap entri dalam by_date memiliki kolom penghitung yang sama dengan totals, ditambah date.

Jika Anda memberikan campaign_id yang bukan milik akun Anda, responsnya adalah 404 dengan { "success": false, "error": "Campaign not found" }.

Penggunaan kredit

Mengembalikan penggunaan kredit selama rentang waktu: daftar catatan individual yang dipaginasi, ditambah total rentang dan rincian berdasarkan alasan serta kampanye.

GET /analytics/credits

Parameter	Wajib	Deskripsi
`from`	Tidak	Awal rentang, `YYYY-MM-DD`.
`to`	Tidak	Akhir rentang, `YYYY-MM-DD`.
`campaign_id`	Tidak	Hanya sertakan penggunaan yang diatribusikan ke kampanye ini.
`limit`	Tidak	Ukuran halaman untuk `records`, 1–100. Defaultnya adalah 50.
`cursor`	Tidak	Berikan `next_cursor` halaman sebelumnya untuk mengambil halaman berikutnya.

Penyesuaian vs. konsumsi: Perubahan saldo seperti bonus, pembaruan paket, dan koreksi dikecualikan dari totals dan rinciannya — ini bukan konsumsi nyata. Hal tersebut tetap muncul dalam daftar records, ditandai dengan "is_adjustment": true.

Total dan rincian hanya muncul di halaman pertama (saat tidak ada cursor yang diberikan). Pada halaman berikutnya, totals, by_reason, by_reason_cost, dan by_campaign dikembalikan sebagai null — hanya array records yang berlanjut. Ini menghindari pemindaian ulang seluruh rentang untuk setiap halaman.

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.

Respons (halaman pertama)

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

Catatan kolom:

amount — kredit yang dibebankan untuk catatan tersebut. Nol untuk catatan yang ditagihkan ke kunci API penyedia Anda sendiri.
is_adjustment — true untuk perubahan saldo (dikecualikan dari total/rincian).
cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — diisi hanya pada catatan yang ditagihkan ke kunci API penyedia Anda sendiri; nol atau null jika tidak.
is_test — true untuk uji coba/playground, yang tidak pernah ditagihkan.
next_cursor — kursor untuk halaman berikutnya, atau null jika tidak ada lagi catatan.

Ringkasan biaya AI

Mengembalikan ringkasan pengeluaran AI per hari untuk akun Anda. Ini membaca total harian yang telah diagregasi sebelumnya, sehingga cepat bahkan dalam rentang waktu yang lama. Setiap hari dalam rentang tersebut muncul di days — hari yang tenang diisi dengan nol.

GET /analytics/ai-cost

Parameter	Wajib	Deskripsi
`from`	Tidak	Awal rentang, `YYYY-MM-DD`.
`to`	Tidak	Akhir rentang, `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()

Respons

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

Catatan kolom:

byok_usd — pengeluaran yang ditagihkan ke kunci API penyedia Anda sendiri.
platform_usd — porsi pengeluaran yang berjalan di platform, bukan menggunakan kunci Anda sendiri.
input_usd, output_usd, cache_creation_usd, cache_read_usd — komponen biaya yang membentuk total_usd.
by_provider — pengeluaran dalam USD berdasarkan nama penyedia AI.
Angka USD hanya dikembalikan ke akun yang menggunakan kunci penyedia mereka sendiri. Untuk akun yang membayar dengan kredit, setiap kolom USD bernilai nol dan costs_redacted adalah true (jumlah panggilan tetap terlihat).

Seri metrik

Mengembalikan satu atau beberapa deret waktu metrik dalam satu panggilan, secara opsional dikelompokkan hingga dua dimensi — endpoint untuk mengikat grafik. Satu permintaan dapat menjawab “pesan terkirim dan dibalas per hari, per saluran, untuk kampanye ini” tanpa perlu satu panggilan per kampanye.

GET /analytics/series

Setiap respons membawa array labels (sumbu waktu, diisi nol di seluruh rentang) dan satu entri di series per grup, masing-masing menampung satu array per metrik yang diminta yang diselaraskan dengan labels. Seri setelah limit tidak dibuang — seri tersebut digabungkan ke dalam other_bucket, dihitung sebagai total rentang dikurangi seri yang dikembalikan, sehingga grafik yang dirender selalu berjumlah sesuai dengan angka asli Anda; truncated adalah true kapan pun itu terjadi.

Dari mana angka-angka tersebut berasal: sent, delivered, read, dan replied berasal dari catatan pesan, yang membawa saluran dan nomor pengirim. booked, contact_created, dan credits_spent berasal dari aliran peristiwa, yang tidak membawa nomor pengirim, sehingga metrik tersebut masuk ke bucket nomor null saat Anda mengelompokkan berdasarkan number.

Parameter	Wajib	Deskripsi
`from`	Tidak	Awal rentang, `YYYY-MM-DD`. Default-nya adalah 30 hari yang lalu.
`to`	Tidak	Akhir rentang, `YYYY-MM-DD`. Default-nya adalah hari ini.
`metrics`	Tidak	Daftar yang dipisahkan koma dari `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. Default-nya adalah `sent,replied`. Metrik yang tidak dikenal mengembalikan `400`.
`group_by`	Tidak	Daftar yang dipisahkan koma hingga dua dimensi dari `date`, `campaign`, `channel`, `agent`, `number`. `date` diterima tetapi tidak berpengaruh — setiap respons sudah membawa sumbu waktu. Abaikan untuk satu seri di seluruh akun.
`granularity`	Tidak	`day` (default), `week`, atau `month`. Bucket minggu dimulai pada hari Senin, bucket bulan pada tanggal 1.
`limit`	Tidak	Berapa banyak seri yang akan dikembalikan sebelum sisanya digabungkan ke dalam `other_bucket`, 1–50. Default-nya adalah 12.
`campaign_id`	Tidak	Hanya hitung aktivitas milik kampanye ini. Lama; lebih disukai `agent_id`.
`agent_id`	Tidak	Hanya hitung aktivitas milik Agen AI ini.
`channel`	Tidak	Hanya hitung aktivitas pada saluran ini, contohnya `whatsapp`.

Rentang tanggal endpoint ini dibatasi hingga 92 hari (lebih ketat daripada batas 366 hari yang digunakan di tempat lain di halaman ini).

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

Respons

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

Catatan kolom:

key — identitas satu seri. Hanya kunci untuk dimensi group_by yang diminta yang ada; dimensi yang nilainya tidak diketahui untuk baris (pesan tanpa kampanye, peristiwa tanpa saluran) akan kembali sebagai null alih-alih dibuang, sehingga seri tetap berjumlah sesuai dengan totalnya.
other_bucket — null saat tidak ada yang digabungkan.
Endpoint ini mengembalikan 503 dengan "error_code": "analytics_unavailable" saat basis data pelaporan tidak dapat menjawab untuk akun Anda, alih-alih 200 yang penuh dengan angka nol — grafik yang dinolkan akan dibaca sebagai fakta.

Hasil percakapan

Mengembalikan bagaimana percakapan berakhir selama rentang tanggal: jumlah per hari untuk setiap tag hasil yang ditetapkan AI, ditambah total rentang untuk balasan, pemesanan, serah terima ke manusia, dan percakapan yang tidak pernah diklasifikasikan oleh AI.

GET /analytics/outcomes

Berikan group_by=tag untuk menggabungkan sumbu waktu dan mendapatkan total rentang per tag saja — dalam mode tersebut labels kosong dan setiap array counts tag kosong, sementara total masih terisi.

Parameter	Wajib	Deskripsi
`from`	Tidak	Awal rentang, `YYYY-MM-DD`. Defaultnya adalah 30 hari yang lalu.
`to`	Tidak	Akhir rentang, `YYYY-MM-DD`. Defaultnya adalah hari ini.
`campaign_id`	Tidak	Hanya hitung percakapan dengan kontak yang saat ini ada di kampanye ini. Warisan; lebih disarankan `agent_id`.
`agent_id`	Tidak	Hanya hitung hasil yang dimiliki oleh Agen AI ini.
`group_by`	Tidak	`date` (default) mempertahankan jumlah per hari; `tag` menggabungkan menjadi total rentang.

Rentang tanggal titik akhir ini dibatasi hingga 92 hari.

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

Respons

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

Catatan kolom:

by_tag[].tag — null untuk percakapan yang tidak pernah diberi label hasil oleh AI.
totals.human_alerted — percakapan yang diserahkan kepada manusia; ini ditulis pada setiap penyerahan dan sebelumnya tidak dimunculkan oleh titik akhir mana pun.
Postur 503/analytics_unavailable yang sama seperti seri Metrik saat basis data pelaporan tidak dapat menjawab.

Wawasan dasbor

Mengembalikan payload dasbor lengkap untuk rentang tanggal dalam satu panggilan: peta panas tingkat balasan berdasarkan hari dalam seminggu dan jam, papan peringkat kampanye, volume per saluran, total per koneksi yang tepat, perincian metrik per hari (seluruh akun, per saluran, dan per nomor), asal kontak, waktu respons kotak masuk, dan umpan aktivitas terkini. Ini adalah payload pelaporan terkaya di API — yang menggerakkan dasbor dalam aplikasi secara langsung.

GET /analytics/dashboard-insights

Parameter	Wajib	Deskripsi
`startDate`	Ya	Awal rentang, `YYYY-MM-DD`.
`endDate`	Ya	Akhir rentang, `YYYY-MM-DD`.
`campaignId`	Tidak	Hanya sertakan aktivitas yang dimiliki oleh kampanye ini (`campaign_id` juga diterima). Warisan; lebih disarankan `agent_id`.
`agent_id`	Tidak	Hanya sertakan aktivitas yang dimiliki oleh Agen AI ini (`agentId` juga diterima). Di bawah cakupan agen, papan peringkat kampanye dibangun hanya dari aktivitas agen tersebut.

Titik akhir ini menggunakan startDate/endDate (bukan from/to) karena berbagi implementasi dengan dasbor dalam aplikasi. Rentang dibatasi hingga 92 hari dan dijepit (clamped), bukan ditolak, jika rentang tersebut lebih lebar.

Null berarti tidak tersedia, bukan nol. Beberapa blok (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) dihitung dari basis data pelaporan dan kembali sebagai null jika basis data tersebut tidak dapat menjawab untuk akun Anda. Jangan merender blok null sebagai bagan kosong.

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

Respons (disingkat — payload ini besar; lihat Referensi API untuk skema lengkapnya)

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

Catatan kolom:

heatmap.buckets[].weekday — 0 adalah Minggu hingga 6 adalah Sabtu.
numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — masing-masing secara independen null saat basis data pelaporan tidak tersedia untuk akun Anda; setiap blok lainnya tetap mengembalikan data.

Wawasan AI dasbor

Mengembalikan tiga wawasan singkat yang ditulis oleh AI tentang pesan akun selama rentang tanggal: satu kemenangan, satu hal yang perlu diperhatikan, dan satu kiat — kalimat yang dapat Anda tempel langsung ke dalam laporan alih-alih angka yang masih harus Anda interpretasikan. Dihasilkan hanya dari metrik pesan akun itu sendiri.

GET /analytics/dashboard-ai-insights

Parameter	Wajib	Deskripsi
`startDate`	Ya	Awal rentang, `YYYY-MM-DD`.
`endDate`	Ya	Akhir rentang, `YYYY-MM-DD`.

Titik akhir ini berlaku untuk seluruh akun — tidak memerlukan cakupan kampanye atau agen.

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

Respons

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

startDate atau endDate yang hilang akan mengembalikan 400.

Linimasa aktivitas entitas

Mengembalikan aktivitas satu kontak, kesepakatan, atau tugas sebagai satu linimasa, diurutkan dari yang terbaru: apa yang terjadi dan kapan, mencakup pesan, janji temu, catatan, dan perubahan status. Gunakan ini untuk menjawab “apa yang telah terjadi dengan orang ini” tanpa harus menggabungkan beberapa titik akhir daftar.

GET /analytics/entity-activity

Parameter	Wajib	Deskripsi
`entityType`	Ya	`contact`, `deal`, atau `task`.
`entityId`	Ya	ID catatan yang linimasanya ingin dikembalikan.

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

Respons

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

entityType/entityId yang hilang atau tidak valid akan mengembalikan 400. Entitas yang tidak ada di akun Anda akan mengembalikan 404, sehingga ID akun lain tetap tidak dapat ditebak.

Jumlah peristiwa gabungan (warisan)

Mengembalikan jumlah peristiwa gabungan yang sama seperti Ringkasan volume pesan, tetapi dalam bentuk camelCase (contactCreated alih-alih contact_created, byDate alih-alih by_date) yang digunakan oleh beberapa integrasi lama. Gunakan /analytics/summary untuk integrasi baru — titik akhir ini ada hanya agar dasbor dalam aplikasi dan API berbagi implementasi yang sama.

GET /analytics/aggregate

Parameter	Wajib	Deskripsi
`startDate`	Tidak	Awal rentang, tanggal atau tanggal-waktu ISO. Default ke jendela yang sama yang digunakan `/analytics/summary`.
`endDate`	Tidak	Akhir rentang, tanggal atau tanggal-waktu ISO.
`campaignId`	Tidak	Hanya hitung peristiwa milik kampanye ini (`campaign_id` juga diterima). Warisan; gunakan `agent_id`.
`agent_id`	Tidak	Hanya hitung peristiwa milik Agen AI ini (`agentId` juga diterima).

cURL

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

Respons

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

Penggabungan sub-akun agensi

Kesalahan API Analytics

Endpoint Analytics mengembalikan amplop kesalahan standar:

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

Pada titik akhir analitik, format tanggal yang tidak valid atau jendela di luar rentang akan mengembalikan 400, dan campaign_id atau agent_id yang tidak diketahui akan mengembalikan 404. Mengirim campaign_id dan agent_id sekaligus pada titik akhir yang hanya menerima salah satunya juga merupakan 400 — kirimkan maksimal satu. Titik akhir pelaporan khusus PG (Seri metrik, Hasil percakapan, Penggabungan agensi) mengembalikan 503 dengan "error_code": "analytics_unavailable" alih-alih 200 yang penuh dengan angka nol ketika basis data pelaporan tidak dapat menjawab untuk akun Anda — coba lagi dalam waktu singkat. Kode bersama yang dapat dikembalikan oleh setiap titik akhir — 401, 403 (paket Anda tidak menyertakan akses API, atau, pada penggabungan agensi, akun Anda bukan Agensi/Dev), 429 (batas kecepatan), dan 500 — tercantum dengan panduan percobaan ulang di Kesalahan & Penomoran Halaman.

Langkah berikutnya

Autentikasi — empat cara untuk mengautentikasi permintaan.
Error & Batas Kecepatan — kode status dan batas 300 permintaan/menit.
API Kampanye — kampanye yang dapat digunakan untuk memfilter angka-angka ini.

API Analitik & Laporan #

Rentang tanggal #

Flag truncated #

Ringkasan volume pesan #

Penggunaan kredit #

Ringkasan biaya AI #

Seri metrik #

Hasil percakapan #

Wawasan dasbor #

Wawasan AI dasbor #

Linimasa aktivitas entitas #

Jumlah peristiwa gabungan (warisan) #

Penggabungan sub-akun agensi #

Kesalahan API Analytics #

Langkah berikutnya #

API Analitik & Laporan

Rentang tanggal

Flag `truncated`

Ringkasan volume pesan

Penggunaan kredit

Ringkasan biaya AI

Seri metrik

Hasil percakapan

Wawasan dasbor

Wawasan AI dasbor

Linimasa aktivitas entitas

Jumlah peristiwa gabungan (warisan)

Penggabungan sub-akun agensi

Kesalahan API Analytics

Langkah berikutnya