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

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

export TOKEN="YOUR_API_KEY"

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

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

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

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

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

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

المحادثات التي لم يرد عليها هي المحادثات التي تكون آخر رسالة فيها مرسلة من جهة الاتصال، ولم يرد عليها أحد وكلاء مركز المساعدة، ولعرضها نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/conversations?last_reply_by=contact" \
     -H "Authorization: Bearer @TOKEN"

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

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

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

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

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

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

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

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

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

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

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

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

محادثة واحدة

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

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

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

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

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

لعرض كافة تغييرات المحادثة رقم 1003 منذ إنشائها، نكتب الطلب على النحو التالي:

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

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

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

محادثة واحدة

لتعديل خصائص المحادثة رقم 1003 بحيث نعدل حالتها من الحالة مفتوحة إلى الحالة مغلقة -بافتراض أنها تملك الرقم التعريفي 400- ونضيفها لصندوق البريد رقم 1010، مع تعطيل ميزة تقييمها نكتب الطلب على النحو التالي:

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

عدة محادثات

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

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

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

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

عدة محادثات

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

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

أرشفة محادثة

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

محادثة واحدة

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

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

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

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

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

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

وكيل واحد

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

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

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

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

وسم واحد

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

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

عدة وسوم

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

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

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

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

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

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

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

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

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

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

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

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

حذف وسوم المحادثات

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

عدة وسوم

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

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

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

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

ملاحظة واحدة

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

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