واجهة برمجة تطبيقات التحليلات والتقارير

تتيح لك نقاط النهاية للقراءة فقط هذه سحب نشاط حسابك إلى لوحات المعلومات والتقارير الخاصة بك: عدد أحداث الرسائل، واستهلاك الرصيد، وإنفاق الذكاء الاصطناعي، ونفس المخططات والرؤى التي تعرضها لوحة معلومات التطبيق. يتناول هذا الدليل:

الملخص — عدادات حجم الرسائل (المرسلة، والمُسلمة، والمقروءة، والمُرد عليها، والمحجوزة، وجهات الاتصال التي تم إنشاؤها، والأرصدة).
الأرصدة — سجل مفصل ومقسم إلى صفحات لاستخدام الرصيد مع الإجماليات والتفاصيل.
تكلفة الذكاء الاصطناعي — ملخص يومي لإنفاق الذكاء الاصطناعي.
سلسلة المقاييس — سلسلة زمنية جاهزة للمخططات لمقياس واحد أو أكثر، مجمعة حسب الحملة، أو القناة، أو وكيل الذكاء الاصطناعي، أو الرقم.
نتائج المحادثة — كيف انتهت المحادثات، حسب علامة النتيجة التي يعينها الذكاء الاصطناعي.
رؤى لوحة المعلومات و رؤى الذكاء الاصطناعي للوحة المعلومات — البيانات الكاملة خلف لوحة معلومات التطبيق، بما في ذلك الملخصات التي كتبها الذكاء الاصطناعي.
نشاط الكيان — الجدول الزمني لجهة اتصال واحدة، أو صفقة، أو مهمة.
عدد الأحداث المجمعة — نموذج قديم بصيغة camelCase للملخص تم الاحتفاظ به لعمليات التكامل الحالية.

تحتاج كل نقطة نهاية في هذه الصفحة إلى نطاق دقيق، وليس كلاهما: مرر نطاقاً واحداً على الأكثر من campaign_id (قديم) أو agent_id حيث تقبل نقطة النهاية ذلك. إرسال كليهما يعيد 400، ومعرف غير موجود في حسابك يعيد 404 بدلاً من 403، بحيث تظل معرفات الحسابات الأخرى غير قابلة للتخمين.

جميع المسارات أدناه نسبية إلى عنوان URL الأساسي لواجهة برمجة التطبيقات:

https://api.youraiconnector.com/v1

يجب مصادقة كل طلب. راجع المصادقة لمعرفة الطرق الأربع المقبولة. تستخدم الأمثلة هنا رأس X-API-Key (ونموذج معلمة استعلام واحد لـ cURL).

نطاق التاريخ

تقبل نقاط النهاية الثلاث جميعها نفس عوامل تصفية التاريخ الاختيارية:

المعلمة	الوصف
`from`	بداية النطاق، `YYYY-MM-DD`، شامل. القيمة الافتراضية هي قبل 30 يوماً.
`to`	نهاية النطاق، `YYYY-MM-DD`، شامل. القيمة الافتراضية هي اليوم.

يتم تفسير التواريخ بتوقيت UTC. النطاق الافتراضي هو آخر 30 يوماً ومحدد بـ 366 يوماً — النطاق الأوسع يعيد 400. يجب ألا يكون from بعد to.

علامة `truncated`

تحدد نقاط النهاية الملخص و الأرصدة عدد السجلات التي يقوم الطلب الواحد بمسحها. إذا كان نطاقك مشغولاً بما يكفي للوصول إلى هذا الحد، فإن الاستجابة تتضمن "truncated": true. عندما تراه، تكون الأرقام مبنية على مسح جزئي — قم بتضييق نطاق التاريخ (أو التنقل عبر الصفحات بنافذة أصغر) للحصول على أرقام كاملة.

