التعامل مع الدردشات المباشرة

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

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

export TOKEN="YOUR_API_KEY"

طلب عرض الدردشات المباشرة

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

عرض كافة الدردشات

لعرض كافة الدردشات المباشرة المعرفة في مركز مساعدة له النطاق example.com مع ترتيبها تصاعديًّا حسب تاريخ إنشائها من الأقدم إلى الأحدث نرسل طلبGET كما يلي:

curl --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/chats?sort=created_at.asc'

عرض دردشات صندوق بريد معين

لعرض الدردشات المباشرة المرتبطة بالصندوق رقم 1010ضمن مركز مساعدة له النطاق example.com نكتب الطلب كما يلي:

curl --globoff \
--header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/chats?inbox_id=1010'

عرض الدردشات الفعالة فقط

لعرض الدردشات الفعالة فقط في مركز مساعدة له النطاق الفرعي example.com نكتب الطلب كما يلي:

curl --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/chats?statuses[]=active'

طلب إنشاء دردشة مباشرة

توفر زيتون دردشة مباشرة افتراضية مضافة مسبقًا إلى مركز المساعدة تسمى الدردشة الأساسية، ويمكننا إنشاء دردشة مباشرة إضافية إلى جانب الدردشة الأساسية من خلال إرسال طلب POST لنقطة الوصول Create a chat مع تمرير خصائص الدردشة في جسم الطلب.

طلب عرض كافة إعدادت الدردشة

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

عرض كافة إعدادت دردشة

لعرض كافة إعدادات الدردشة المباشرة رقم 1011 في مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/chats/1011'

إنشاء دردشة إضافية

لننشئ دردشة إضافية جديدة في مركز مساعدة له النطاق example.com مع ضبط مختلف خياراتها من خلال الطلب التالي:

curl -X POST --header 'Content-Type: application/json'  \
--header 'Authorization: Bearer @TOKEN' \
--data '{
  "name": "الدردشة الإضافية",
  "description": "دردشة إضافية",
  "inbox_id": "1010",
  "first_name_field": "required",
  "last_name_field": "required",
  "email_field": "required",
  "mobile_number_field": "optional",
  "agent_ids": [108, 1008],
  "team_ids": [1009],
  "slug": "new-chat",
  "welcome_message_behaviour": "popup",
  "replying_speed": "",
  "authentication_method": "none",
  "status": "active",
  "ar": {
    "welcome_message": "كيف يمكننا مساعدتك؟",
    "title": "تحدث معنا"
  },
  "tabs": [
    {
      "name": "تعرّف على خدماتنا",
      "icon": "Enter_your_icon_image_SVG_Code",
      "status": "active",
      "locale": "ar",
      "type": "knowledgebase",
      "sort": "0"
    },
    {
      "name": "الدردشة المباشرة",
      "icon": "Enter_your_icon_image_SVG_Code",
      "status": "active",
      "locale": "ar",
      "type": "chat",
      "sort": "1"
    }
  ]
}' \
'https://example.com/api/agent/v1/chats'

طلب تعديل إعدادات دردشة مباشرة

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

تعديل إعدادات دردشة مباشرة

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

curl -X PUT \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer your_token' \
     --data '{
       "name": "الدردشة الإضافية",
       "description": "هذه الدردشة مخصصة لعملاء المتجر",
       "mobile_number_field": "hidden",
       "email_field": "required",
       "authentication_method": "email",
       "team_ids": [1009 , 109],
       "status": "active",
       "ar": {
         "title": "تحدث معنا"
       },
       "tabs": [
         { 
           "name": "الدردشة المباشرة",
           "icon": "Enter_your_icon_image_SVG_Code",
           "status": "active",
           "locale": "ar",
           "type": "chat",
           "sort": "1"
         }
       ]
     }' \
     'https://example.com/api/agent/v1/chats/1011'