عرض كافة الأشخاص

محتويات الصفحة

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

    طلب عرض الأشخاص

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

    عنوان URL

    https://{your_subdomain}/api/agent/v1/contacts

    معاملات الاستعلام

    after

    نوعه مصفوفة array، يساعدك على عرض قائمة بالأشخاص الذين تتجاوز أرقامهم التعريفية id حد معين.

    before

    نوعه مصفوفة array، يساعدك على عرض قائمة بالأشخاص الذين تقل أرقامهم التعريفية id عن حد معين.

    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/ مع الاهتمام بفئات الأشخاص التي نوعها 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.

    أمثلة

    سنطبق بعض الأمثلة لعرض الأشخاص ضمن مركز مساعدة له النطاق الفرعي support.example.com


    عرض كافة الأشخاص

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

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

    عرض الأشخاص الذين لهم أرقام تعريفية محددة

    لعرض الأشخاص المسجلين في مركز المساعدة، والذين تتراوح أرقامهم بين 500 و 1000 وإظهار أرقام عناوين بريدهم الإلكتروني والشركات التي ينتمون إليها نكتب الطلب كما يلي:

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

    عرض الأشخاص المؤرشفين

    لعرض الأشخاص المؤرشفين archived فقط في مركز المساعدة نكتب الطلب:

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

    عرض الأشخاص المسندين لوكيل معين

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

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

    عرض الأشخاص التابعين لشركة

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

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

    عرض الأشخاص ضمن فئة

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

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

    عرض أشخاص بأرقام تعريفية معينة

    لعرض الأشخاص الذين يملكون الأرقام التعريفية 1و 2 و 3 نكتب الطلب التالي:

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

    عرض أشخاص تتضمن أسماؤهم كلمة معينة

    لعرض الأشخاص في مركز المساعدة الذين يتضمن اسمهم كلمة test مثلًا نكتب الطلب التالي:

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

    عرض الأشخاص المحظورين

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

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

    عرض الأشخاص المشتركين بوسم معين

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

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

    عرض الأشخاص المحذوفين

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

    curl --header 'Authorization: Bearer your_token' 'https://support.example.com/api/agent/v1/contacts?trashed=1'
    محتويات الصفحة