إدارة رسائل المحادثة

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

export TOKEN="YOUR_API_KEY"

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

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

كافة الرسائل

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

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

رسالة واحدة

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

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

عرض مرفق رسالة

لعرض مرفق معين من مرفقات الرسالة نرسل طلب GET لنقطة الوصول Preview a message attachment مع تمرير رقم المحادثة ورقم الرسالة ورقم المرفق المطلوب في عنوان الطلب، سنحصل في الاستجابة على عنوان URL خاص بالمرفق لنتمكن من عرضه.

مرفق واحد

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

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

تحميل مرفق رسالة

يمكن تحميل أي مرفق يأتي مع الرسالة وحفظه على محليًا بإرسال طلب POST لنقطة الوصول Download a message attachment مع تمرير كل من رقم المحادثة ورقم الرسالة ورقم المرفق في عنوان الطلب.

مرفق واحد

لتحميل المرفق رقم 1013 المرتبط بالرسالة رقم 1015 داخل محادثة رقم 1003 وحفظه على الجهاز المحلي باسم download_attachment.png سنكتب الطلب التالي:

curl "https://example.com/api/agent/v1/conversations/1003/messages/1015/attachments/1013/download" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -o "download_attachment.png"

تعديل محتوى رسالة

يمكن تعديل أي رسالة نرسلها عبر محادثات زيتون خلال مدة خمس دقائق فقط بعد إرسالها من خلال إرسال طلب PUT لنقطة الوصول Update Message مع تمرير الرقم التعريفي للمحادثة والرقم التعريفي للرسالة كمتغيرات مسار ضمن عنوان الطلب، وتضمين محتوى الرسالة ومرفقاتها في جسم الطلب.

رسالة واحدة

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

curl "https://example.com/api/agent/v1/conversations/1015/messages/1003" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "محتوى رسالة جديد",
    "attachments": [1013]
  }'

تعيين رسائل كمقروءة

لتغيير حالة الرسائل ضمن محادثة معينة من الحالة غير مقروءة إلى الحالة مقروءة، نرسل طلب POST لنقطة الوصول View unread messages مع تمرير الرقم التعريفي لهذه المحادثة ضمن عنوان الطلب، وأرقام الرسائل المعنية في جسم الطلب.

تعيين عدة رسائل

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

curl "https://example.com/api/agent/v1/conversations/510638/messages/mark-read" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
    "message_ids": [1015, 115]
  }'

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

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

رسالة واحدة

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

curl "https://example.com/api/agent/v1/conversations/1003/messages/1015" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
    "message_ids": [1015]
  }'

حذف مرفق رسالة

لحذف مرفق معين من رسالة ضمن محادثة، نرسل طلب DELETE لنقطة الوصول Delete a message attachment مع تمرير رقم المحادثة ورقم الرسال ورقم المرفق المطلوب حذفه ضمن عنوان الطلب.

مرفق واحد

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

curl "https://example.com/api/agent/v1/conversations/1003/messages/1015/attachments/1013" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"