ضبط النماذج

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

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

export TOKEN="YOUR_API_KEY"

عرض النماذج

لعرض قائمة بكافة بيانات النماذج ضمن مركز المساعدة نرسل طلبGET لنقطة الوصول List all forms كاسم النموذج ووصفه والرابط الفريد له، كما يمكن تصفية النماذج المعروضة بناءً على معايير محددة مثل حالة النموذج، أو الوكلاء المخصصين للتعامل معه.

ولعرض كافة بيانات نموذج معين نرسل طلب GET لنقطة الوصول Retrieve a form مع تمرير الرقم التعريفي للنموذج المطلوب في عنوان الطلب.

كما يمكن عرض تفاصيل الحقول المكونة للنموذج كاسم الحقل ونوعه وترتيبه وهل هو إجباري أم لا، وعرض بيانات أساسية أخرى كالرسائل المخصصة عند تسليم النموذج، ورابط إعادة التوجيه المخصص لذلك من خلال إرسال طلب GET لنقطة الوصول Retrieve form builder fields مع تمرير الرقم التعريفي للنموذج المطلوب في عنوان الطلب.

كافة النماذج

لعرض كافة نماذج مركز المساعدة نكتب الطلب التالي:

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

نموذج واحد

لعرض بيانات النموذج الذي يملك الرقم 1012 على سبيل المثال نكتب الطلب كما يلي:

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

حقول نموذج

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

  curl -X GET "https://suar-dev.zaetoon.hsoubdev.com/api/agent/v1/forms/1012/builder" \
  -H "Authorization: Bearer @TOKEN"

إنشاء نموذج

توفر زيتون نموذج افتراضي مضاف مسبقًا إلى مركز المساعدة باسم "تواصل معنا" كما تقدم كودًا جاهزًا لتضمين هذا النموذج في أي موقع يخصنا، كل ما نحتاجه هو إضافة الكود في الصفحة التي نرغب في إظهار النموذج فيه.

قد نحتاج لإنشاء نموذج إضافي بإعدادات مخصصة تتناسب مع نوع العمل أو الخدمة التي نقدمها، ولإنشاء نموذج جديد نرسل طلب POST لنقطة الوصول Create a form مع تمرير إعدادت النموذج المطلوبة في جسم الطلب. وننوه لأن من الضروري أن يحتوي أي نموذج ننشؤه على حقل إجباري لاسم أو بريد الشخص وأن يتضمن اسم هذا الحقل البادئة contact_ لتمييز حقول التواصل الأساسية.

نموذج واحد

لننشئ نموذج اتصال جديد يتضمن حقول لاسم العميل وبريده الإلكتروني وحقل لكتابة رسالة الشكوى، لتضمينه في تطبيق أو موقع ويب مع ربطه بصندوق البريد رقم 1010 نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/forms" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
  "inbox_id": 1010,
  "status": "active",
  "name": "الشكاوي",
  "ar": {
    "submission_message": "شكرًا لتواصلك معنا! سنقوم بالرد قريبًا."
  },
  "en": {
    "submission_message": "Thank you for contacting us! We will get back to you soon."
  },
  "fields": [
    {
      "type": "text",
      "name": "contact_first_name",
      "required": true,
      "grid": "50",
      "ar": {
        "label": "الاسم الأول"
      },
      "en": {
        "label": "First Name"
      }
    },
    {
      "type": "text",
      "name": "contact_last_name",
      "required": true,
      "is_contact_field": true,
      "grid": "50",
      "ar": {
        "label": "اسم العائلة"
      },
      "en": {
        "label": "Last Name"
      }
    },
    {
      "type": "contact_email",
      "name": "email",
      "required": true,
      "grid": "100",
      "ar": {
        "label": "البريد الإلكتروني"
      },
      "en": {
        "label": "Email"
      }
    },
    {
      "type": "textarea",
      "name": "message",
      "required": true,
      "grid": "100",
      "min_length": 10,
      "max_length": 500,
      "ar": {
        "label": "رسالة الشكوى"
      },
      "en": {
        "label": "Message"
      }
    },
    {
      "type": "submit",
      "name": "submit_button",
      "ar": {
        "label": "إرسال"
      },
      "en": {
        "label": "Submit"
      }
    }
  ]
}'

