التعامل مع الأشخاص

نشرح في هذا المقال كيفية عرض وإضافة وتعديل الأشخاص المسجلين في مركز المساعدة من خلال الواجهة البرمجية لزيتون من خلال أمثلة متنوعة. لتطبيق الأمثلة، سنفترض وجود مركز مساعدة على النطاق example.com، وتوفر مفتاح الواجهة البرمجية لزيتون مخزن ضمن المتغير TOKEN$ لاستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY"

عرض الأشخاص

لعرض شخص محدد مسجل في مركز المساعدة، نرسل طلب GET لنقطة الوصول Retrieve a contact مع تمرير الرقم التعريفي للشخص ضمن عنوان الطلب.

ولعرض كافة الأشخاص المسجلين، نرسل طلب GET لنقطة الوصول List all contacts ويمكننا من خلال هذه النقطة فرز وتصفية الأشخاص المعروضين.

كافة الأشخاص

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

curl "https://example.com/api/agent/v1/contacts" \
  -H "Authorization: Bearer @TOKEN"

شخص واحد

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

curl "https://example.com/api/agent/v1/contacts/1001" \
  -H "Authorization: Bearer @TOKEN"

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

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

curl "https://example.com/api/agent/v1/contacts?archived=1" \
  -H "Authorization: Bearer @TOKEN"

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

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

curl "https://example.com/api/agent/v1/contacts?trashed=1" \
  -H "Authorization: Bearer @TOKEN"

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

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

curl "https://example.com/api/agent/v1/contacts?assign_to=1008" \
  -H "Authorization: Bearer @TOKEN"

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

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

curl "https://example.com/api/agent/v1/contacts?company_ids[]=1002" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

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

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

curl "https://example.com/api/agent/v1/contacts?limit=25&sort=last_seen_at.desc&segment_ids[]=800" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

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

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

curl "https://example.com/api/agent/v1/contacts?status=banned" \
  -H "Authorization: Bearer @TOKEN"

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

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

curl "https://example.com/api/agent/v1/contacts?tags[]=مميز&sort=created_at.asc" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

إضافة أشخاص

لإضافة شخص جديد إلى جهات اتصال مركز المساعدة، نرسل طلب من نوع POST إلى نقطة الوصول Create a contact مع تمرير بيانات الشخص في جسم الطلب مثل الاسم والكنية والصورة المصغرة واسم الشركة، كما يمكن تمرير قيم حقول مخصصة لتعريف الأشخاص عبر إرسال طلب GET لنقطة الوصول Show custom field.
تختلف قيمة الحقل المخصص حسب نوعه، فيمكن أن يكون الحقل المخصص سلسلة نصية كما في المثال التالي:

"custom_fields": {
           "field_33525": "عنوان الشخص"
     }

ويمكن أن يكون ملف، عندها نمرره صيغة base64 لكل ملف مرفق كما يلي:

"custom_fields": {
           "field_33525":{
                "files": ["file1 as base64", "file2 as base64"]
             }
     }

أو نمرر الأرقام التعريفية لكل ملف مُحَمَّل مسبقًا بواسطة نقطة الوصول Upload files أو Upload an image كما في المثال التالي:

"custom_fields": {
           "field_33525":{
                 "ids": [13, 113, 1013]
             }
     }

وإذا كان الحقل المخصص من صندوق اختيار يتضمن عدة خيارات، نمرر مصفوفة بأرقام الخيارات المطلوبة وفق التالي:

"custom_fields": {
           "field_35413": [1, 2, 3]
     }

شخص واحد

لإضافة بيانات شخص جديد لمركز المساعدة باللغة العربية، وضمّه للشركة رقم 1002، وإسناده للوكيل رقم 1008 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Saleh",
    "last_name": "Amin",
    "avatar": "contact_avatar_in_base64",
    "status": "active",
    "locale": "ar",
    "custom_fields": {
        "field_34424": "client_national_id"
    },
    "company_id": "1002",
    "assign_to": "1008"
}'

إضافة حقول مخصصة للأشخاص

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

حقل واحد

لإضافة رابط LinkedIn لبيانات الشخص رقم 1001 في مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001/fields" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "linkedin",
    "value": "https://www.linkedin.com/exampel/",
    "type": "url"
  }'

إضافة فئات للأشخاص

