إضافة استلامات النماذج يدويًّا

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

إضافة استلامات النماذج يدويًّا

يمكن لمستخدمي مركز المساعدة إضافة استلام form submission عن جهة اتصال معينة بإرسال طلب من نوع POST إلى نقطة الاتصال form-submissions/ وفق التالي:

• عنوان URL لنقطة الاتصال:

https://{your_subdomain}/api/agent/v1/form-submissions.

• نوع الطلب: POST.
• جسم الطلب Body: يُكتب بصيغة JSON ويتضمن المعاملات التالية:
• • {submission_name}: نوعه سلسلة نصية string، تمرر ضمنه أسماء حقول النموذج التي ينبغي إرسالها إلى الواجهة البرمجية.
    تنشأ هذه الأسماء ديناميكيًا وتختلف من مركز مساعدة لآخر حسب الاسم والمواصفات التي تختارها لكل حقل من حقول النموذج، وتبدو مثل: 01j3mnqd7vjned3mefw5xfx33p.

ملاحظة1: إذا احتوى نموذجك حقلًا من النوع "contact_phone_number" لكتابة رقم جوال العميل، فستمرره ضمن الطلب POST بهيئة كائن مؤلف من عنصرين: رمز الدولة، ورقم الهاتف، وفق الصيغة المبينة في المثال التالي:

ملاحظة2: إذا تضمن نموذجك حقلًا خاصًا بإرفاق الملفات أي من النوع "files"، فأمامك طريقتان لتحميل الملفات المرفقة: إما بتمريرها ضمن طلب إنشاء الاستلام نفسه بهيئة مصفوفة من السلاسل النصية هي تراميز Base64 المقابلة لكل ملف كما في المثال التالي:

"01j8waqve6df8pqjvnp2qcb310" : {
"files": ["file1_base64_code", "file2_base64_code"]
}

أو من خلال رفعها مسبقًا إلى خادم زيتون باستخدام إحدى نقطتي الاتصال files/ أو files/images/ ثم تمرير الأرقام التعريفية للملفات المرفوعة ids ضمن طلب إنشاء الاستلام وفق المثال التالي:

"01j8waqve6df8pqjvnp2qcb310" : {
"ids": [file1_id, file2_id]
}

علمًا أن الحد الأقصى لعدد الملفات المسموح إرفاقها مع الاستلام الواحد هو خمسة ملفات فقط وهذا ينطبق على طريقتي الإرفاق.

• • form_id:نوعه عدد صحيح integer، تمرر ضمنه الرقم التعريفي لنموذج التواصل الذي ترغب بإضافة الاستلام الجديد ضمنه. علمًا أنه يمكنك عرض قائمة بالنماذج المُعَرَّفة ضمن مركز المساعدة بإرسال طلب GET إلى نقطة الاتصال forms/.
  • contact_id: نوعه عدد صحيح integer، الرقم التعريفي لجهة الاتصال contact، يساعدك على ربط الاستلام الجديد بجهة اتصال محددة ومُعَرَّفة مسبقًا ضمن مركز المساعدة.

أمثلة

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

في البداية ينبغي على المستخدم امتلاك الصلاحيات اللازمة للعملية وتسجيل الدخول إلى مركز المساعدة، إذ سيُمرر رمز الوصول access token الخاص به (والذي ترجعه الواجهة بعد عملية تسجيل الدخول) في ترويسة الطلب POST التالي:

curl -X POST --header 'Authorization: Bearer your_token' --header 'Content-Type: application/json'  --data '{
"form_id": 1048,
"01j3mnqd7mcyyxzs9te09s57p9" :"client_name",
"contact_id" : "432651",
"01j3mnqd7vjned3mefw5xfx33p" :"client_mail@example.com",
"01j3mnqd88q4jsrmnp1zt3e14k" :"company_name",
"01j3mnqd8ep5fxqj03jvcnt15y" :"https://example.com",
"01j3mnqd82zeqxwmmb1xp1mqxy" : {
    "country_code": 999,
     "number": 123456489
    },
"01j3mnqd8m53m7rearf6eztwp8" : "type_your_message_details",
"01j8waqve6df8pqjvnp2qcb310" : {
"files": ["type_base64_code_for_your_file"]
},
}' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions'

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