التعامل مع قواعد المعرفة

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

export TOKEN="YOUR_API_KEY"

عرض قواعد المعرفة

يمكننا إرسال طلب GET إلى نقطة الوصول List all knowledgebases لجلب قائمة بكافة قواعد المعرفة الموجودة في مركز المساعدة، ولجلب بيانات قاعدة المعرفة المكتوبة باللغة العربية أو باللغة الإنجليزية نرسل الطلب طلب GET لنقطة الوصول Retrieve a knowledgebase.

كافة القواعد

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

curl "https://example.com/api/agent/v1/knowledgebases?statuses=active" \
     -H "Authorization: Bearer $TOKEN"

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

قاعدة المعرفة العربية

لعرض بيانات قاعدة المعرفة باللغة العربية في مركز مساعدة زيتون نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar" \
     -H "Authorization: Bearer $TOKEN"

قاعدة المعرفة الإنجليزية

لعرض بيانات قاعدة المعرفة باللغة الإنجليزية في مركز مساعدة زيتون نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/en" \
     -H "Authorization: Bearer $TOKEN"

عرض روابط قاعدة المعرفة

لعرض كافة روابط القوائم ضمن قاعدة المعرفة، نرسل طلب GET لنقطة الوصول List knowledgebase menu links.

ولعرض بيانات رابط قائمة محدد في قاعدة المعرفة نرسل طلب GET لنقطة الوصول Show menu link مع تمرير معرف الرابط المحدد المطلوب جلبه و لغة قاعدة المعرفة ونوع القائمة في عنوان الطلب.

روابط القائمة الرئيسية

لعرض كافة روابط القائمة الرئيسية في قاعدة المعرفة باللغة العربية نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/menus/primary/links" \
     -H "Authorization: Bearer $TOKEN"

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

روابط القائمة الفرعية

لجلب روابط القائمة الفرعية في قاعدة المعرفة باللغة العربية نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/menus/secondary/links" \
     -H "Authorization: Bearer $TOKEN"

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

رابط واحد للقائمة الرئسية

لعرض بيانات رابط القائمة الرئيسية له المعرف 900 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/menus/primary/links/900" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json"

عرض كتل قاعدة المعرفة

يمكننا عرض كافة الكتل blocks الموجودة في قاعدة المعرفة من خلال إرسال طلب GET لنقطة الوصول List all knowledgebase blocks مع تمرير لغة قاعدة المعرفة في عنوان الطلب.

كافة الكتل

لجلب كافة كتل قاعدة المعرفة العريبة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/blocks" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json"

في حال نجاح الطلب ستتضمن الاستجابة مصفوفة من الكتل، وتفاصيل كل كتلة كموقع الكتلة، ونوعها، وحالتها.

الكتل المحذوفة

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

curl "https://example.com/api/agent/v1/knowledgebases/ar/blocks?statuses[]=deleted" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json"

تعديل قاعدة المعرفة

تعديل قاعدة المعرفة وتحديث بياناتها نرسل طلب PUT لنقطة الوصول Update a knowledgebase ونمرر البيانات المطلوب تعديلها في جسم الطلب.

تغيير اللون الأساسي

لتعديل اللون الأساسي المستخدم في قاعدة المعرفة العربية التي لها المعرف 1004 للون الأزرق 0000FF# سنكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar" \
     -X PUT" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "id": "1004",
         "locale": "ar",
         "theme": "default",
         "theme_color": "#0000FF",
         "status": "active"
     }'

في حال نجاح طلب التعديل، نحصل على استجابة تتضمن كافة تفاصيل قاعدة المعرفة بعد التعديل، مع الإشارة لنجاح تعديل عملية التعديل.

كود CSS مخصص

يمكننا تنسيق بعض العناصر في قاعدة المعرفة من خلال كتابة الطلب التالي الذي يمرر التنسيق المطلوب للمعامل custom_css على النحو التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar" \
     -X PUT \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "id": "1004",
         "locale": "ar",
         "theme": "default",
         "theme_color": "#0000FF",
         "status": "active",
         "custom_css": "body { font-family: Arial, sans-serif; } .card-body {               background-color: #87CEEB; }"
      }'

ولإلغاء التنسيقات يمكن إرسال نفس الطلب مع تمرير قيمة فارغة للمتغير custom_css.

تعديل القوائم

يمكن إرسال طلب من نوع PUT لنقطة الوصول Update menu link لتعديل رابط قائمة من قوائم قاعدة المعرفة مع إرسال المعرف الفريد لرابط القائمة الذي نرغب في تعديله ولغة قاعدة المعرفة ونوع القائمة في عنوان الطلب، وبيانات الرابط الجديد في جسم الطلب.

رابط قائمة رئيسية

لتحديث الاسم الظاهر، والأيقونة، والرابط، والترتيب لرابط القائمة الرئيسية TEST Link1 الذي له المعرف 900، سنكتب الطلب التالي:

