قراءة سجل محادثات Messenger عبر واجهة برمجة التطبيقات (API)
يُقرأ سجل رسائل صفحة Facebook في Messenger عبر GET /{page-id}/conversations?platform=messenger، الذي يسرد معرّفات المحادثات مع وقت آخر تحديث لكل منها، ثم GET /{conversation-id}?fields=messages للحصول على معرّفات الرسائل، و GET /{message-id} لكل رسالة لقراءة مرسلها ومستلمها ونصها ومرفقاتها. تُعيد Meta تفاصيل آخر 20 رسالة فقط في المحادثة، ويتطلب الاستدعاء إذن pages_messaging مع رمز الوصول (token) للصفحة.
يمرر easyCoexistence رسائل Messenger الجديدة الخاصة بالصفحة إلى endpoint الخاص بك فور وصولها، ويرد send_social_dm داخل نافذة 24 ساعة، من Claude أو ChatGPT أو كودك الخاص.
تُعاد تفاصيل آخر 20 رسالة فقط في المحادثة، أما الأقدم فيُعيد خطأ يفيد بأن الرسالة قد حُذفت.
عدد استدعاءات Conversations API التي يمكن لتطبيق إجراؤها لكل صفحة Facebook.
المحادثات في مجلد «Requests» التي لم تنشط منذ هذه المدة لا تُدرج في نتائج API.
المهمة التي يجب أن يكون صاحب الرمز قادرًا على تنفيذها على الصفحة لقراءة المحادثات.
خطأ عند تجاوز عدد استدعاءات Messenger API لحساب الصفحة؛ توصي Meta بالانتظار قليلًا ثم المحاولة مجددًا.
كيف تسرد محادثات الصفحة؟
عبر GET /{page-id}/conversations مع تحديد platform بالقيمة messenger. تحتوي النتيجة على مصفوفة data من معرّفات المحادثات، ولكل منها updated_time، وهو وقت إضافة آخر رسالة، وكائن paging. تنص مرجعية Meta على أن الترقيم المعتمد على الوقت غير متاح في نقطة النهاية (endpoint) هذه، لذا تابع كائن paging للتنقل في القائمة.
GET /{page-id}/conversations?platform=messenger
{
"data": [
{ "id": "<CONVERSATION_ID>", "updated_time": "<TIME>" },
{ "id": "<CONVERSATION_ID>", "updated_time": "<TIME>" }
],
"paging": { ... }
}كيف تجد محادثة شخص واحد؟
أضف إلى الطلب نفسه user_id، ويُضبط على معرّف الشخص الخاص بالصفحة. تُعيد Meta معرّف المحادثة بين الصفحة وذلك الشخص، وهو أقصر طريق من خطاف الويب (webhook) للرسائل، حيث يصل PSID بوصفه sender.id، إلى السجل الذي يقف خلفه:
GET /{page-id}/conversations?platform=messenger&user_id=<PSID>
{ "data": [ { "id": "<CONVERSATION_ID>" } ] }كيف تقرأ الرسائل داخل المحادثة؟
على خطوتين. يُعيد GET /{conversation-id} مع fields=messages معرّفات رسائل المحادثة، ولكل منها created_time، مرتبةً من الأحدث إلى الأقدم. ثم يُعيد GET /{message-id} مع الحقول التي تحتاجها، مثل id و created_time و from و to و message و reply_to، محتوى رسالة واحدة. الحقلان الافتراضيان هما id و created_time، والحقل الذي لا توجد له بيانات يُحذف من الاستجابة.
ما الحقول التي يمكن قراءتها؟
المحادثة والرسالة تُظهران حقولًا مختلفة. هذه الحقول هي التي تسردها مرجعيات Meta لمراسلات الصفحة:
- Conversation: id،
updated_time، participants مع معرّفه واسمه وبريده الإلكتروني، messages، وis_ownerبعد تفعيل Conversation Routing. - Message: id،
created_time، from و to، ولكل منهما معرّف واسم وبريد إلكتروني، و message وهو النص، ويكون فارغًا إن لم يوجد. - attachments: الملفات والصور ومقاطع الفيديو مع روابط CDN الخاصة بها، و
is_unsupported، ولا يُعاد إلا عندما تحتوي الرسالة على محتوى غير مدعوم. - reactions، و
reply_toمع mid الذي تُجيب عنه، وis_self_reply، و shares للمنشورات والريلز المشاركة. - tags: القيم مثل inbox و read و source:chat، وهي تدل على مجلد الرسالة ومصدرها.
إلى أي مدى يمكن الرجوع في القراءة؟
بالنسبة للمعرّفات، إلى بداية المحادثة كاملة، أما المحتوى فلا. تقول مرجعية Meta إن endpoint المحادثة يُعيد جميع معرّفات الرسائل فيها، بينما تُعاد التفاصيل فقط لآخر 20 رسالة، وطلب رسالة أقدم يُعيد خطأ بأن الرسالة قد حُذفت. أما المحادثات في مجلد «Requests» التي لم تنشط منذ 30 يومًا فلا تُعاد أصلًا.
ما الأذونات والمهام المطلوبة؟
token للصفحة من شخص يستطيع تنفيذ مهمة MESSAGING أو MODERATE على الصفحة، مع الأذونات pages_manage_metadata و pages_read_engagement و pages_messaging. تتطلب قراءة المحادثات مع أشخاص لا دور لهم في التطبيق أو الصفحة أو النشاط التجاري الحصول على Advanced Access، وتمنحه Meta بعد مراجعة التطبيق.
ما الحدود المطبقة على الاستدعاءات؟
تمنح حدود معدل Meta الـ Conversations API استدعاءين في الثانية لكل صفحة، وتعود الاستدعاءات التي تتجاوز الحد بالخطأ 613 أو 80006، ونصه: «There have been too many messenger api calls to this Page account» ويعني أن الصفحة تجاوزت الحد. أما الصفحة التي تبلغ حد الحجم العالي لدى Meta، مثل إرسال أكثر من 40 رسالة في الثانية، فلا تستطيع سرد محادثاتها حتى ينخفض الحجم، لكن يمكن قراءة محادثة واحدة للبحث عن رسائل جديدة.
متى تستخدم الواجهة بدلًا من webhooks؟
للاستعلام عن الماضي. ترسل webhooks الرسائل الجديدة لحظة حدوثها، وتنص Meta على أن الإشعارات السابقة لا يمكن استعلامها لاحقًا، لذا فإن Conversations API هي الطريق الذي يقرأ به التكامل ما سبق بدء استماعه، أو يلحق به بعد توقف. ومع تفعيل Conversation Routing، يضيّق الحقل is_owner القائمة إلى المحادثات التي يتولى التطبيق الرد عليها، وهو ما تقترحه Meta للاسترداد بعد التوقف.
كيف يقرأ easyCoexistence سجل Messenger؟
لا يقرأ السجل. تُربط الصفحة بالأذونات pages_messaging و pages_manage_metadata و pages_read_engagement، لكن لا توجد أداة تستدعي Conversations API، ولا تُسلَّم رموز الصفحات. تصل الرسائل الجديدة إلى endpoint الخاص بك عبر set_social_webhook_destination لحظة وصولها، وتُمرَّر دون الاحتفاظ بنسخة منها، ليحتفظ نظامك الخاص بالسجل الذي يحتاجه.
الأخطاء الشائعة
- توقّع محتوى الرسائل في استدعاء القائمة. endpoint المحادثة يُعيد معرّفات الرسائل، فاقرأ حقول كل رسالة من /{message-id}.
- الاعتماد على السجل كاملًا. تتوقف التفاصيل عند آخر 20 رسالة، لذا احفظ ما تحتاجه من webhooks أثناء وصول الرسائل.
- الاستعلام المتكرر عن الرسائل الجديدة. مع استدعاءين في الثانية لكل صفحة، تصطدم حلقة الاستعلام سريعًا بحد المعدل، بينما يسلّم webhook الرسائل لحظة حدوثها.
- ترتيب المحادثات بالتاريخ عبر since و until. الترقيم المعتمد على الوقت غير متاح في endpoint المحادثات، لذا تابع كائن paging بدلًا من ذلك.
لا توجد لديه أداة لـ Conversations API، لذا يُقرأ السجل السابق في صندوق وارد الصفحة. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل تتضمن Conversations API رسائل الصفحة نفسها؟
نعم. يحدد حقلا from و to الشخص أو الصفحة، لذا تتضمن رسائل المحادثة الطرفين معًا.
هل يمكنني قراءة محادثات Messenger بدون مراجعة التطبيق؟
للأشخاص الذين لديهم دور في التطبيق أو الصفحة يكفي Standard Access. أما المحادثات مع أي شخص آخر فتحتاج Advanced Access، وتُمنح بعد مراجعة التطبيق.
هل يستطيع Conversations API إرسال الردود؟
لا، إذ تنص مرجعية المحادثات لدى Meta على أن endpoint لا ينشر شيئًا، وتُرسل الردود عبر Send API على المسار /{page-id}/messages، وهو طريق منفصل.
هل يحتفظ easyCoexistence بمحادثات Messenger الخاصة بي؟
ليس افتراضيًا. تُمرَّر الأحداث دون الاحتفاظ بنسخة منها، وعند تفعيل أتمتة، يُحفظ نص الرسالة لمدة 7 أيام، وسجلات تشغيل الأتمتة لمدة 30 يومًا.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في