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

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

طرق تعديل إعدادات شخص

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

أولًا: نقطة الاتصال {contacts/{id/

تساعدك نقطة الاتصال {contacts/{id/ على تعديل الإعدادات الأساسية للشخص مثل: الاسم، والصورة الشخصية، والحالة، والشركة التي ينتمي إليها، والمستخدم المُسنَد إليه، وفق التالي:

• عنوان URL:
  https://al-munasib.zaetoon.com/api/agent/v1/contacts/{id}.
• نوع الطلب: PUT.
• معاملات المسار Path Parameters: معامل واحد فقط، هو الرقم التعريفي للشخص id، نوع المعامل عدد صحيح integer، وهو معامل إجباري.
• جسم الطلب Body: يُكتب بصيغة JSON ويتضمن المعاملات التالية:
• • first_name: معامل إجباري، نوعه سلسلة نصية string، يُحَدِّد الاسم الأول للشخص.
  • last_name: معامل إجباري، نوعه سلسلة نصية string، يُحَدِّد اسم عائلة الشخص.
  • avatar: نوعه سلسلة نصية string، يُحَدِّد صورة الشخص، تُمَرِّر ضمنه الترميز base64 للصورة.
  • status: نوعه سلسلة نصية string، يُحَدِّد حالة الشخص، ويقبل إحدى القيم التالية حصرًا: active أو banned أو deleted.
  • avatar_url: نوعه سلسلة نصية string، يساعدك على استخدام رابط الصورة الشخصية لجهة الاتصال (للشخص) بدلًا من رفعها إلى خادم زيتون.
  • locale: نوعه سلسلة نصية string، يُحَدِّد الإعدادات المحلية للشخص، ويأخذ إحدى القيمتين ar أو en.
  • custom_fields: نوعه عنصر object مركب من عدة عناصر، يمثل كل عنصر منها أحد الحقول المخصصة الخاصة بتعريف الأشخاص (في حال استخدامك لها) ويكتب وفق الصيغة العامة التالية:

"custom_fields": {
           "field_{field id}": "your custom field value"
     }

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

• • company_id: نوعه عدد صحيح integer، تُمَرِر ضمنه الرقم التعريفي id للشركة التي تود ضم الشخص إليها.
  • assign_to: نوعه عدد صحيح integer، تُمَرِر ضمنه الرقم التعريفي id للمستخدم أو موظف مركز المساعدة الذي تود إسناد الشخص إليه.

مثال

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

curl -X PUT --header 'Authorization: Bearer your_token' 'Content-Type: application/json' --data '{
   "first_name": "name",
    "last_name": "last",
    "custom_fields": {
           "field_34424": "5268000"
     },
    "company_id": 247
    }' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts/438085'

ثانيًا: نقطة الاتصال contacts/save/

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

• عنوان URL لنقطة الاتصال:
  https://{your_subdomain}/api/agent/v1/contacts/save.
• نوع الطلب: POST.
• جسم الطلب Body: يُكتب بصيغة JSON ويتضمن المعاملات التالية:
• • id: نوعه عدد صحيح integer، يُطلَب فقط عندما تستخدم نقطة الاتصال لتعديل الأشخاص، فهو يُحَدِّد الشخص المطلوب تعديله، أما عند استخدامها لإضافة شخص جديد فلا حاجة له.
  • first_name: نوعه سلسلة نصية string، يُحَدِّد الاسم الأول للشخص.
  • last_name: نوعه سلسلة نصية string، يُحَدِّد اسم عائلة الشخص.
  • avatar: نوعه سلسلة نصية string، تُمَرِر ضمنه الترميز base64 لصورة الشخص.
  • emails: نوعه مصفوفة من السلاسل النصية array، يتضمن عناوين البريد الإلكتروني للشخص.
  • tags: نوعه مصفوفة من السلاسل النصية array، تُكتب ضمنه الوسوم التي ترغب بإضافتها إلى الشخص، ولا يُشترط أن تكون الوسوم موجودة مسبقًا في مركز المساعدة إذ مجرد كتابتها هنا يعني إضافتها إلى وسوم المركز.
  • fields: نوعه مصفوفة array، وهو خاص بإضافة حقول جديدة إلى إعدادات الشخص مثل روابط URLs ملفاته الشخصية على مواقع التواصل الاجتماعي أو غير ذلك، تتألف المصفوفة fields من عدة عناصر objects، يمثل كل عنصر رابط معين ويتضمن اسم الرابط key وهو معامل إجباري وقيمة الرابط value ونوع الحقل type وقيمته المتاحة حاليًّا "url" كما في المثال التالي:

"fields": [
   {
      "key": "الرابط الأول",
       "value": "https://exampel.com",
       "type": "url"
   },
  {
      "key": "الرابط الثاني",
      "value": "https://exampel2.com",
      "type": "url"
   }
]

• • numbers: نوعه مصفوفة من العناصر array، يمثل كل عنصر object منها رقم جوال للشخص يحتوي جزأين هما رمز الدولة country_code والرقم number. كما في المثال التالي:

"numbers" :[
    {
       "country_code": 999,
       "number" : 123456789
   },
   {
       "country_code": 999,
       "number" : 111111111
    }
     ]

• • status: نوعه سلسلة نصية string، يُحَدِّد حالة الشخص، ويقبل حصرًا إحدى القيم التالية:
  • • active فعَّال.
    • banned محظور.
    • deleted محذوف.
  • avatar_url: نوعه سلسلة نصية string، يمكنك استخدامه لتمرير رابط الصورة الشخصية لجهة الاتصال بدلًا من رفعها باستخدام المعامل "avatar".
  • locale: نوعه سلسلة نصية string، يُحَدِّد الإعدادات المحلية للشخص (إعدادات اللغة)، ويكون إما "ar" أو "en".
  • custom_fields: نوعه عنصر object مركب من عدة عناصر، يمثل كل عنصر منها أحد الحقول المخصصة الخاصة بتعريف الأشخاص (في حال استخدامك لها) ويكتب وفق الصيغة العامة التالية:

"custom_fields": {
           "field_{field id}": "your custom field value"
     }

ويمكنك الرجوع للأمثلة في مقال إضافة شخص جديد إلى مركز المساعدة.

• • segment_ids: نوعه مصفوفة array، تُكتب ضمنه الأرقام التعريفية للفئات segments التي سينتمي إليها الشخص.
  • company_id: نوعه مصفوفة array، تُكتب ضمنه الأرقام التعريفية للشركات التي سينتمي إليها الشخص.
  • assign_to: نوعه عدد صحيح integer، تُمَرِر ضمنه الرقم التعريفي id للمستخدم الذي تود إسناد الشخص إليه.

مثال

يبين المثال التالي إجراء بعض التعديلات على الشخص ذو الرقم التعريفي "438092" في مركز مساعدة "المناسب" تشمل مايلي:

1. إضافة عنوان بريد إلكتروني للشخص.
2. إضافة وسم جديد له ليكن مثلًا "عميل مميز".
3. ضمه إلى الشركة ذات الرقم "247".
4. إضافة رقمه الوطني ضمن أحد الحقول المخصصة.
5. إضافته إلى فئة "العملاء" ذات الرقم "2098" في مركزنا التجريبي.

curl -X POST --header 'Authorization: Bearer your_token' 'Content-Type: application/json' --data '{
    "id": "438092",
    "emails": ["info@test.com"],
    "tags": ["عميل مميز"],
    "fields": [
 {
      "key": "رابط موقعه الإلكتروني",
       "value": "https://test.com",
       "type": "url"
   }
    ],
    "custom_fields": {
           "field_34424": "5517000"
     },
    "segment_ids": [2098],
    "company_id": 247
   }' 'https://al-munasib.zaetoon.com/api/agent/v1/contacts/save'