عرض الأشخاص المسجلين

نشرح في هذا المقال طريقة الحصول على كافة الأشخاص أو جهات الاتصال في مركز المساعدة من خلال الواجهة البرمجية لزيتون، ونطبق الشرح على مركز مساعدة تجريبي يدعى "المناسب al-munasib" له النطاق الفرعي al-munasib.zaetoon.com.

عرض الأشخاص المسجلين

يمكنك الحصول على قائمة بجهات الاتصال وتحديدًا الأشخاص المسجلة بياناتهم في مركز المساعدة بإرسال طلب من نوع GET إلى نقطة الاتصال contacts/ مع العديد من خيارات الفرز والتصفية التي تساعدك على الوصول إلى الشخص أو الأشخاص المطلوبين كما يلي:

• عنوان URL لنقطة الاتصال:
  https://{your_subdomain}/api/agent/v1/contacts.
• نوع الطلب: GET.
• معاملات الاستعلام Query Parameters: وهي كالتالي:
• • after: نوعه مصفوفة array، يساعدك على عرض قائمة بالأشخاص الذين تتجاوز أرقامهم التعريفية id حد معين، كما في المثال التالي:
    ["after[id] = 100"]
  • before: نوعه مصفوفة array، يساعدك على عرض قائمة بالأشخاص الذين تقل أرقامهم التعريفية id عن حد معين، كما في المثال التالي:
    ["before[id] = 100"]
  • archived:نوعه معامل منطقي boolean، يساعدك على عرض الأشخاص المؤرشفين. فإذا أعطيته القيمة "1" ستظهر في الاستجابة بيانات الأشخاص المؤرشفين فقط، أما عند إعطائه القيمة "0" ستظهر بيانات جميع الأشخاص المسجلين في مركز المساعدة ما عدا الأشخاص المؤرشفين.
  • company_ids: نوعه مصفوفة أعداد صحيحة array، يساعدك على عرض الأشخاص المنتمين إلى شركات معينة، إذ تُمَرِّر ضمنه الأرقام التعريفية للشركات.
  • assign_to: نوعه مصفوفة أعداد صحيحة array، يستخدم لعرض الأشخاص المُسنَدَين إلى مستخدمين (أو موظفي دعم) معينين في مركز المساعدة، إذ تُمَرِّر ضمنه الأرقام التعريفية للمستخدمين.
  • contact_ids: نوعه مصفوفة أعداد صحيحة array، يستخدم لعرض مجموعة مُحَدَّدة من الأشخاص بتمرير أرقامهم التعريفية.
  • expand:نوعه مصفوفة array، يفيدك إذا رغبت بعرض معلومات تفصيلية عن جوانب محددة من إعدادات الأشخاص مثلًا: عناوين البريد الإلكتروني أو أرقام الهواتف المرتبطة بكل شخص أو غير ذلك، ويأخذ حصرًا واحدة أو أكثر من القيم التالية:
  • • emails لإظهار عناوين البريد الإلكتروني للأشخاص.
    • tags لعرض وسوم الأشخاص.
    • urls لإظهار عناوين URL لمواقع الويب الخاصة بالأشخاص.
    • numbers لعرض أرقام هواتف الأشخاص.
    • segments لعرض الفئات التي ينتمي إليها كل شخص.
    • assigned_agent لإظهار المستخدمين المُسند إليهم كل شخص.
    • companies لعرض الشركة التي ينتمي إليها كل شخص.
  • has_email: نوعه معامل منطقي boolean، يساعدك على عرض الأشخاص المسجلة عناوين بريدهم الإلكتروني في مركز المساعدة.
  • فإذا أعطيته القيمة "1" سيظهر في الاستجابة الأشخاص المسجل عنوان بريدهم الإلكتروني فقط، أما عند إعطائه القيمة "0" ستظهر بيانات كافة الأشخاص المحفوظين في المركز سواء كانت مسجلة عناوين بريدهم الإلكتروني أم لا.
  • limit: نوعه عدد صحيح integer، يساعدك على التحكم بعدد الأشخاص المعروضين في الاستجابة، قيمته الافتراضية 6 ويمكنك إعطائه أي قيمة تريدها من 1 إلى 100.
  • query: نوعه سلسلة نصية string، يفيدك في عمليات البحث ضمن الحقول النصية المختلفة، مثل: اسم الشخص الأول أو اسم عائلته.
  • segment_ids: نوعه مصفوفة array، يساعدك على عرض الأشخاص المنتمين إلى فئات معينة فقط بناءً على الرقم التعريفي للفئة (الذي يمكنك معرفته بإرسال طلب GET إلى نقطة الاتصال segments/ مع الاهتمام بالفئات الخاصة بالأشخاص أي ذات النوع types=contact).
  • sort: نوعه سلسلة نصية string، يفيدك في ترتيب عناصر الاستجابة حسب قيمة sort تبعًا للعوامل التالية:
  • • تاريخ إضافة الشخص إلى مركز المساعدة: من أقدم شخص إلى أحدث شخص أو العكس بإعطاء sort القيمة created_at.asc أو created_at.desc.
    • عدد محادثات الشخص مع مركز المساعدة: من الأقل إلى الأكثر أو العكس باستخدام conversations_count.asc أو conversations_count.desc.
    • عدد عناوين البريد الإلكتروني للشخص: من الأقل إلى الأكثر أو العكس بواسطة emails_count.asc أو emails_count.desc.
    • الترتيب الأبجدي لاسم الشخص: من الأول أبجديًّا إلى الأخير أو العكس باستخدام first_name.asc أو first_name.desc.
    • الترتيب الأبجدي لاسم عائلة الشخص: من الأول أبجديًّا إلى الأخير أو العكس باستخدام last_name_at.asc أو last_name_at.desc.
    • وقت وتاريخ آخر تواجد للشخص في مركز المساعدة: من الأقدم تواجدًا في مركز المساعدة إلى الأحدث أو العكس بواسطة last_seen_at.desc أو last_seen_at.asc.
  • status: نوعه سلسلة نصية string، يستخدم لعرض الأشخاص الذين يتصفون بحالة معينة فقط من الحالات التالية:
  • • active فعّال.
    • banned محظور.
    • deleted محذوف.
  • tags: نوعه مصفوفة array، يساعدك على عرض الأشخاص الذين يتصفون بوسوم معينة، إذا تُكتب أسماء الوسوم ضمن هذه المصفوفة.
  • trashed:نوعه معامل منطقي boolean، يساعدك على عرض الأشخاص الذين سبق لك حذفهم من مركز المساعدة باستخدام نقطة الاتصال {contacts/{id/ وذلك بإعطائه القيمة "1".

أمثلة

سنطبق بعض الأمثلة على مركز المساعدة التجريبي "المناسب"

مثال1: عرض كافة الأشخاص المسجلين في مركز المساعدة من دون أي شرط:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?limit=100' 

مثال2: عرض الأشخاص الذين تتراوح أرقامهم التعريفية بين "500" و "1000" وعرض معلومات تفصيلية عن أرقام عناوين بريدهم الإلكتروني والشركات التي ينتمون إليها:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?after[id]=500&before[id]=1000&limit=25&expand[]=emails&expand[]=companies'

مثال3: عرض الأشخاص المؤرشفين في مركز المساعدة:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?archived=1'

مثال4: عرض الأشخاص المسندين إلى مستخدم معين ليكن ذو الرقم "1434" مثلًا:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?assign_to=1434'

مثال5: عرض الأشخاص التابعين لشركة معينة لتكن الشركة رقم "250" مثلًا:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?company_ids[]=250'

مثال6: عرض الأشخاص المسجلة عناوين بريدهم الإلكتروني في مركز المساعدة دون بقية المستخدمين:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?has_email=1'

مثال7: عرض الأشخاص ضمن فئة معينة ولتكن فئة "العملاء المحتملين" ذات الرقم التعريفي "2097" وترتيب النتائج حسب الأشخاص الأحدث تواجدًا في مركز المساعدة:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?limit=25&sort=last_seen_at.desc&segment_ids[]=2097'

مثال8: عرض مجموعة أشخاص ذوي أرقام تعريفية معينة:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?contact_ids[]=1&contact_ids[]=2&contact_ids[]=3' 

مثال9: عرض الأشخاص الذين تتضمن أسماؤهم كلمة "test" مثلًا:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?query=test'

مثال10: عرض الأشخاص المحظورين "banned" في مركز المساعدة:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?status=banned'

مثال11: عرض الأشخاص المشتركين بوسم معين وليكن "new" مثلًا، وترتيبهم حسب تواريخ إضافتهم إلى مركز المساعدة من الأقدم إلى الأحدث:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?tags[]=new&sort=created_at.asc'

مثال12: عرض الأشخاص المحذوفين trashed في مركز المساعدة:

curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts?trashed=1'