# تحليلات الوكيل

> اقرأ نشاط وكيلك في مجيب يوماً بيوم عبر GET /v1/agents/{agentId}/analytics، من المحادثات الجديدة والرسائل ومزاج العملاء والمحادثات الغاضبة والإجراءات المكتملة، لتقاريرك الخاصة.

يُعيد `GET /v1/agents/{agentId}/analytics` الأرقام التي تقف خلف صفحة **التحليلات** في لوحة التحكم، صفاً لكل يوم بتوقيت UTC، لتقاريرك أو أدوات ذكاء الأعمال لديك أو ملخص يومي لفريقك: المحادثات الجديدة، والرسائل، ومزاج العملاء كما يقرؤه الذكاء الاصطناعي، والمحادثات التي تحوّلت إلى الغضب، والإجراءات التي أكملها الذكاء الاصطناعي. وهو للقراءة فقط ولا يستهلك رسائل. راجع [التحليلات](/docs/features/analytics) لصفحة لوحة التحكم.

## كيف أحصل على أرقام الأسبوع الماضي؟

```bash
curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/analytics?from=2026-10-01&to=2026-10-07" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

`from` و`to` يومان بتوقيت UTC يُكتبان بصيغة `YYYY-MM-DD`، وكلاهما مشمول. وإن لم ترسل `to` يصل التقرير إلى اليوم. يُعيد استدعاء واحد كل المقاييس لكل يوم مع إجماليات النافذة، فلا تحتاج أبداً إلى استدعاء لكل مقياس، واليوم الذي لا نشاط فيه يعود بأصفار، فلكل يوم في النافذة صفّه. وأطول نافذة يمكنك طلبها، وكل الحقول، في [مرجع جلب تحليلات الوكيل اليومية](../api-reference/get-agent-analytics).

## أسئلة شائعة

### لماذا لا تطابق الأرقام لوحة التحكم؟

نوافذ لوحة التحكم الجاهزة تتقدّم بالساعة، ونطاقها المخصّص يبدأ عند منتصف الليل بالمنطقة الزمنية لمتصفحك، بينما تحسب الواجهة البرمجية أياماً كاملة بتوقيت UTC. اختر الأيام نفسها بتوقيت UTC في الاثنين لتقارن بينهما. و**العملاء المستخلصون** في لوحة التحكم هي `completed_actions` في الواجهة البرمجية، و**الغضب** هي `angry_conversations`.

### لماذا لا يزال صف اليوم يكبر؟

اليوم لم ينتهِ بعد، فتستمر أرقامه في الزيادة حتى منتصف الليل بتوقيت UTC. وللأرقام النهائية، اجعل التقرير ينتهي بالأمس.

### لماذا الأيام الأولى صفر في الرسائل وليست كذلك في المحادثات الجديدة؟

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

### لماذا قفزت المحادثات الجديدة بعد بثّ؟

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

### هل تُحتسب ردود فريقي رسائل؟

لا. الرسائل هي ما يرسله العملاء مع ردود الذكاء الاصطناعي النصية. أما ردود فريقك والمتابعات والملفات التي يرسلها الذكاء الاصطناعي والبث والقوالب وما يُرسل عبر الواجهة البرمجية فلا تُحتسب.

### هل `messages` هو عدد الرسائل الذي تحتسبه باقتي؟

لا. يعدّ `messages` ما يرسله العملاء مع ردود الذكاء الاصطناعي النصية، بينما تحتسب باقتك ردود الذكاء الاصطناعي وإجراءاته، ولا تحتسب أبداً ما يرسله العملاء. وللعدد الذي يستخدمه حد باقتك، راجع [الباقة والاستخدام](./plan-and-usage).

### هل `completed_actions` هو عدد عملائي المحتملين؟

لا. فهو يعدّ كل أداة ذكاء اصطناعي نجحت، مثل حفظ عميل محتمل أو حجز موعد أو إضافة صف إلى جدول أو استدعاء Custom API أو Webhook، مرة واحدة لكل محادثة وأداة. ولعدّ العملاء المحتملين، اعرضهم مع `date_from` و`date_to`؛ راجع [جهات الاتصال والملاحظات والعملاء المحتملون](./contacts-and-leads).

### كيف أحسب نسبة الغضب؟

اقسم `angry_conversations` على `new_conversations`، كما تفعل لوحة التحكم. وهي نسبة تقريبية: فالمحادثة التي تحوّلت إلى الغضب اليوم ربما بدأت في يوم سابق.

### لماذا لا يوجد إجمالي للمزاج؟

متوسط المتوسطات اليومية يزن يوماً هادئاً كما يزن يوماً مزدحماً، لذا تستبعد الإجماليات المزاج. ولكل يوم `average_sentiment` خاص به، وقيمته `null` في اليوم الذي لا قراءة فيه.

### هل أستطيع الحصول على أرقام بالساعة، أو أيام بمنطقتي الزمنية؟

ليس بعد. التقرير بالأيام بتوقيت UTC.

### ما الأخطاء التي يجب أن أعالجها؟

`422 invalid_date_range` حين يسبق `to` تاريخ `from`، أو يكون أحد التاريخين بعد اليوم بتوقيت UTC، أو تكون النافذة أطول من المسموح؛ وتوضّح `message` السبب. و`422 invalid_request_body`، مع `param`، حين لا يُكتب تاريخ بصيغة `YYYY-MM-DD`. راجع [الأخطاء](../errors).

### ما النطاق الذي يحتاجه؟

`analytics:read`، ويحمله كل مفتاح اليوم؛ راجع [التوثيق](../authentication).