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

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

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

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

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

```
https://api.youraiconnector.com/v1
```

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

---

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

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

| פרמטר | תיאור |
|---|---|
| `from` | תחילת הטווח, `YYYY-MM-DD`, כולל. ברירת המחדל היא לפני 30 יום. |
| `to` | סוף הטווח, `YYYY-MM-DD`, כולל. ברירת המחדל היא היום. |

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

### הדגל `truncated`

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

::: note
**הערה:** נתוני עלות ואסימונים כלולים רק עבור קריאות AI המחויבות למפתחות ה-API של הספק שלך. כאשר נתוני העלות מוסתרים עבור החשבון שלך, התגובה מגדירה את `"costs_redacted": true` ושדות העלות מוחזרים כפסים.
:::


---

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

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

`GET /analytics/summary`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `from` | לא | תחילת הטווח, `YYYY-MM-DD`. |
| `to` | לא | סוף הטווח, `YYYY-MM-DD`. |
| `campaign_id` | לא | ספירת אירועים השייכים לקמפיין זה בלבד. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

**תגובה**

```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`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `from` | לא | תחילת הטווח, `YYYY-MM-DD`. |
| `to` | לא | סוף הטווח, `YYYY-MM-DD`. |
| `campaign_id` | לא | כלול רק ניצול המשויך לקמפיין זה. |
| `limit` | לא | גודל דף עבור `records`, 1–100. ברירת המחדל היא 50. |
| `cursor` | לא | העבר את ה-`next_cursor` של הדף הקודם כדי להביא את הדף הבא. |

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

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

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

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

```json
{
  "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` כאשר אין יותר רשומות.

---

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

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

`GET /analytics/ai-cost`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `from` | לא | תחילת הטווח, `YYYY-MM-DD`. |
| `to` | לא | סוף הטווח, `YYYY-MM-DD`. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

**תגובה**

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

| פרמטר | נדרש | תיאור |
|---|---|---|
| `from` | לא | תחילת טווח, `YYYY-MM-DD`. ברירת המחדל היא לפני 30 יום. |
| `to` | לא | סוף טווח, `YYYY-MM-DD`. ברירת המחדל היא היום. |
| `metrics` | לא | רשימה מופרדת בפסיקים מ-`sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. ברירת המחדל היא `sent,replied`. מדד לא ידוע מחזיר `400`. |
| `group_by` | לא | רשימה מופרדת בפסיקים של עד שני ממדים מ-`date`, `campaign`, `channel`, `agent`, `number`. `date` מתקבל אך אין לו השפעה — כל תגובה כבר נושאת את ציר הזמן. השמט עבור סדרה בודדת ברמת החשבון. |
| `granularity` | לא | `day` (ברירת מחדל), `week`, או `month`. דלי שבוע מתחילים ביום שני, דלי חודש ב-1 לחודש. |
| `limit` | לא | כמה סדרות להחזיר לפני שהשאר מתכנסים ל-`other_bucket`, 1–50. ברירת המחדל היא 12. |
| `campaign_id` | לא | ספור רק פעילות השייכת לקמפיין זה. מיושן; העדף את `agent_id`. |
| `agent_id` | לא | ספור רק פעילות השייכת לסוכן AI זה. |
| `channel` | לא | ספור רק פעילות בערוץ זה, לדוגמה `whatsapp`. |

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

**cURL**

```bash
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**

```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**

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

**תגובה**

```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 הקצה, בתוספת סכומי טווח עבור תשובות, קביעות, העברות לאדם, ושיחות שה-AI מעולם לא סיווג.

`GET /analytics/outcomes`

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

| פרמטר | נדרש | תיאור |
|---|---|---|
| `from` | לא | תחילת טווח, `YYYY-MM-DD`. ברירת המחדל היא לפני 30 יום. |
| `to` | לא | סוף טווח, `YYYY-MM-DD`. ברירת המחדל היא היום. |
| `campaign_id` | לא | ספירת שיחות רק עם אנשי קשר הנמצאים כעת בקמפיין זה. מיושן; עדיף להשתמש ב-`agent_id`. |
| `agent_id` | לא | ספירת תוצאות השייכות לסוכן AI זה בלבד. |
| `group_by` | לא | `date` (ברירת מחדל) שומר על ספירות יומיות; `tag` מאחד לסיכומי טווח. |

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

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

**תגובה**

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

**הערות שדה:**

- `by_tag[].tag` — `null` עבור שיחות שה-AI מעולם לא הקצה להן תגית תוצאה.
- `totals.human_alerted` — שיחות שהועברו לאדם; זה נכתב בכל העברה ולא הוצג בעבר על ידי אף נקודת קצה.
- אותה התנהגות `503`/`analytics_unavailable` כמו בסדרות מדדים כאשר מסד הנתונים של הדיווחים אינו יכול לספק תשובה.

---

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

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

`GET /analytics/dashboard-insights`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `startDate` | כן | תחילת טווח, `YYYY-MM-DD`. |
| `endDate` | כן | סוף טווח, `YYYY-MM-DD`. |
| `campaignId` | לא | כלול רק פעילות השייכת לקמפיין זה (`campaign_id` מתקבל גם כן). מיושן; עדיף להשתמש ב-`agent_id`. |
| `agent_id` | לא | כלול רק פעילות השייכת לסוכן AI זה (`agentId` מתקבל גם כן). תחת היקף של סוכן, טבלת מובילי הקמפיין נבנית מפעילותו של אותו סוכן בלבד. |

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

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

**cURL**

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

**JavaScript**

```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**

```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](reference.md) עבור הסכימה המלאה)

```json
{
  "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`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `startDate` | כן | תחילת טווח, `YYYY-MM-DD`. |
| `endDate` | כן | סוף טווח, `YYYY-MM-DD`. |

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

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

**תגובה**

```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`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `entityType` | כן | `contact`, `deal`, או `task`. |
| `entityId` | כן | מזהה הרשומה שעבורה יש להחזיר את ציר הזמן. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

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

**תגובה**

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

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

`GET /analytics/aggregate`

| פרמטר | נדרש | תיאור |
|---|---|---|
| `startDate` | לא | תחילת טווח, תאריך או תאריך-שעה בפורמט ISO. כברירת מחדל משתמש באותו חלון ש-`/analytics/summary` משתמש בו. |
| `endDate` | לא | סוף טווח, תאריך או תאריך-שעה בפורמט ISO. |
| `campaignId` | לא | ספור רק אירועים השייכים לקמפיין זה (`campaign_id` מתקבל גם כן). Legacy; העדף את `agent_id`. |
| `agent_id` | לא | ספור רק אירועים השייכים לסוכן AI זה (`agentId` מתקבל גם כן). |

**cURL**

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

**תגובה**

```json
{
  "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 מחזירות את מעטפת השגיאה הסטנדרטית:

```json
{
  "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` — מפורטים עם הנחיות לניסיון חוזר ב-[שגיאות ועימוד](errors-and-pagination.md).

---

## צעדים הבאים

- [אימות](authentication.md) — ארבע הדרכים לאימות בקשה.
- [שגיאות ומגבלות קצב](errors-and-pagination.md) — קודי סטטוס והמגבלה של 300 בקשות לדקה.
- [API של קמפיינים](campaigns.md) — הקמפיינים שניתן לסנן לפיהם את הנתונים האלה.