إنتقل إلى المحتوى الرئيسي

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

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

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

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 يصل التقرير إلى اليوم. يُعيد استدعاء واحد كل المقاييس لكل يوم مع إجماليات النافذة، فلا تحتاج أبداً إلى استدعاء لكل مقياس، واليوم الذي لا نشاط فيه يعود بأصفار، فلكل يوم في النافذة صفّه. وأطول نافذة يمكنك طلبها، وكل الحقول، في مرجع جلب تحليلات الوكيل اليومية.

أسئلة شائعة​

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

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

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

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

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

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

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

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

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

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

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

لا. يعدّ messages ما يرسله العملاء مع ردود الذكاء الاصطناعي النصية، بينما تحتسب باقتك ردود الذكاء الاصطناعي وإجراءاته، ولا تحتسب أبداً ما يرسله العملاء. وللعدد الذي يستخدمه حد باقتك، راجع الباقة والاستخدام.

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

لا. فهو يعدّ كل أداة ذكاء اصطناعي نجحت، مثل حفظ عميل محتمل أو حجز موعد أو إضافة صف إلى جدول أو استدعاء Custom API أو Webhook، مرة واحدة لكل محادثة وأداة. ولعدّ العملاء المحتملين، اعرضهم مع date_from وdate_to؛ راجع جهات الاتصال والملاحظات والعملاء المحتملون.

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

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

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

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

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

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

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

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

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

analytics:read، ويحمله كل مفتاح اليوم؛ راجع التوثيق.