API ניתוח ודוחות #

נקודות קצה לקריאה בלבד אלו מאפשרות לך למשוך את פעילות החשבון שלך ללוחות המחוונים ולדוחות שלך: ספירות אירועי הודעות, צריכת קרדיטים, הוצאות AI, ואותם תרשימים ותובנות שמוצגים בלוח המחוונים בתוך האפליקציה. מדריך זה מכסה:

• סיכום — מוני נפח הודעות (נשלחו, נמסרו, נקראו, נענו, הוזמנו, אנשי קשר שנוצרו, קרדיטים).
• קרדיטים — ספר חשבונות מפורט וממוספר של ניצול קרדיטים עם סיכומים ופירוטים.
• עלות AI — סיכום יומי של הוצאות ה-AI.
• סדרות מדדים — סדרת עיתוי מוכנה לתרשים עבור מדד אחד או יותר, מקובצת לפי קמפיין, ערוץ, סוכן AI או מספר.
• תוצאות שיחה — שיחות לאורך זמן, מקובצות לפי תגיות איש הקשר שהן נושאות (תגיות הסגירה שהסוכן שלך מחיל).
• עלויות שיחה: עלות הקרדיט הממוצעת של שיחה שה-AI טיפל בה לבדו לעומת שיחה שהצוות שלך התערב בה.
• תובנות לוח מחוונים ו-תובנות AI ללוח מחוונים — הנתונים המלאים מאחורי לוח המחוונים באפליקציה, כולל סיכומים שנכתבו על ידי ה-AI.
• פעילות ישות — ציר הזמן של איש קשר, עסקה או משימה בודדים.
• ספירות אירועים מצטברות — צורה מיושנת ב-camelCase של סיכום שנשמרה עבור אינטגרציות קיימות.

כל נקודת קצה בדף זה דורשת היקף (scope) מדויק, לא את שניהם: העבר לכל היותר אחד מ-campaign_id (מיושן) או agent_id היכן שנקודת הקצה מקבלת זאת. שליחת שניהם מחזירה 400, ומזהה (id) שאינו בחשבונך מחזיר 404 במקום 403, כך שמזהים של חשבונות אחרים נשארים בלתי ניתנים לניחוש.

רק שני נקודות קצה מסננות לפי תגית איש קשר. tag_ids (עם tag_match) מכובד על ידי תובנות לוח הבקרה ו-ספירות אירועים מצטברות — אלו השניים שבהם משתמש המסנן כל התגיות בלוח הבקרה בתוך האפליקציה. סיכום, סדרות מדדים ו-תוצאות שיחה מאמתים את הפרמטר (רשימת מזהים פגומה עדיין מחזירה 400) אך לא מחילים אותו: תקבל בחזרה מספרים ברמת החשבון, ללא שגיאה שתציין זאת. אל תקרא סך הכל לא מסונן כסך הכל מסונן לפי תגית.

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית של ה-API:

https://api.youraiconnector.com/v1

כל בקשה חייבת לעבור אימות. ראה Authentication עבור ארבע השיטות המקובלות. הדוגמאות כאן משתמשות ב-header מסוג X-API-Key (וטופס פרמטר שאילתה אחד עבור cURL).

טווח תאריכים #

כל שלוש נקודות הקצה מקבלות את אותם מסנני תאריכים אופציונליים:

תאריכים מתפרשים לפי UTC. ברירת המחדל של הטווח היא 30 הימים האחרונים והוא מוגבל ל-366 ימים — טווח רחב יותר יחזיר 400. from חייב להיות לפני או שווה ל-to.

הדגל truncated #

נקודות הקצה סיכום ו-קרדיטים מגבילות את מספר הרשומות שבקשה בודדת סורקת. אם הטווח שלך עמוס מספיק כדי להגיע למגבלה זו, התגובה כוללת "truncated": true. כאשר אתה רואה זאת, המספרים מבוססים על סריקה חלקית — צמצם את טווח התאריכים שלך (או דפדף עם חלון קטן יותר) כדי לקבל נתונים מלאים.