ملاحظة: يتم تضمين أرقام التكلفة والرموز فقط لطلبات الذكاء الاصطناعي التي تتم محاسبتها على مفاتيح واجهة برمجة تطبيقات (API) الخاصة بمزودك. عندما تكون أرقام التكلفة مخفية لحسابك، تقوم الاستجابة بتعيين "costs_redacted": true وتتم إعادة حقول التكلفة كأصفار.

ملخص حجم الرسائل

يعيد عدادات أحداث الرسائل المجمعة لحسابك، كإجماليات للنطاق وكسلسلة يومية. يظهر كل يوم في النطاق في by_date — الأيام الهادئة يتم ملؤها بأصفار. يمكنك التصفية اختيارياً لحملة واحدة باستخدام campaign_id.

GET /analytics/summary

المعلمة	مطلوبة	الوصف
`from`	لا	بداية النطاق، `YYYY-MM-DD`.
`to`	لا	نهاية النطاق، `YYYY-MM-DD`.
`campaign_id`	لا	احتساب الأحداث التي تنتمي إلى هذه الحملة فقط.

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

المعلمة	مطلوبة	الوصف
`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

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 عندما لا توجد سجلات أخرى.

تجميع تكاليف الذكاء الاصطناعي

يعيد تجميع إنفاق الذكاء الاصطناعي اليومي لحسابك. يقرأ هذا التقرير الإجماليات اليومية المجمعة مسبقاً، لذا فهو سريع حتى عبر النطاقات الطويلة. يظهر كل يوم في النطاق في days — الأيام الهادئة يتم ملؤها بأصفار.

GET /analytics/ai-cost

المعلمة	مطلوبة	الوصف
`from`	لا	بداية النطاق، `YYYY-MM-DD`.
`to`	لا	نهاية النطاق، `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()

الاستجابة

