التعامل مع المحادثات

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

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

export TOKEN="YOUR_API_KEY"

عرض المحادثات

لعرض كافة محادثات مركز المساعدة، نرسل طلب GET لنقطة الوصول List all conversations ويمكننا من خلال هذه النقطة تصفية المحادثات المعروضة وترتيبها.

ولعرض محادثة محددة، نرسل طلب GET لنقطة الوصول Retrieve a conversation. وننوه إلى أنه في حال كانت هذه المحادثة مدمجة مع محادثات أخرى فسنحصل ضمن الاستجابة على رسالة مفادها conversation.merged_with لإشعارنا بعملية الدمج.

كافة المحادثات

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

curl --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations'

محادثة واحدة

لعرض المحادثة التي تملك الرقم التعريفي 1003، نمرر رقم المحادثة في عنوان الطلب كما يلي:

curl --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations/1003'

محادثات مسندة لوكيل

لعرض المحادثات المسندة إلى وكيل محدد له الرقم 1008، نرسل الطلب التالي:

curl --globoff \
  --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations?assign_to[]=1008'

محادثات ضمن صندوق بريد

لعرض كافة المحادثات المفتوحة التابعة لصندوق البريد رقم 1010، نمرر حالة المحادثة ورقم صندوق البريد المطلوب في عنوان الطلب.

curl --globoff \
  --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations?status=opened&inbox_ids[]=1010'

محادثات بوسم معين

لعرض المحادثات المدرجة تحت وسم معين وليكن الوسم"مهم"، نمرر الوسم المطلوب في عنوان الطلب كما يلي:

curl --globoff \
  --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations?tags[]=مهم'

محادثات مؤرشفة

لعرض كافة المحادثات المؤرشفة في مركز المساعد، نمرره معامل الأرشفة مع ضبطه بالقيمة 1 في عنوان الطلب على النحو التالي:

curl --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations?archived=1'

عرض رسائل محادثة

لعرض كافة الرسائل ضمن محادثة معينة نرسل طلب GET لنقطة الوصول Messages مع تمرير رقم المحادثة في عنوان الطلب، ولعرض رسالة محددة ضمن هذه المحادثة نرسل طلب GET لنقطة الوصول Show Message مع تمرير رقم المحادثة ورقم الرسالة في عنوان الطلب.

كافة الرسائل

لعرض كافة الرسائل التابعة للمحادثة 1003 نكتب الطلب التالي:

curl  --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003'

رسالة واحدة

لعرض الرسالة رقم 1015 ضمن المحادثة رقم 1003 نكتب الطلب التالي:

curl --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003/messages/1015'

عرض تقييمات المحادثة

يمكننا عرض تقييمات محادثة معينة من خلال إرسال طلب GET لنقطة الوصول List all conversation reviews مع تمرير رقم المحادثة في عنوان الطلب.

تقييم محادثة محددة

لعرض تقييمات المحادثة رقم 1003، نكتب الطلب على النحو التالي:

curl --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003/reviews'

عرض سجل التغييرات لمحادثة

قد نحتاج لتتبع التغييرات التي أجراها وكلاء مركز المساعدة على محادثة معينة، وللقيام بذلك نرسل طلب GET لنقطة الوصول List all conversation history لمطالعة كافة التعديلات التي طرأت على المحادثة منذ إنشائها.

كافة التغييرات

لعرض كافة التغييرات الخاصة بالمحادثة رقم 1003، نكتب الطلب على النحو التالي:

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/conversations/1003/history?limit=100

تغييرات محددة

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

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/conversations/1003/history?limit=100&after[created_at]=2025-03-01T00%3A00%3A00&before[created_at]=2024-04-16T00%3A00%3A00&sort=created_at.asc&event=status.updated'

تعديل المحادثات

لتعديل مختلف خصائص المحادثة كحالتها، أو عنوانها، أو صندوق البريد الذي تنتمي إليه، أو الوكيل المُسندة إليه، أو تفعيل ميزة طلب تقييم المحادثة من العميل بعد إغلاقها، نرسل طلب PUT لنقطة الوصول Update a conversation. ولتعديل عدة محادثات معًا، نرسل طلب PUT لنقطة الوصول Mass update conversations.