סיכום נפח הודעות #

מחזיר מוני אירועי הודעות מצטברים עבור החשבון שלך, הן כסיכומי טווח והן כסדרה יומית. כל יום בטווח מופיע ב-by_date — ימים שקטים ימולאו באפסים. ניתן לסנן באופן אופציונלי לקמפיין בודד באמצעות campaign_id.

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

תגובה

{
  "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 יש את אותם שדות מונה כמו ב-totals, בתוספת date.

אם תעביר campaign_id שאינו שייך לחשבון שלך, התגובה תהיה 404 עם { "success": false, "error": "Campaign not found" }.

ניצול קרדיט #

מחזיר את ניצול הקרדיט לאורך הטווח: רשימה מפוצלת לדפים של רשומות בודדות, בתוספת סיכומי טווח ופירוט לפי סיבה ולפי קמפיין.

GET /analytics/credits

התאמות לעומת צריכה: שינויים ביתרה כגון בונוסים, חידושי תוכנית ותיקונים אינם נכללים ב-totals ובפירוטים — הם אינם צריכה אמיתית. הם עדיין מופיעים ברשימת ה-records, מסומנים ב-"is_adjustment": true.

סיכומים ופירוטים מופיעים רק בדף הראשון (כאשר לא מסופק cursor). בדפים הבאים, totals, by_reason, by_reason_cost ו-by_campaign מוחזרים כ-null — רק מערך ה-records ממשיך. זה מונע סריקה מחדש של כל הטווח עבור כל דף.

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.

תגובה (דף ראשון)

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

הערות שדה:

• amount — קרדיטים שחויבו עבור הרשומה. אפס עבור רשומות שחויבו במפתח ה-API של הספק שלך.
• is_adjustment — true עבור שינויים ביתרה (לא נכללים בסיכומים/פירוטים).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — מאוכלסים רק ברשומות שחויבו במפתח ה-API של הספק שלך; אחרת אפס או null.
• is_test — true עבור הרצות ניסיון/בדיקה, שלעולם אינן מחויבות.
• next_cursor — הסמן לדף הבא, או null כאשר אין יותר רשומות.

יתרת קרדיטים #

GET /users/me/credits — מצב הקרדיטים הנוכחי בחשבון שלך בשיחה אחת: מה נותר להוציא, ההקצבה החודשית, והגדרות הטעינה האוטומטית והיתרה הנמוכה. השימוש בקרדיטים לעיל הוא היסטוריה; זהו היתרה נכון לעכשיו. חברי צוות שקוראים לזה זקוקים להרשאת חיוב; למפתח של בעל החשבון יש אותה תמיד.

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

תגובה (200)

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

סוכנויות יכולות להעביר sub_account_id כדי לקרוא את היתרה של חשבון לקוח. בתוך אוטומציה, שלב בדיקת קרדיטים מחזיר את אותם שדות.

ריכוז עלויות AI #

מחזיר את ריכוז הוצאות ה-AI היומי עבור החשבון שלך. פעולה זו קוראת סיכומים יומיים שעברו צבירה מראש, לכן היא מהירה גם בטווחים ארוכים. כל יום בטווח מופיע ב-days — ימים שקטים ימולאו באפסים.

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

תגובה

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

הערות שדה:

• byok_usd — הוצאות שחויבו במפתחות ה-API של הספק שלך.
• platform_usd — חלק ההוצאות שרץ על הפלטפורמה במקום על המפתח שלך.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — רכיבי העלות המרכיבים את total_usd.
• by_provider — הוצאות בדולר ארה"ב לפי שם ספק ה-AI.
• נתוני דולר ארה"ב מוחזרים רק לחשבונות המשתמשים במפתח ספק משלהם. עבור חשבונות המשלמים באמצעות קרדיט, כל שדה דולרי הוא אפס ו-costs_redacted הוא true (ספירות הקריאות נשארות גלויות).

סדרות מדדים #

מחזירה סדרת עתים אחת או יותר של מדדים בקריאה אחת, מקובצת אופציונלית לפי עד שני ממדים — נקודת הקצה לחיבור תרשים. בקשה אחת יכולה לענות על “נשלחו ונענו ליום, לפי ערוץ, עבור קמפיין זה” ללא צורך בקריאה נפרדת לכל קמפיין.

GET /analytics/series

כל תגובה נושאת מערך labels (ציר הזמן, מאופס לכל הטווח) וכניסה אחת ב-series לכל קבוצה, כאשר כל אחת מחזיקה מערך אחד לכל מדד מבוקש המיושר ל-labels. סדרות מעבר ל-limit אינן מושמטות — הן מתכנסות ל-other_bucket, המחושב כסך הטווח פחות הסדרות שהוחזרו, כך שתרשים מוצג תמיד מסתכם למספרים האמיתיים שלך; truncated הוא true בכל פעם שזה קורה.

מאיפה מגיעים המספרים: sent, delivered, read ו-replied מגיעים מרשומות הודעות, הנושאות את הערוץ ומספר השולח. booked, contact_created ו-credits_spent מגיעים מזרם האירועים, שאינו נושא מספר שולח, לכן מדדים אלו נוחתים בדלי ה-null-מספר כאשר אתה מקבץ לפי number.

conversations סופר את השיחות (סשנים של צ’אט) שהחלו בכל דלי, ו-conversation_credits את העלות של אותן שיחות, מחושבות בדיוק כמו עלויות שיחה. חלקו את האחד בשני לפי דלי עבור העלות הממוצעת לשיחה לאורך זמן. כאשר אתם מקבצים או מסננים לפי קמפיין, סוכן, ערוץ או מספר, שיחה נספרת עבור זה שההודעה הראשונה שלה שייכת אליו.

טווח התאריכים של נקודת קצה זו מוגבל ל-92 ימים (מחמיר יותר מהמגבלה של 366 ימים המשמשת במקומות אחרים בדף זה).

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

תגובה

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

הערות שדה:

• key — הזהות של סדרה אחת. רק המפתחות עבור ממדי ה-group_by המבוקשים נוכחים; ממד שערכו אינו ידוע עבור שורה (הודעה ללא קמפיין, אירוע ללא ערוץ) חוזר כ-null במקום להיות מושמט, כך שהסדרות עדיין מסתכמות לסכומים הכוללים.
• other_bucket — null כאשר שום דבר לא התכנס.
• נקודת קצה זו מחזירה 503 עם "error_code": "analytics_unavailable" כאשר מסד הנתונים של הדיווח אינו יכול לענות עבור החשבון שלך, במקום 200 מלא באפסים — תרשים מאופס היה נקרא כעובדה.

תוצאות שיחה #

מחזיר את תוצאות השיחה בטווח תאריכים: ספירה יומית של שיחות תחת כל תגית איש קשר, בתוספת סיכומי טווח עבור תשובות, הזמנות, העברות לנציג אנושי, ושיחות שאיש הקשר שלהן אינו נושא תגית.

התגית היא תגית איש קשר: התגיות שסוכן ה-AI שלך מחיל באמצעות כלי התגיות שלו, כללי תיוג אוטומטי, ה-API או הצוות שלך. זו אינה תווית לכל שיחה. שיחה נספרת תחת התגיות שאיש הקשר שלה נושא בזמן הבקשה, כך שאיש קשר עם מספר תגיות נספר פעם אחת תחת כל אחת מהן, ותגית שמוסרת מאוחר יותר תוסר גם מימים קודמים. תן לסוכן שלך תגית סגירה אחת לכל תוצאה (למשל resolved_ai, handoff_asked_for_human) ונקודת קצה זו תחזיר את נתוני ההכלה וסיבות ההעברה לאורך זמן.

GET /analytics/outcomes

העבר group_by=tag כדי לכווץ את ציר הזמן ולקבל סכומי טווח לכל תג בלבד — במצב זה labels ריק וכל מערך counts של תג ריק, בעוד total עדיין מאוכלס.

טווח התאריכים של נקודת קצה זו מוגבל ל-92 ימים.

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

תגובה

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

הערות שדה:

• by_tag[].tag / by_tag[].tag_id — השם והמזהה של תגית איש הקשר; שניהם null בשורה של שיחות שאיש הקשר שלהן אינו נושא תגית. לכל היותר 20 תגיות יוחזרו, לפי סדר נפח גבוה תחילה.
• totals.sessions — שיחות נפרדות שהחלו בטווח. זה אינו הסכום של by_tag[].total: איש קשר עם שלוש תגיות תורם שיחה אחת לשלוש שורות.
• totals.unresolved — שיחות שאיש הקשר שלהן אינו נושא תגית.
• totals.human_alerted — שיחות שהועברו לנציג אנושי; זה נרשם בכל העברה ולא הוצג בעבר על ידי אף נקודת קצה.
• אותה התנהגות 503/analytics_unavailable כמו בסדרות מדדים כאשר מסד הנתונים של הדיווח אינו יכול להשיב.

עלויות שיחה #

מחזיר את העלות הממוצעת של שיחה לאורך טווח תאריכים, מחולקת לפי אופן התנהלותה. זהו המספר להצגה ללקוח כהחזר על השקעה: מה עולה שיחה שה-AI טיפל בה לבדו, לצד שיחה שהצוות שלך נאלץ להתערב בה.

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"

תגובה

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

הערות שדה:

• סופר שיחות (סשנים של צ’אט) שהחלו בטווח, עם הקרדיטים שחויבו בתוך חלון הזמן של כל שיחה, בניכוי החזרים. קרדיטים שהוצאו מחוץ לכל שיחה (סיכומים יומיים, עמלות חודשיות, אוטומציות שלא הופעלו על ידי איש קשר, כגון טריגרים של webhook או RSS) אינם חלק מכך. הרצות אוטומציה ושלבי AI שהופעלו על ידי איש קשר נספרים כחלק מהשיחה של אותו איש קשר מאז ה-26 בספטמבר 2026.
• contained: ה-AI השיב ואף אחד מהצוות שלכם לא היה צריך להתערב. handed_off: מישהו שלח הודעה לאחר שה-AI השיב, או שה-AI התריע בפני אדם. no_ai: ה-AI מעולם לא השיב (למשל צ’אטים שהצוות שלכם מטפל בהם כשה-AI מושהה).
• נספרות לכל היותר 20,000 שיחות; sessions_truncated הוא true כאשר הטווח הכיל יותר, לכן צמצמו אותו.
• דורש הרשאת חיוב עבור חברי צוות. אותה עמדת 503/analytics_unavailable כמו בסדרות מדדים.
• לכל איש קשר, אותו פיצול נמצא ב-קבלת עלות איש קשר.

תובנות לוח מחוונים #

מחזיר את מטען לוח המחוונים המלא עבור טווח תאריכים בקריאה אחת: מפת חום של שיעור המענה לפי יום בשבוע ושעה, טבלת מובילי הקמפיין, נפח לפי ערוץ, סכומים מדויקים לפי חיבור, פירוט מדדים יומי (ברמת החשבון, לפי ערוץ ולפי מספר), מקורות אנשי הקשר, זמן תגובה בתיבת הדואר הנכנס ופיד פעילות אחרונה. זהו מטען הדיווח העשיר ביותר ב-API — הוא מפעיל ישירות את לוח המחוונים בתוך האפליקציה.

GET /analytics/dashboard-insights

נקודת קצה זו משתמשת ב-startDate/endDate (לא ב-from/to) מכיוון שהיא חולקת את המימוש שלה עם לוח המחוונים בתוך האפליקציה. הטווח מוגבל ל-92 ימים והוא נחתך, לא נדחה, כאשר הוא רחב יותר.

Null פירושו לא זמין, לא אפס. מספר בלוקים (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) מחושבים ממסד הנתונים של הדיווחים וחוזרים כ-null כאשר הוא אינו יכול לספק תשובה עבור החשבון שלך. אל תציג בלוק null כתרשים ריק.

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

תגובה (מקוצרת — מטען זה גדול; ראה את הפניית ה-API עבור הסכימה המלאה)

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

הערות שדה:

• heatmap.buckets[].weekday — 0 הוא יום ראשון עד 6 הוא יום שבת.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — כל אחד מהם באופן עצמאי null כאשר מסד הנתונים של הדיווחים אינו זמין עבור החשבון שלך; כל שאר הבלוקים עדיין יוחזרו.

תובנות AI ללוח המחוונים #

מחזיר שלוש תובנות קצרות שנכתבו על ידי AI לגבי הודעות החשבון לאורך טווח תאריכים: הצלחה אחת, דבר אחד שכדאי לשים לב אליו, וטיפ אחד — משפטים שניתן להדביק ישירות לתוך דוח במקום מספרים שעדיין צריך לפרש. נוצר מתוך מדדי ההודעות של החשבון בלבד.

GET /analytics/dashboard-ai-insights

נקודת קצה זו היא ברמת החשבון — היא אינה דורשת הגדרת קמפיין או סוכן.

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

תגובה

{
  "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 או endDate יחזיר 400.

ציר זמן של פעילות ישות #

מחזיר את הפעילות של איש קשר, עסקה או משימה בודדים כציר זמן אחד, מהחדש לישן: מה קרה ומתי, כולל הודעות, פגישות, הערות ושינויי סטטוס. השתמש בו כדי לענות על השאלה “מה קרה עם האדם הזה” מבלי לחבר יחד מספר נקודות קצה של רשימות.

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

תגובה

{
  "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 חסר או לא תקין יחזיר 400. ישות שאינה קיימת בחשבונך תחזיר 404, כך שמזהים של חשבונות אחרים נשארים בלתי ניתנים לניחוש.

ספירות אירועים מצטברות (Legacy) #

מחזיר את אותן ספירות אירועים מצטברות כמו סיכום נפח הודעות, אך במבנה camelCase (contactCreated במקום contact_created, byDate במקום by_date) שחלק מהאינטגרציות הישנות נבנו לפיו. העדף את /analytics/summary עבור אינטגרציות חדשות — נקודת קצה זו קיימת רק כדי שלוח המחוונים באפליקציה וה-API יחלקו מימוש אחד.

GET /analytics/aggregate

cURL

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

תגובה

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

ריכוז תתי-חשבונות של סוכנות #

שגיאות ב-Analytics API #

נקודות הקצה של Analytics מחזירות את מעטפת השגיאה הסטנדרטית:

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

בנקודת קצה של ניתוח נתונים, פורמט תאריך לא תקין או חלון מחוץ לטווח יחזיר 400, ו-campaign_id או agent_id לא ידועים יחזירו 404. שליחת גם campaign_id וגם agent_id בנקודת קצה שמקבלת את שניהם היא גם 400 — העבר לכל היותר אחד. נקודות הקצה של דיווח מבוסס PG בלבד (סדרות מדדים, תוצאות שיחה, ריכוז סוכנות) מחזירות 503 עם "error_code": "analytics_unavailable" במקום 200 מלא באפסים כאשר מסד הנתונים של הדיווח אינו יכול להשיב עבור חשבונך — נסה שוב בקרוב. הקודים המשותפים שכל נקודת קצה יכולה להחזיר — 401, 403 (התוכנית שלך אינה כוללת גישת API, או, בריכוז סוכנות, החשבון שלך אינו Agency/Dev), 429 (מגבלת קצב) ו-500 — מפורטים עם הנחיות לניסיון חוזר ב-שגיאות ועימוד.

צעדים הבאים #

• אימות — ארבע הדרכים לאימות בקשה.
• שגיאות ומגבלות קצב — קודי סטטוס והמגבלה של 300 בקשות לדקה.
• API של סוכני בינה מלאכותית — הסוכנים שניתן לסנן לפיהם נתונים אלו.