{
  "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 — الإنفاق بالدولار الأمريكي مصنفاً حسب اسم مزود الذكاء الاصطناعي.
يتم إرجاع أرقام الدولار الأمريكي فقط للحسابات التي تستخدم مفتاح المزود الخاص بها. بالنسبة للحسابات التي تدفع بالرصيد، يكون كل حقل دولار أمريكي صفراً ويكون 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`. تبدأ دلاء الأسبوع يوم الاثنين، ودلاء الشهر في اليوم الأول.
`limit`	لا	عدد السلاسل التي يجب إرجاعها قبل أن تنهار البقية في `other_bucket`، من 1 إلى 50. الافتراضي هو 12.
`campaign_id`	لا	احتساب النشاط الذي ينتمي لهذه الحملة فقط. قديم؛ يفضل استخدام `agent_id`.
`agent_id`	لا	احتساب النشاط الذي ينتمي لوكيل الذكاء الاصطناعي هذا فقط.
`channel`	لا	احتساب النشاط على هذه القناة فقط، على سبيل المثال `whatsapp`.

نطاق التاريخ لنقطة النهاية هذه محدود بـ 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 مليئة بالأصفار — المخطط المليء بالأصفار سيُقرأ كحقيقة.

نتائج المحادثة

يعيد كيف انتهت المحادثات عبر نطاق تاريخي: عدد يومي لكل علامة نتيجة عينها الذكاء الاصطناعي، بالإضافة إلى إجماليات النطاق للردود، والحجوزات، وعمليات التسليم إلى بشري، والمحادثات التي لم يصنفها الذكاء الاصطناعي أبداً.

GET /analytics/outcomes

مرر group_by=tag لطي محور الوقت والحصول على إجماليات النطاق لكل علامة فقط — في هذا الوضع تكون labels فارغة وتكون مصفوفة counts لكل علامة فارغة، بينما تظل total مأهولة.

المعلمة	مطلوبة	الوصف
`from`	لا	بداية النطاق، `YYYY-MM-DD`. القيمة الافتراضية هي قبل 30 يوماً.
`to`	لا	نهاية النطاق، `YYYY-MM-DD`. القيمة الافتراضية هي اليوم.
`campaign_id`	لا	احتساب المحادثات مع جهات الاتصال الموجودة حالياً في هذه الحملة فقط. قديم؛ يُفضل استخدام `agent_id`.
`agent_id`	لا	احتساب النتائج التي تنتمي إلى وكيل الذكاء الاصطناعي هذا فقط.
`group_by`	لا	`date` (افتراضي) يحتفظ بالعدد اليومي؛ `tag` يدمج النتائج في إجمالي النطاق.

نطاق التاريخ لهذا الطرف (endpoint) محدود بـ 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": "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 للمحادثات التي لم يقم الذكاء الاصطناعي بتعيين وسم نتيجة لها.
totals.human_alerted — المحادثات التي تم تحويلها إلى بشري؛ يتم كتابة هذا في كل عملية تحويل ولم يكن متاحاً سابقاً عبر أي طرف (endpoint).
نفس وضع 503/analytics_unavailable مثل سلسلة المقاييس عندما لا تستطيع قاعدة بيانات التقارير الإجابة.

رؤى لوحة التحكم

يعيد حمولة لوحة التحكم الكاملة لنطاق تاريخي في طلب واحد: خريطة حرارية لمعدل الرد حسب يوم الأسبوع والساعة، ولوحة صدارة الحملات، وحجم الرسائل لكل قناة، وإجمالي الاتصالات الدقيق، وتفاصيل المقاييس اليومية (على مستوى الحساب، لكل قناة، ولكل رقم)، ومصادر جهات الاتصال، ووقت الاستجابة في صندوق الوارد، وخلاصة النشاط الأخير. هذه هي أغنى حمولة تقارير في واجهة برمجة التطبيقات (API) — وهي التي تشغل لوحة التحكم داخل التطبيق مباشرة.

GET /analytics/dashboard-insights

المعلمة	مطلوبة	الوصف
`startDate`	نعم	بداية النطاق، `YYYY-MM-DD`.
`endDate`	نعم	نهاية النطاق، `YYYY-MM-DD`.
`campaignId`	لا	تضمين النشاط الذي ينتمي إلى هذه الحملة فقط (يُقبل أيضاً `campaign_id`). قديم؛ يُفضل استخدام `agent_id`.
`agent_id`	لا	تضمين النشاط الذي ينتمي إلى وكيل الذكاء الاصطناعي هذا فقط (يُقبل أيضاً `agentId`). تحت نطاق الوكيل، يتم بناء لوحة صدارة الحملات من نشاط ذلك الوكيل فقط.

يستخدم هذا الطرف (endpoint) startDate/endDate (وليس from/to) لأنه يتشارك في تنفيذه مع لوحة التحكم داخل التطبيق. النطاق محدود بـ 92 يوماً ويتم تقييده (clamped) وليس رفضه عندما يكون أوسع من ذلك.

تعني القيمة 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()

الاستجابة (مختصرة — هذه الحمولة كبيرة؛ راجع مرجع واجهة برمجة التطبيقات للحصول على المخطط الكامل)

{
  "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 بشكل مستقل عندما تكون قاعدة بيانات التقارير غير متاحة لحسابك؛ كل كتلة أخرى لا تزال تعيد بيانات.

رؤى الذكاء الاصطناعي للوحة التحكم

يعيد ثلاث رؤى قصيرة مكتوبة بواسطة الذكاء الاصطناعي حول مراسلات الحساب خلال نطاق تاريخي: إنجاز واحد، شيء يستحق المراقبة، ونصيحة واحدة — جمل يمكنك لصقها مباشرة في تقرير بدلاً من أرقام لا تزال بحاجة إلى تفسير. يتم إنشاؤها من مقاييس رسائل الحساب الخاصة فقط.

GET /analytics/dashboard-ai-insights

المعلمة	مطلوبة	الوصف
`startDate`	نعم	بداية النطاق، `YYYY-MM-DD`.
`endDate`	نعم	نهاية النطاق، `YYYY-MM-DD`.

نقطة النهاية هذه على مستوى الحساب بالكامل — فهي لا تأخذ نطاق حملة أو وكيل.

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

المعلمة	مطلوبة	الوصف
`entityType`	نعم	`contact` أو `deal` أو `task`.
`entityId`	نعم	معرف السجل الذي تريد إرجاع جدوله الزمني.

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، بحيث تظل معرفات الحسابات الأخرى غير قابلة للتخمين.

إجمالي عدد الأحداث (قديم)

يُرجع نفس إجمالي عدد الأحداث مثل ملخص حجم الرسائل، ولكن بتنسيق camelCase (مثل contactCreated بدلاً من contact_created، وbyDate بدلاً من by_date) الذي بُنيت عليه بعض عمليات التكامل القديمة. يُفضل استخدام /analytics/summary لعمليات التكامل الجديدة — توجد نقطة النهاية هذه فقط لكي تتشارك لوحة تحكم التطبيق وواجهة برمجة التطبيقات في تنفيذ واحد.

GET /analytics/aggregate

المعلمة	مطلوبة	الوصف
`startDate`	لا	بداية النطاق، تاريخ أو تاريخ ووقت بتنسيق ISO. يتم تعيينه افتراضياً على نفس النافذة التي يستخدمها `/analytics/summary`.
`endDate`	لا	نهاية النطاق، تاريخ أو تاريخ ووقت بتنسيق ISO.
`campaignId`	لا	عد الأحداث التي تنتمي لهذه الحملة فقط (يُقبل أيضاً `campaign_id`). قديم؛ يُفضل استخدام `agent_id`.
`agent_id`	لا	عد الأحداث التي تنتمي لهذا الوكيل الذكي (AI Agent) فقط (يُقبل أيضاً `agentId`).

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

تجميع الحسابات الفرعية للوكالة

أخطاء واجهة برمجة تطبيقات التحليلات

تُرجع نقاط نهاية التحليلات غلاف الخطأ القياسي:

{
  "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 (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات، أو في حالة تجميع الوكالة، حسابك ليس وكالة/مطور)، 429 (حد المعدل) و500 — مدرجة مع إرشادات إعادة المحاولة في الأخطاء والترقيم.

الخطوات التالية

المصادقة — الطرق الأربع لمصادقة الطلب.
الأخطاء وحدود المعدل — رموز الحالة وحد 300 طلب/دقيقة.
واجهة برمجة تطبيقات الحملات — الحملات التي يمكن تصفية هذه الأرقام بناءً عليها.

واجهة برمجة تطبيقات التحليلات والتقارير #

نطاق التاريخ #

علامة truncated #

ملخص حجم الرسائل #

استخدام الرصيد #

تجميع تكاليف الذكاء الاصطناعي #

سلسلة المقاييس #

نتائج المحادثة #

رؤى لوحة التحكم #

رؤى الذكاء الاصطناعي للوحة التحكم #

الجدول الزمني لنشاط الكيان #

إجمالي عدد الأحداث (قديم) #

تجميع الحسابات الفرعية للوكالة #

أخطاء واجهة برمجة تطبيقات التحليلات #

الخطوات التالية #

واجهة برمجة تطبيقات التحليلات والتقارير

نطاق التاريخ

علامة `truncated`

ملخص حجم الرسائل

استخدام الرصيد

تجميع تكاليف الذكاء الاصطناعي

سلسلة المقاييس

نتائج المحادثة

رؤى لوحة التحكم

رؤى الذكاء الاصطناعي للوحة التحكم

الجدول الزمني لنشاط الكيان

إجمالي عدد الأحداث (قديم)

تجميع الحسابات الفرعية للوكالة

أخطاء واجهة برمجة تطبيقات التحليلات

الخطوات التالية