Analitik ve Raporlar API’si #

Bu salt okunur uç noktalar, hesabınızın etkinliğini kendi panolarınıza ve raporlarınıza çekmenizi sağlar: mesaj olayı sayıları, kredi tüketimi, yapay zeka harcamaları ve uygulama içi panonun gösterdiği grafikler ve içgörülerin aynısı. Bu kılavuz şunları kapsar:

• Özet — mesaj hacmi sayaçları (gönderilen, iletilen, okunan, yanıtlanan, rezerve edilen, oluşturulan kişiler, krediler).
• Krediler — toplamlar ve dökümlerle birlikte kredi kullanımının ayrıntılı, sayfalandırılmış bir defteri.
• Yapay zeka maliyeti — günlük yapay zeka harcamalarının toplamı.
• Metrik serileri — kampanya, kanal, Yapay Zeka Temsilcisi veya numaraya göre gruplandırılmış, grafik oluşturmaya hazır zaman serileri.
• Konuşma sonuçları — taşıdıkları kişi etiketlerine (temsilcinizin uyguladığı kapanış etiketleri) göre gruplandırılmış, zaman içindeki konuşmalar.
• Konuşma maliyetleri: yapay zekanın tek başına yönettiği bir konuşmanın, ekibinizin dahil olduğu bir konuşmaya kıyasla ortalama kredi maliyeti.
• Panel içgörüleri ve Panel yapay zeka içgörüleri — yapay zeka tarafından yazılmış özetler dahil olmak üzere, uygulama içi panelin arkasındaki tüm veriler.
• Varlık etkinliği — tek bir kişinin, anlaşmanın veya görevin zaman çizelgesi.
• Toplu etkinlik sayıları — mevcut entegrasyonlar için tutulan, Özet’in eski, camelCase biçimi.

Bu sayfadaki her uç nokta, her ikisi birden değil, tam bir kapsam gerektirir: uç noktanın kabul ettiği durumlarda campaign_id (eski) veya agent_id değerlerinden en fazla birini iletin. Her ikisini de göndermek 400 sonucunu döndürür ve hesabınızda bulunmayan bir kimlik, 403 yerine 404 döndürür; böylece diğer hesapların kimlikleri tahmin edilemez kalır.

Yalnızca iki uç nokta kişi etiketine göre filtreleme yapar. tag_ids (ve tag_match ile birlikte), Dashboard insights ve Aggregated event counts tarafından dikkate alınır — uygulama içi panonun Tüm etiketler filtresinin kullandığı iki uç nokta bunlardır. Summary, Metric series ve Conversation outcomes parametreyi doğrular (hatalı bir kimlik listesi yine de 400 döndürür) ancak parametreyi uygulamaz: size hesap genelindeki sayıları geri döndürür ve bunu bildiren bir hata mesajı vermez. Filtrelenmemiş bir toplamı, etiketle filtrelenmiş bir toplam gibi okumayın.

Aşağıdaki tüm yollar, API temel URL’sine göre belirlenmiştir:

https://api.youraiconnector.com/v1

Her isteğin kimliği doğrulanmalıdır. Kabul edilen dört yöntem için Kimlik Doğrulama bölümüne bakın. Buradaki örnekler X-API-Key başlığını (ve cURL için bir sorgu parametresi biçimini) kullanır.

Tarih aralığı #

Her üç uç nokta da aynı isteğe bağlı tarih filtrelerini kabul eder:

Tarihler UTC olarak yorumlanır. Aralık varsayılan olarak son 30 gündür ve 366 gün ile sınırlandırılmıştır; daha geniş bir aralık 400 döndürür. from, to tarihinden sonra olmamalıdır.

truncated bayrağı #

Özet ve Krediler uç noktaları, tek bir isteğin tarayabileceği kayıt sayısını sınırlar. Aralığınız bu sınıra ulaşacak kadar yoğunsa, yanıt "truncated": true içerir. Bunu gördüğünüzde, sayılar kısmi bir taramaya dayalıdır; tam rakamları almak için tarih aralığınızı daraltın (veya daha küçük bir pencereyle sayfalar arasında gezinin).

