بيانات مساحة العمل

المحادثات

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

المحادثة

المحادثة إما open وإما closed، وإغلاقها حالة سير عمل لا شيء يراه المستلم.

الحقل	الوصف
id	المعرّف العام للخيط.
status	open أو closed.
channel_id	القناة التي يجري عليها الخيط.
contact	الطرف الآخر: المعرّف والرقم والاسم وأسماء الوسوم.
assignee	من يملك الخيط، إن وُجد. ومعرّف المستخدم فيه معرّف عضو مساحة عمل لا معرّف مستخدم.
unread_count	كم رسالة واردة لم تُعلَّم مقروءة.
last_message_at	آخر وقت جرى فيه شيء على الخيط.
last_inbound_at, last_outbound_at	آخر وارد وآخر صادر، كلٌّ على حدة.
closed_at	وقت الإغلاق، إن كان مغلقا.

النقاط

متاحة لـ API key

GET/v1/conversationsGET/v1/conversations/{conversationId}GET/v1/conversations/{conversationId}/messagesPOST/v1/conversations/{conversationId}/messagesPOST/v1/conversations/{conversationId}/closePOST/v1/conversations/{conversationId}/reopen

بيانات اعتماد الجلسة فقط

هذه نقاط سير العمل البشري. تتطلب access token، لأن الإسناد وحالة القراءة والملاحظات الداخلية كلها عن شخص — وبيانات الاعتماد الآلية لا عضو لها لتُسند إليه.

POST/v1/conversations/{conversationId}/assignPOST/v1/conversations/{conversationId}/unassignGET/v1/conversations/{conversationId}/assignmentsPOST/v1/conversations/{conversationId}/readGET/v1/conversations/{conversationId}/notesPOST/v1/conversations/{conversationId}/notesDELETE/v1/conversations/{conversationId}/notes/{noteId}

الرد

نقطة الرد لا تأخذ مستلما ولا قناة: كلاهما من المحادثة، وهذا يزيل صنفا كاملا من الأخطاء. وتعيد الشكل نفسه الذي يعيده الإرسال المباشر.

curl

# The recipient and the channel come from the conversation, never the body.
curl -X POST https://whats.azzamkh.sa/api/v1/conversations/cnv_.../messages \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "تم شحن طلبك اليوم." }'

# 201 Created
# { "id": "msg_...", "status": "queued", "category": "utility", ... }

# Exactly one of "text" or "template" must be present.

أرسل واحدا فقط من text أو template. وإرسال كليهما أو لا أيّهما يعطي 422.
الرد يُصنَّف دائما utility. ولا تستطيع رفع أولويته ولا خفضها.
لا يوجد حقل وسائط. وإرفاق ملف بالرد غير متاح بعد.
الرد الناجح يعلّم الخيط مقروءا أيضا.

المرشّحات

المعامل	القيم	الوصف
status	open, closed	الخيوط المفتوحة أو المغلقة.
channel_id	ch_…	خيوط قناة واحدة.
assigned	me, unassigned, none, team, user:mem_…, team:tm_…	من يملك الخيط. وقيمتا me وteam نسبية إلى المستدعي، فلا تعنيان شيئا لـ API key.
unread	true	لا يفعّل هذا المرشّح إلا النص true بالضبط.
q	string	يبحث في جهة الاتصال — اسمها أو رقمها — لا في نص الرسائل.
tag	slug	الـ slug الخاص بوسم جهة اتصال. وخلافا لقائمة جهات الاتصال، لا يُقبل المعرّف هنا.
limit, after	—	تقسيم بالـ cursor.

قيم المرشّحات المجهولة تُتجاهل

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

الترتيب

هذه القائمة ليست مرتّبة بالنشاط الأحدث

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

نطاق الفرق

يمكن لمساحة العمل أن تقيّد القنوات التي يراها فريق. وحيث ضُبط ذلك يُرشَّح الوصول إلى المحادثات به — في القراءة والكتابة على السواء.

الـ API key غير مقيّد أبدا. فبيانات الاعتماد الآلية لا عضوية فريق لها، وترى كل محادثة في مساحة العمل.
أما المستخدم فمجموعته المرئية هي كل قناة عدا المقيّدة بفرق ليس منها.
الخيط على قناة خارج نطاقك يعطي 403 برمز CONVERSATION_ACCESS_DENIED وسببه في details.
أما الخيط في مساحة عمل أخرى فيعطي 404. والفرق بينهما مقصود: أحدهما يخبرك أن الخيط موجود وأنك لا تراه، والآخر لا يخبرك بشيء البتة.