تعديل نموذج

يمكن تعديل نموذج معين في مركز المساعدة بإرسال طلب PUT لنقطة الوصول Update a form مع تمرير الرقم التعريفي للنموذج في عنوان الطلب وإعدادت النموذج المعدلة في جسم الطلب.

ويمكن أيضًا تعديل حقل معين في النموذج من خلال إرسال طلب PUT لنقطة الوصول Update a form field مع تمرير رقم النموذج ورقم الحقل المطلوب في عنوان الطلب، وإعدادت الحقل الجديدة في جسم الطلب.

نموذج واحد

لتعديل النموذج الذي أنشأناه سابقًا في مركز المساعدة باسم "شكاوى" بفرض أنه يملك الرقم التعريفي 1012 بحيث نعدل اسم النموذج وعنوانه ووصفه وحقل الرسالة النصية سنكتب الطلب على النحو التالي:

curl "https://suar-dev.zaetoon.hsoubdev.com/api/agent/v1/forms/1012" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
  "name": "complaint form",
  "status": "active",
  "ar": {
    "submission_message": "شكرًا لتواصلك معنا!",
    "title": "نموذج شكاوى العملاء",
    "description": "يرجى وصف مشكلتك وسنقوم بالرد عليك قريبًا"
  },
  "en": {
    "submission_message": "Thank you for contacting us! We will get back to you soon.",
    "title": "Customer Complaints Form",
    "description": "Please describe your issue and we will get back to you soon"
  },
  "fields": [
    {
      "id": "27283",
      "type": "text",
      "sort": 0,
      "grid": "50",
      "required": true,
      "ar": { "label": "الاسم الأول" },
      "en": { "label": "First Name" }
    },
    {
      "id": "27284",
      "type": "text",
      "sort": 1,
      "grid": "50",
      "required": true,
      "ar": { "label": "اسم العائلة" },
      "en": { "label": "Last Name" }
    },
    {
      "id": "27285",
      "type": "contact_email",
      "sort": 2,
      "grid": "100",
      "required": true,
      "ar": { "label": "البريد الإلكتروني" },
      "en": { "label": "Email" }
    },
    {
      "id": "27286",
      "type": "textarea",
      "sort": 3,
      "grid": "100",
      "required": true,
      "min_length": 10,
      "max_length": 500,
      "ar": { "label": "المشكلة" },
      "en": { "label": "Problem" }
    },
    {
      "id": "27287",
      "type": "submit",
      "sort": 4,
      "grid": "100",
      "required": false,
      "ar": { "label": "إرسال" },
      "en": { "label": "Submit" }
    }
  ]
}'

حقل واحد

لتعديل الحقل contact_first_name في النموذج بحيث نحدد طوله ليكون 3 محارف على الأقل و20 محرف على الأكثر، ونضيف له نص نائب ونص مساعد، وبافتراض أن رقم النموذج هو 1012 ورقم الحقل هو 100، سنكتب الطلب على النحو التالي:

curl "https://suar-dev.zaetoon.hsoubdev.com/api/agent/v1/forms/1012/fields/100" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
  "type": "contact_first_name",
  "min_length": 2,
  "max_length": 50,
  "ar": {
    "label": "الاسم الأول",
    "placeholder": "أدخل اسمك الأول",
    "hint": "الرجاء كتابة الاسم الأول كما في الهوية"
  },
  "en": {
    "label": "First Name",
    "placeholder": "Enter your first name",
    "hint": "Please enter your first name as it appears on your ID"
  }
}'

حذف النماذج

لحذف نموذج من مركز المساعدة نرسل الطلب DELETE لنقطة الوصول Delete a form مع تمرير الرقم التعريفي للنموذج في عنوان الطلب.

نموذج واحد

لحذف نموذج رقم 1012 من مركز المساعدة نرسل الطلب التالي:

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