Mesaj hacmi özeti #

Hesabınız için hem aralık toplamları hem de günlük seri olarak toplanmış mesaj etkinliği sayaçlarını döndürür. Aralıktaki her gün by_date içinde görünür; sessiz günler sıfır ile doldurulur. İsteğe bağlı olarak campaign_id ile tek bir kampanyaya filtre uygulayın.

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

Yanıt

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

by_date içindeki her girdi, totals ile aynı sayaç alanlarına ve ek olarak bir date değerine sahiptir.

Hesabınıza ait olmayan bir campaign_id gönderirseniz, yanıt { "success": false, "error": "Campaign not found" } ile birlikte 404 olur.

Kredi kullanımı #

Belirtilen aralıktaki kredi kullanımını döndürür: sayfalandırılmış bireysel kayıt listesi ile birlikte aralık toplamları ve neden ile kampanyaya göre dökümler.

GET /analytics/credits

Düzeltmeler ve tüketim: Bonuslar, plan yenilemeleri ve düzeltmeler gibi bakiye değişiklikleri totals ve dökümlerden hariç tutulur; bunlar gerçek tüketim değildir. Yine de "is_adjustment": true ile işaretlenmiş olarak records listesinde görünürler.

Toplamlar ve dökümler yalnızca ilk sayfada görünür (herhangi bir cursor sağlanmadığında). Sonraki sayfalarda totals, by_reason, by_reason_cost ve by_campaign değerleri null olarak döndürülür; yalnızca records dizisi devam eder. Bu, her sayfa için tüm aralığın yeniden taranmasını önler.

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.

Yanıt (ilk sayfa)

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

Alan notları:

• amount — kayıt için tahsil edilen krediler. Kendi sağlayıcı API anahtarınız üzerinden faturalandırılan kayıtlar için sıfırdır.
• is_adjustment — bakiye değişiklikleri için true (toplamlardan/dökümlerden hariç tutulur).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — yalnızca kendi sağlayıcı API anahtarınız üzerinden faturalandırılan kayıtlarda doldurulur; aksi takdirde sıfır veya null değerini alır.
• is_test — asla faturalandırılmayan oyun alanı/test çalışmaları için true.
• next_cursor — bir sonraki sayfa için imleç veya daha fazla kayıt kalmadığında null.

Kredi bakiyesi #

GET /users/me/credits — hesabınızın mevcut kredi durumu tek bir çağrıda: harcanacak ne kadar kaldığı, aylık ödenek ve otomatik yükleme ile düşük kredi ayarları. Yukarıdaki kredi kullanımı bir geçmiştir; bu ise şu anki bakiyedir. Buna erişen ekip üyelerinin faturalandırma erişimine sahip olması gerekir; hesap sahibinin anahtarı her zaman bu erişime sahiptir.

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

Yanıt (200)

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

Ajanslar, bir müşteri hesabının bakiyesini okumak için sub_account_id değerini iletebilir. Bir otomasyonun içinde, Kredileri kontrol et adımı aynı alanları döndürür.

Yapay zeka maliyet özeti #

Hesabınız için günlük yapay zeka harcama özetini döndürür. Bu, önceden toplanmış günlük toplamları okur, bu nedenle uzun aralıklarda bile hızlıdır. Aralıktaki her gün days içinde görünür; işlem yapılmayan günler sıfır ile doldurulur.

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

Yanıt

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

Alan notları:

• byok_usd — kendi sağlayıcı API anahtarlarınız üzerinden faturalandırılan harcama.
• platform_usd — kendi anahtarınız yerine platform üzerinde çalışan harcama kısmı.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — total_usd’yı oluşturan maliyet bileşenleri.
• by_provider — AI sağlayıcı adına göre anahtarlanmış USD harcaması.
• USD rakamları yalnızca kendi sağlayıcı anahtarını kullanan hesaplara döndürülür. Kredi ile ödeme yapan hesaplar için her USD alanı sıfırdır ve costs_redacted değeri true’dur (çağrı sayıları görünür kalır).