curl "https://exapmle.com/api/agent/v1/knowledgebases/ar/menus/primary/links/900" \
     -X PUT 
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
     "url": "https://example2.com/",
     "name": "Updated TEST Link1 ",  
     "icon": "book",
     "sort": 3,
     "status": "active"
     }'

إذا نجح الطلب سنحصل على معلومات تفصيلية حول الرابط المعدل والمورد الذي يرتبط به إن وجد، مع رسالة تشير لنجاح عملية التعديل.

تعديل الكتل

يمكننا تعديل كتلة في قاعدة المعرفة من خلال إرسال طلب من نوع PUT لنقطة الوصول Update knowledgebase block مع تحديد لغة قاعدة المعرفة وموضع الكتلة في عنوان الطلب، وبيانات الكتلة الجديدة في جسم الطلب.

كتلة المقالات الشائعة

لتعديل عنوان وحالة كتلة المقالات الأكثر شيوعًا المضافة في القسم footer نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/blocks/footer" \
     -X PUT \
     -H "Authorization: Bearer @TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
     "title": "أكثر المقالات قراءة",
     "status": "inactive"
     }'

كتلة مقالات مختارة

لتعديل عنوان كتلة المقالات المختارة التي أضفناها في القسم body إلى مقالات مميزة وتغيير المقال رقم 1502 إلى الرقم 1503 لها نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/knowledgebases/ar/blocks/body" \
     -X PUT \
     -H "Authorization: Bearer @TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
     "title": "مقالات مميزة", 
     "status": "active",
     "contents": [
     {
     "resource_type": "article",
     "resource_id": 1501,
     "sort": 2
     },
     {
     "resource_type": "article",
     "resource_id": 1503,
     "sort": 1
     }
     ]
     }'

إضافة كتلة لقاعدة المعرفة

يمكننا إرسال طلب من نوع POST لنقطة الوصول Create knowledgebase block لإنشاء كتلة جديدة في قاعدة المعرفة مع تحديد لغة قاعدة المعرفة في عنوان الطلب، وبيانات الكتلة المطلوبة في جسم الطلب.

ننوه لأنه لا يمكن إضافة نفس الكتلة أكثر من مرة ضمن الصفحة الرئيسية لقاعدة المعرفة، فالصفحة مقسمة لثلاثة مواقع هي header و body و footer ويجب أن يحتوي كل موقع على كتلة واحدة فقط، كما يجب أن يكون نوع الكتلة في كل موقع فريدًا.

كتلة المقالات الشائعة

لإضافة كتلة بعنوان المقالات الأكثر شيوعًا في القسم footer ضمن قاعدة المعرفة العربية نكتب الطلب التالي:

curl  "https://example.com/api/agent/v1/knowledgebases/ar/blocks" \
     -X POST \
     -H "Authorization: Bearer @TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
     "title": "المقالات الاكثر شيوعاً",
     "position": "footer",
     "type": "popular_articles",
     "status": "active"
     }'

مقالات محددة

لإضافة مقالات محددة ضمن كتلة بعنوان مقالات مختارة في القسم body لقاعدة المعرفة العربية نكتب الطلب التالي:

curl  "https://example.com/api/agent/v1/knowledgebases/ar/blocks" \
     -X POST \
     -H "Authorization: Bearer @TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
     "title": "مقالات مختارة",
     "type": "selected_articles",
     "position": "body",
     "status": "active",
     "contents": [
     {
     "resource_type": "article",
     "resource_id": 1501,
     sort": 1
     },
     {
      "resource_type": "article",
     "resource_id": 1502,
     "sort": 2
     }
     ]
     }'

حذف كتلة من قاعدة المعرفة

يمكننا إرسال طلب من نوع DELETE لنقطة الوصول Delete Knowledgebase block لحذف كتلة جديدة من قاعدة المعرفة مع تحديد لغة قاعدة المعرفة وموضع الكتلة

كتلة الترويسة

لحذف الكتلة الموجوة في القسم header نكتب الطلب التالي:

$ curl  "https://example.com/api/agent/v1/knowledgebases/ar/blocks/header" \
     -X DELETE 
     -H "Authorization: Bearer @TOKEN"

كتلة التذييل

لحذف الكتلة الموجوة في القسم footer نكتب الطلب التالي:

$ curl "https://example.com/api/agent/v1/knowledgebases/ar/blocks/footer" \
     -X DELETE 
     -H "Authorization: Bearer @TOKEN"

في حال نحاح الطلب سنحصل على رسالة تفيد بنجاح عملية الحذف، وفي حال حاولنا حذف كتلة غير موجودة سنحصل على الخطأ التالي:

{
  "status": "failed",
  "messages": [
    {
      "code": "knowledgebaseblock.404",
      "message": "المحتوى غير موجود"
    }
  ]
}