عرض صناديق البريد

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

عرض صناديق البريد

يمكن الحصول على إعدادات كافة صناديق البريد العائدة لمركز مساعدة معين بإرسال طلب GET إلى نقطة الاتصال inboxes/ كما في المثال التالي الذي يعرض كافة صناديق البريد العائدة لمركز مساعدة تجريبي يدعى "المناسب" له النطاق الفرعي al-munasib.zaetoon.com

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/inboxes'

بعد تنفيذ الطلب ستعيد لك الواجهة البرمجية استجابة تتضمن المعلومات التالية عن كل صندوق بريد:

• الرقم التعريفي id.
• الاسم name.
• الوصف description.
• رابط صندوق البريد slug.
• نص رسالة الرد التلقائي autoresponse_text للصندوق، وفيما إذا كانت ميزة الرد التلقائي مُفَعَّلة على هذا الصندوق أم لا.
• بريد إعادة التوجيه forward_email وهو البريد الأساسي الذي ستُحَوَّل إليه جميع رسائل البريد.
• عناوين البريد الإلكتروني المرتبطة بالصندوق emails.
• حالات المحادثات conversation_statuses (مفتوحة open أو مغلقة closed) التي ستُصَنَّف بناءً عليها كافة المحادثات الواردة لصندوق البريد.
• فرق العمل teams التي لها صلاحيات على صندوق البريد.
• المستخدمون agents الذين لا ينتمون لفرق العمل السابقة لكنهم يملكون صلاحيات على صندوق البريد.
• القيمة sort لكل صندوق بريد، وهي تُحَدِّد ترتيبه التسلسلي ضمن صناديق بريد مركز المساعدة.
• حالة صندوق البريد status أو تصنيفه(افتراضي default أو مزعج spam أو عادي normal).
• نص رسالة التقييم rating_message التي ستظهر للشخص سواء ضمن المحادثة المباشرة أو عبر البريد الإلكتروني لتقييم تجربته مع المركز، مع بيان فيما إذا كانت ميزة طلب التقييم من العميل مُفَعَّلة على هذا الصندوق أم لا.
• وقت وتاريخ إنشاء صندوق البريد created_at.
• وقت وتاريخ آخر تحديث أجري على صندوق البريد updated_at.

يمكنك أيضًا تخصيص طلبك وبالتالي طريقة عرضك لصناديق البريد وعرض الصناديق التي تحقق شروط معينة فقط وذلك باستخدام معاملات الاستعلام Query Parameters التالية:

• after: نوعه مصفوفة array، يُظهِر صناديق البريد المُنشأة بعد تاريخ معين، أو التي يتجاوز رقمها التعريفي id حد معين، أو التي يقع ترتيبها sort بعد حد معين، أو التي تحقق عدة شروط منها معًا، مثل المصفوفة التالية:
• ["after[id]= 1","after[sort]= 1","after[created_at]= datetimezone"]
• before: نوعه مصفوفة array، يُظهِر صناديق البريد المُنشأة قبل تاريخ معين، أو التي يقل رقمها التعريفي عن حد معين، أو التي يقع ترتيبها sort قبل حد معين، أو التي تحقق عدة شروط منها معًا، مثل المصفوفة التالية:

["before[id]= 1","before[sort]= 1","before[created_at]= datetimezone"]

• limit: نوعه عدد صحيح integer، يُحدد عدد صناديق البريد التي ستعيدها الواجهة البرمجية في الاستجابة، وقيمته الافتراضية 6 ما لم نحدد له قيمةً مغايرة.
• query: نوعه سلسلة نصية string، وهو مخصص للبحث في الحقول النصية، مثل: اسم صندوق البريد، أو اسم فريق العمل، أو نص رسالة التقييم أو غيره.
• sort: نوعه سلسلة نصية string، يساعدك على ترتيب عناصر الاستجابة تصاعديًا أو تنازليًا تبعًا لعدة عوامل: تاريخ إنشاء الصندوق، الترتيب الأبجدي لحروف اسمه، عدد المحادثات ضمنه، ترتيبه ضمن قائمة الصناديق، ويقبل إحدى القيم التالية حصرًا:
• • created_at.desc
  • created_at.asc
  • conversations_count.desc
  • conversations_count.asc
  • name.desc
  • name.asc
  • ort.desc
  • sort.asc
• statuses: نوعه مصفوفة array، يسمح لك بجلب صناديق البريد التي تتصف بحالة معينة، ويقبل القيم الثلاث التالية حصرًا: normal, spam, default

يحتوي مركز مساعدة زيتون افتراضيًا على صندوقي بريد: الصندوق الوارد وهو الصندوق الأساسي لاستقبال الرسائل وحالته default والمزعج وحالته spam تحول له كافة الرسائل التي تصنف كمزعجة، وأي صندوق آخر تنشئه لاحقًا ستكون حالته normal.

مثال

يعرض المثال التالي صناديق البريد العائدة لمركز مساعدة "المناسب al-munasib" والمنشأة قبل تاريخ 2024/08/01 مع إظهارها بترتيب تنازلي تبعًا للقيمة sort:

curl --header 'Authorization: Bearer your_token' --globoff 'https://al-munasib.zaetoon.com/api/agent/v1/inboxes?before[created_at]=2024-08-01T00%3A00%3A00&sort=sort.desc'