Metrik serileri #

Tek bir çağrıda bir veya daha fazla metrik zaman serisi döndürür, isteğe bağlı olarak iki boyuta kadar gruplandırılabilir — bir grafiği bağlamak için kullanılan uç nokta. Tek bir istek, kampanya başına bir çağrı yapmadan “bu kampanya için kanal başına, günlük gönderilen ve yanıtlanan” sorusunu yanıtlayabilir.

GET /analytics/series

Her yanıt bir labels dizisi (zaman ekseni, tüm aralık boyunca sıfırlarla doldurulmuş) ve series içinde grup başına bir girdi taşır; her biri labels ile hizalanmış, istenen metrik başına bir dizi tutar. limit sonrasındaki seriler atılmaz; bunlar, toplam aralıktan döndürülen serinin çıkarılmasıyla hesaplanan other_bucket içinde toplanır, böylece oluşturulan bir grafik her zaman gerçek sayılarınızla eşleşir; bu durum gerçekleştiğinde truncated, true değerini alır.

Sayıların kaynağı: sent, delivered, read ve replied, kanal ve gönderen numarayı taşıyan mesaj kayıtlarından gelir. booked, contact_created ve credits_spent, gönderen numarası taşımayan olay akışından gelir, bu nedenle number’e göre gruplandırma yaptığınızda bu metrikler null numaralı kovaya düşer.

conversations, her bir grupta başlayan konuşmaları (sohbet oturumları) sayar ve conversation_credits, Konuşma maliyetleri ile tam olarak aynı şekilde hesaplanan bu konuşmaların maliyetini gösterir. Zaman içindeki ortalama konuşma başına maliyeti bulmak için grup başına birini diğerine bölün. Kampanya, temsilci, kanal veya numaraya göre gruplandırdığınızda veya filtrelediğinizde, bir konuşma, ilk mesajının ait olduğu öğeye dahil edilir.

Bu uç noktanın tarih aralığı 92 gün ile sınırlandırılmıştır (bu sayfada başka yerlerde kullanılan 366 günlük sınırdan daha dardır).

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

Yanıt

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

Alan notları:

• key — bir serinin kimliği. Yalnızca istenen group_by boyutlarına ait anahtarlar mevcuttur; bir satır için değeri bilinmeyen bir boyut (kampanyası olmayan bir mesaj, kanalı olmayan bir olay), atılmak yerine null olarak geri döner, böylece seriler toplamlarla eşleşmeye devam eder.
• other_bucket — hiçbir şey toplanmadığında null.
• Bu uç nokta, raporlama veritabanı hesabınız için yanıt veremediğinde, sıfırlarla dolu bir 200 yerine "error_code": "analytics_unavailable" ile 503 döndürür; sıfırlanmış bir grafik gerçek gibi okunabilir.

Konuşma sonuçları #

Belirli bir tarih aralığındaki konuşma sonuçlarını döndürür: her kişi etiketi altındaki konuşmaların günlük sayısı ve ayrıca yanıtlar, rezervasyonlar, bir insana devretmeler ve kişisi hiçbir etiket taşımayan konuşmalar için aralık toplamları.

Etiket bir kişi etiketidir: Yapay Zeka Temsilcinizin etiket aracı, otomatik etiket kuralları, API veya ekibiniz aracılığıyla uyguladığı etiketler. Bu, konuşma başına bir etiket değildir. Bir konuşma, istek anında kişisinin taşıdığı etiketler altında sayılır; bu nedenle birden fazla etikete sahip bir kişi her biri altında bir kez sayılır ve daha sonra kaldırılan bir etiket geçmiş günlerden de düşer. Temsilcinize sonuç başına bir kapanış etiketi verin (örneğin resolved_ai, handoff_asked_for_human) ve bu uç nokta zaman içindeki kapsama ve devretme nedenlerini döndürsün.

GET /analytics/outcomes