يوفر مركز مساعدة زيتون فئتين معرفتين افتراضيًّا هما فئة العملاء، وفئة العملاء المحتملين، ويمكن إنشاء فئات جديدة من خلال نقطة الوصول Create Segment وإضافة الأشخاص لهذه الفئة من خلال إرسال طلب POST لنقطة الوصول Add a segment مع تمرير رقم الشخص في عنوان الطلب، ورقم الفئة في جسم الطلب.

فئة واحدة

لإضافة الشخص رقم 1001 إلى الفئة رقم 800 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001/segments" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": 800
  }'

تعديل الأشخاص

لتعديل البيانات الأساسية لشخص كالاسم، والصورة الشخصية، والحالة، والشركة التي ينتمي إليها، والوكيل المُسنَد إليه نرسل الطلب PUT إلى نقطة الاتصال Update a Contact مع تمرير الرقم التعريفي لهذا الشخص في عنوان الطلب، والبيانات المطلوب تعديلها في جسم الطلب.

ولتعديل إعدادات مجموعة أشخاص معًا نرسل طلب PUT لنقطة الوصول Mass Update contacts مع تمرير أرقامهم كمصفوفة في جسم الطلب.

شخص واحد

لتعديل اسم الشخص رقم 1001 وإضافته إلى الشركة رقم 1002، وإضافة رقمه الوطني كحقل مخصص نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Saleh",
    "last_name": "Amin",
    "custom_fields": {
      "field_34424": "50000"
    },
    "company_id": 1002
  }'

عدة أشخاص

لتعديل الأشخاص ذوي الأرقام 1 و 101 و 1001وإضافة الوسم "جديد" لهم وحذف الوسم "اختبار" منهم، وتعديل حالتهم لتصبح active، وإضافتهم للشركة رقم 1002 نكتب الطلب التالي

curl "https://example.com/api/agent/v1/contacts" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [1, 101, 1001],
    "added_tags": ["جديد"],
    "deleted_tags": ["اختبار"],
    "status": "active",
    "company_id": 1002
  }'

دمج الأشخاص

يمكن دمج بيانات عدة أشخاص في بيانات شخص واحد، بإرسال طلب POST لنقطة الوصول Merge وتمرير الرقم التعريفي للشخص الناتج في عنوان الطلب، وأرقام الأشخاص المطلوب دمجهم معه في جسم الطلب.

عدة أشخاص

لدمج الأشخاص رقم 1 و 101 مع الشخص رقم 1001 نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001/merge" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [1, 101]
  }'

أرشفة الأشخاص

يمكننا أرشفة شخص لإخفاءه من مركز المساعدة دون حذفه نهائيًا، بإرسال طلب POST لنقطة الوصول Archive a contact مع تمرير الرقم التعريفي للشخص في عنوان الطلب.

كما يمكننا استعادة الشخص من الأرشيف بإرسال طلب POST إلى نقطة الوصول Restore an archived contact وتمرير رقم الشخص في عنوان الطلب.

شخص واحد

لأرشفة الشخص رقم 1001 نكتب الطلب التالي

curl "https://example.com/api/agent/v1/contacts/1001/archive" \
  -X POST \
  -H "Authorization: Bearer @TOKEN"

ولإلغاء أرشفة هذا الشخص نكتب الطلب التالي:

curl "https://support.example.com/api/agent/v1/contacts/1001/restore-archive" \
  -X POST \
  -H "Authorization: Bearer @TOKEN"

حذف الأشخاص

لحذف أحد الأشخاص المحفوظين في مركز المساعدة، نرسل طلب من نوع DELETE إلى نقطة الوصول Delete a Contact مع تمرير الرقم الشخصي للشخص بعنوان الطلب.

ويمكن استعادة الشخص بعد الحذف بإرسال طلب POST إلى نقطة الوصول Restore a deleted contact.

شخص واحد

لحذف الشخص رقم 1001 من مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"

ولإلغاء حذف الشخص رقم 1001 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/1001/restore" \
  -X POST \
  -H "Authorization: Bearer @TOKEN"

حذف حقل مخصص

لحذف حقل مخصص أضفناه لشخص، نرسل طلب من نوع DELETE لنقطة الوصول Delete a contact field مع تمرير كل من رقم الشخص ورقم الحقل المخصص في عنوان الطلب.

حقل واحد

لحذف الحقل رقم 500 من إعدادات الشخص رقم 1002 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/contacts/500/fields/1002" \
  -X DELETE \
  -H "Authorization: Bearer @ToKEN"