محادثة واحدة

لتعديل خصائص المحادثة رقم 1003 بحيث نعدل حالة هذه المحادثة من الحالة مفتوحة ورقمها 437 إلى الحالة مغلقة ورقمها 440، ونضيف المحادثة لصندوق البريد رقم 1010، مع إسنادها للوكيل رقم 1008، وتعطيل ميزة تقييمها نكتب الطلب على النحو التالي:

curl -X PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
  --data '{
    "conversation_status_id": 440,
    "inbox_id": 1010,
    "assign_to": 1008,
    "disable_rating": true
  }' \
'https://example.com/api/agent/v1/conversations/1003'

عدة محادثات

لتعديل ثلاث محادثات لها الأرقام 13 و 103و 1003 على التوالي وتعديل حالاتها للحالة "بانتظار الرد" التي تملك الرقم 439، وإضافة وسم "عميل جديد" وحذف وسم "استفسار"، وإسنادها للوكيل رقم 1008 نكتب الطلب كما يلي:

curl -X PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
  --data '{
    "conversation_ids": [13, 103, 1003],
    "conversation_status_id": 439,
    "inbox_id": 1010,
    "added_tags": ["عميل جديد"],
    "deleted_tags": ["استفسار"],
    "assign_to": 1008
  }' \
  'https://example.com/api/agent/v1/conversations'

دمج المحادثات

لدمج المحادثات العائدة لجهة اتصال واحدة أو عدة جهات اتصال ضمن محادثة واحدة نرسل طلب POST لنقطة الوصول Merge conversations مع تمرير الرقم التعريفي للمحادثة في عنوان الطلب، وتمرير الأرقام التعريفية للمحادثات المطلوب دمجها معها في جسم الطلب. يشمل الدمج كل ما يوجد ضمن المحادثات كالرسائل، والوسوم، وجهات الاتصال، والملاحظات.

عدة محادثات

لدمج المحادثتين رقم 13 و 103 مع المحادثة رقم 1003 ضمن محادثة واحدة نكتب الطلب على النحو التالي:

curl --location \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
  --data '{
    "Conversation_ids": [13, 103]
  }' \
  'https://example.com/api/agent/v1/conversations/1003 /merge'

أرشفة المحادثات

لأرشفة أي محادثة في مركز المساعدة نرسل طلب من نوع POST إلى نقطة الوصول Archive a conversation، ولاستعادة محادثة من الأرشيف نرسل طلب POST لنقطة الوصول Restore an archived conversation.

أرشفة محادثة

لأرشفة المحادثة رقم 1003 نرسل الطلب على النحو التالي:

curl -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/conversations/1003/archive'

إلغاء الأرشفة

لاستعادة المحادثة 1003 من الأرشيف، نرسل الطلب على النحو التالي:

curl -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003/restore_archive'

إسناد وكيل لمحادثة

لإسناد وكيل إلى محادثة معينة كي يتابعها، نرسل طلب POST لنقطة الوصول Add a conversation agent مع تمرير الرقم التعريفي للمحادثة في عنوان الطلب، والرقم التعريفي للوكيل في جسم الطلب.

وكيل واحد

لإسناد الوكيل رقم 1008 إلى المحادثة رقم 1003، نرسل الطلب التالي:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer @TOKEN' \
  --data '{
    "agent_id": 1008 
  }' \
'https://example.com/api/agent/v1/conversations/1003/agents'

إضافة الوسوم للمحادثات

لإضافة وسم واحد لمحادثة محددة، نرسل طلب POST لنقطة الوصول Add a conversation tag
مع تمرير الرقم التعريفي للمحادثة في عنوان الطلب، واسم الوسم المطلوب في جسم الطلب، ولإضافة عدة وسوم لمحادثة أو عدة محادثات، نرسل طلب POST لنقطة الوصول Add conversation tags مع تضمين أرقام التعريفية المحادثات وأسماء الوسوم المطلوبة في جسم الطلب.