Zaman eksenini daraltmak ve yalnızca etiket başına aralık toplamlarını almak için group_by=tag değerini iletin; bu modda labels boştur ve her etiketin counts dizisi boştur, ancak total hala doldurulmuştur.

Bu uç noktanın tarih aralığı 92 gün ile sınırlandırılmıştır.

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

Yanıt

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

Alan notları:

• by_tag[].tag / by_tag[].tag_id — kişi etiketinin adı ve kimliği; her ikisi de kişisi hiçbir etiket taşımayan konuşmalar satırında null değerindedir. En fazla 20 etiket döndürülür, en yüksek hacimli olanlar önce gelir.
• totals.sessions — aralık içinde başlatılan farklı konuşmalar. Bu, by_tag[].total değerlerinin toplamı değildir: üç etikete sahip bir kişi, üç satıra birer konuşma katkısında bulunur.
• totals.unresolved — kişisi hiçbir etiket taşımayan konuşmalar.
• totals.human_alerted — bir insana devredilen konuşmalar; bu her devretme işleminde yazılır ve daha önce hiçbir uç nokta tarafından sunulmamıştı.
• Raporlama veritabanı yanıt veremediğinde Metrik serileri ile aynı 503/analytics_unavailable duruşu.

Konuşma maliyetleri #

Bir tarih aralığında konuşmanın nasıl geçtiğine göre bölünmüş olarak ortalama maliyetini döndürür. Bu, bir müşteriye yatırım getirisi olarak gösterilecek sayıdır: yapay zekanın tek başına yönettiği bir konuşmanın maliyeti, ekibinizin dahil olması gereken bir konuşmanın maliyetiyle yan yana.

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"

Yanıt

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

Alan notları:

• Aralık içinde başlayan konuşmaları (sohbet oturumları) sayar; her konuşmanın penceresi içinde tahsil edilen krediler dahil edilir, iadeler düşülür. Herhangi bir konuşmanın dışında harcanan krediler (günlük özetler, aylık ücretler, bir kişi tarafından başlatılmayan otomasyonlar, örneğin webhook veya RSS tetikleyicileri) buna dahil değildir. Bir kişi tarafından başlatılan otomasyon çalışmaları ve yapay zeka adımları, 26 Eylül 2026’dan itibaren o kişinin konuşmasına dahil edilir.
• contained: Yapay zeka yanıt verdi ve ekibinizden kimsenin müdahale etmesi gerekmedi. handed_off: Yapay zeka yanıt verdikten sonra birisi mesaj gönderdi veya yapay zeka bir insanı uyardı. no_ai: Yapay zeka hiç yanıt vermedi (örneğin, yapay zeka duraklatılmışken ekibinizin yönettiği sohbetler).
• En fazla 20.000 konuşma sayılır; aralık daha fazlasını içerdiğinde sessions_truncated, true değerini alır, bu yüzden aralığı daraltın.
• Ekip üyeleri için faturalandırma izni gerektirir. Metrik serileri ile aynı 503/analytics_unavailable tutumuna sahiptir.
• Kişi bazında aynı ayrım Kişi maliyetini al kısmında mevcuttur.

Gösterge paneli içgörüleri #

Tek bir çağrıda bir tarih aralığı için tam gösterge paneli yükünü döndürür: hafta içi ve saate göre yanıt oranı ısı haritası, kampanya liderlik tablosu, kanal başına hacim, bağlantı başına kesin toplamlar, günlük metrik dökümleri (hesap genelinde, kanal başına ve numara başına), kişilerin nereden geldiği, gelen kutusu yanıt süresi ve son etkinlik akışı. Bu, API’deki en zengin raporlama yüküdür; doğrudan uygulama içi gösterge paneline güç sağlar.

GET /analytics/dashboard-insights

Bu uç nokta startDate/endDate kullanır ( from/to değil), çünkü uygulamasını uygulama içi gösterge paneli ile paylaşır. Aralık 92 gün ile sınırlandırılmıştır ve daha geniş olduğunda reddedilmez, kırpılır.