وسم واحد

لإضافة الوسم "استفسار" للمحادثة رقم 1003، نكتب الطلب على النحو التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{"name": "استفسار"}' \
'https://example.com/api/agent/v1/conversations/1003/tags'

عدة وسوم

لإضافة الوسمين "شكوى" و"مستعجل" للمحادثات رقم 13و 103و 1003 نكتب الطلب التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "conversation_ids": [13, 103, 1003],
         "tags": ["شكوى", "مستعجل"]
     }' \
'https://example.com/api/agent/v1/conversations/tags'

إضافة جهة اتصال لمحادثة

لإضافة جهة اتصال لمحادثة معينة نرسل طلب POST لنقطة الوصول Add a conversation contact مع تمرير رقم المحادثة في عنوان الطلب، ورقم جهة الاتصال في جسم الطلب.

جهة اتصال واحدة

لإضافة جهة الاتصال رقم 1001 إلى المحادثة رقم 1003 نكتب الطلب على النحو التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "contact_id": 1001
     }' \
'https://example.com/api/agent/v1/conversations/1003/contacts'

إضافة ملاحظة لمحادثة

لإضافة ملاحظة بخصوص محادثة معينة وإرفاق بعض الملفات الخاصة بها، نرسل طلب POST لنقطة الوصول Add conversation note مع تمرير رقم المحادثة في عنوان الطلب، وتمرير نص الملاحظة والمرفقات المطلوبة في جسم الطلب. وينبغي أن تتضمن كل ملاحظة نص أو مرفق أو كليهما معًا.

ملاحظة مع مرفق

لإضافة ملاحظة جديدة نصها "ملاحظة تجريبية"تحتوي على مرفق واحد له الرقم 1013 إلى المحادثة رقم 1003 نكتب الطلب التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "details": "هذه ملاحظة تجريبية",
         "attachments": [1013]
     }' \
'https://example.com/api/agent/v1/conversations/1003/notes'

حذف رسالة من محادثة

لحذف رسائل أرسلها أحد الوكلاء في مركز المساعدة، نرسل طلب DELETE لنقطة الوصول Delete Message مع تمرير كل من الرقم التعريفي للمحادثة، والرقم التعريفي للرسالة ضمن عنوان الطلب.

رسالة واحدة

لحذف الرسالة رقم 1015 من المحادثة 1003، نكتب الطلب على النحو التالي:

curl -X DELETE \
     --header 'Authorization: @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003/messages/1015'

حذف وسوم من محادثة

لحذف وسوم من محادثة أو مجموعة محادثات نرسل طلب DELETE لنقطة الوصول Delete a conversation tags مع تمرير أرقام المحادثات، وأسماء الوسوم المطلوب إزالتها في جسم الطلب.

عدة وسوم من عدة محادثات

لحذف الوسمين "شكوى" و"مستعجل" من المحادثات رقم 13و 103و 1003 نكتب الطلب التالي:

curl -X DELETE \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "conversation_ids": [13, 103, 1003],
         "tags": ["شكوى", "مستعجل"]
     }' \
'https://example.com/api/agent/v1/conversations/tags'

حذف ملاحظات المحادثات

لحذف ملاحظة مسجلة حول محادثة معينة نرسل طلب من نوع DELETE لنقطة الوصول Delete a conversation note مع تمرير كل من الرقم التعريفي للمحادثة، والرقم التعريفي للملاحظة المراد حذفها كمعاملات في عنوان الطلب. و لمعرفة أرقام هذه الملاحظات نرسل طلب GET لنقطة الوصول List all conversation notes.

ملاحظة واحدة

لحذف الملاحظة رقم 1014 من محادثة رقم 1003، نكتب الطلب التالي:

curl -X DELETE \
     --header 'Authorization: Bearer @TOKEN' \
'https://example.com/api/agent/v1/conversations/1003/notes/1014'