Null, sıfır değil, kullanılamaz anlamına gelir. Birkaç blok (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) raporlama veritabanından hesaplanır ve hesabınız için yanıt veremediğinde null olarak döner. Bir null bloğunu boş bir grafik olarak oluşturmayın.

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

Yanıt (kısaltılmış — bu yük büyüktür; tam şema için API Referansına bakın)

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

Alan notları:

• heatmap.buckets[].weekday — 0 Pazar gününden 6 Cumartesi gününe kadardır.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — her biri, raporlama veritabanı hesabınız için kullanılamadığında bağımsız olarak null değerini alır; diğer tüm bloklar yine de döner.

Yapay Zeka gösterge paneli içgörüleri #

Bir tarih aralığında hesabın mesajlaşması hakkında yapay zeka tarafından yazılmış üç kısa içgörü döndürür: bir başarı, izlenmesi gereken bir şey ve bir ipucu — yorumlamanız gereken sayılar yerine doğrudan bir rapora yapıştırabileceğiniz cümleler. Yalnızca hesabın kendi mesaj metriklerinden oluşturulmuştur.

GET /analytics/dashboard-ai-insights

Bu uç nokta hesap genelindedir; kampanya veya temsilci kapsamı almaz.

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

Yanıt

{
  "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 veya endDate eksik olduğunda 400 döner.

Varlık etkinlik zaman çizelgesi #

Tek bir kişiye, anlaşmaya veya göreve ait etkinlikleri, en yeniden başlayarak tek bir zaman çizelgesi olarak döndürür: mesajlar, randevular, notlar ve durum değişiklikleri genelinde neyin, ne zaman gerçekleştiği. Bunu, birden fazla liste uç noktasını birleştirmek zorunda kalmadan “bu kişiyle neler oldu” sorusunu yanıtlamak için kullanın.

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

Yanıt

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

Eksik veya geçersiz bir entityType/entityId, 400 döndürür. Hesabınızda bulunmayan bir varlık 404 döndürür, böylece diğer hesapların kimlikleri tahmin edilemez kalır.

Toplu etkinlik sayıları (eski) #

Mesaj hacmi özeti ile aynı toplu etkinlik sayılarını döndürür, ancak bazı eski entegrasyonların üzerine inşa edildiği camelCase biçiminde (contact_created yerine contactCreated, by_date yerine byDate). Yeni entegrasyonlar için /analytics/summary tercih edin; bu uç nokta yalnızca uygulama içi kontrol paneli ile API’nin tek bir uygulamayı paylaşması için mevcuttur.

GET /analytics/aggregate

cURL

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

Yanıt

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

Ajans alt hesap toplamı #

Analytics API hataları #

Analytics uç noktaları standart hata zarfını döndürür:

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

Bir analiz uç noktasında, geçersiz bir tarih biçimi veya aralık dışı bir pencere 400 döndürür ve bilinmeyen bir campaign_id veya agent_id, 404 döndürür. Her ikisini de kabul eden bir uç noktaya hem campaign_id hem de agent_id göndermek de bir 400’dır — en fazla birini gönderin. Yalnızca PG raporlama uç noktaları (Metrik serileri, Görüşme sonuçları, Ajans toplamı), raporlama veritabanı hesabınız için yanıt veremediğinde sıfırlarla dolu bir 200 yerine "error_code": "analytics_unavailable" ile 503 döndürür — kısa süre sonra tekrar deneyin. Her uç noktanın döndürebileceği paylaşılan kodlar — 401, 403 (planınız API erişimini içermiyor veya ajans toplamında hesabınız Ajans/Geliştirici değil), 429 (hız sınırı) ve 500 — Hatalar ve Sayfalama bölümünde yeniden deneme rehberliği ile listelenmiştir.

Sonraki adımlar #

• Kimlik Doğrulama — bir isteğin kimliğini doğrulamak için kullanılan dört yöntem.
• Hatalar ve Hız Sınırları — durum kodları ve 300 istek/dakika sınırı.
• Yapay Zeka Ajanları API’si — bu figürlerin filtrelenebileceği Ajanlar.