واجهة Send API في Messenger: إرسال الرسائل من صفحة Facebook
ترسل صفحة Facebook رسائل Messenger عبر واجهة برمجة التطبيقات (API) باستخدام POST /{page-id}/messages ورمز الوصول (token) الخاص بالصفحة. يحمل المستلم معرّف الشخص ضمن الصفحة (PSID)، ويكون messaging_type إما RESPONSE أو UPDATE داخل نافذة المراسلة القياسية، أو MESSAGE_TAG بعدها. ويحمل الحقل message نصًا أو مرفقًا مثل صورة أو صوت أو فيديو أو ملف. وتُرجع Meta الحقلين recipient_id وmessage_id في الاستجابة.
يرد easyCoexistence على الرسائل المباشرة في Messenger بواسطة send_social_dm من Claude أو ChatGPT أو من كودك الخاص ضمن نافذة الـ 24 ساعة، كنص؛ أما الوسائط وأزرار الرد السريع والقوالب فغير مشمولة.
عدد استدعاءات Send API التي يمكن لتطبيق إجراؤها لكل صفحة للرسائل النصية والروابط والتفاعلات والملصقات.
عدد استدعاءات Send API التي يمكن لتطبيق إجراؤها لكل صفحة للرسائل التي تحتوي على صوت أو فيديو.
أكبر أصل يحفظه Messenger Platform لإعادة استخدامه، والصورة المرفوعة من رابط محدودة بـ 8 MB.
أكبر عدد من الصور يمكن لرسالة واحدة أن تحمله في المصفوفة attachments، وهو النوع الوحيد من الوسائط المسموح به هناك.
المدة التي يبقى فيها attachment_id المحفوظ صالحًا قبل وجوب رفع الوسائط من جديد.
ماذا يتضمن طلب Send API؟
يذكر Meta ستة مكونات يجب أن يتضمنها الإرسال: معرّف الصفحة المرسِلة، ومعرّف الشخص المستلم، وtoken الخاص بتلك الصفحة، وإذنًا من الشخص، ونوع الرسالة، والمحتوى. الطلب عبارة عن POST بصيغة JSON إلى /{page-id}/messages، والرد على شخص راسلك للتو يبدو هكذا:
POST /{page-id}/messages
{
"recipient": { "id": "<PSID>" },
"messaging_type": "RESPONSE",
"message": { "text": "Your order ships tomorrow." }
}
{ "recipient_id": "<PSID>", "message_id": "<MESSAGE_ID>" }أي معرّف يوضع في recipient؟
غالبًا معرّف الشخص ضمن الصفحة، أي PSID، الذي يخصصه Meta لكل شخص في أول مرة يراسل فيها الصفحة، ويصل في خطاف الويب (webhook) الخاص بالرسائل باسم sender.id. يقبل كائن recipient أنواعًا أخرى من المعرّفات في حالات محددة:
- id: معرّف PSID، فريد لذلك الشخص ولتلك الصفحة.
user_ref: لشخص استخدم إضافة أو زر postback لمراسلة الصفحة.comment_idأوpost_id: للرد الخاص على تعليق أو منشور زائر.- المعرّفات القادمة من Facebook Login مرتبطة بالتطبيق ولا تعمل على Messenger Platform.
أي messaging_type ينبغي أن تستخدم الرسالة؟
يوضح النوع سبب إرسال الرسالة، ويحدد متى يُسمح بالإرسال. تذكر صفحة مراجع رسائل الصفحة لدى Meta أربع قيم:
- RESPONSE: ردّ على رسالة استلمتها الصفحة، ترويجية كانت أو لا، داخل نافذة المراسلة القياسية.
- UPDATE: رسالة تبادر الصفحة إلى إرسالها من تلقاء نفسها، ترويجية كانت أو لا، وتكون أيضًا داخل النافذة.
MESSAGE_TAG: رسالة غير ترويجية تُرسل بعد انتهاء النافذة، مع وسم يطابق حالة استخدام معتمدة.- UTILITY: رسالة خدمية مبنية على قالب معتمد، مثل تحديث طلب أو موعد.
ما الذي يمكن أن تحمله الرسالة؟
نص، أو كائن مرفق واحد يحمل type وpayload، فمرفقات الصورة والصوت والفيديو والملف تشير إلى رابط أو إلى attachment_id محفوظ، أما مرفقات القوالب فتحمل رسائل منظمة بأزرار. وتقبل نقطة النهاية (endpoint) نفسها هذه الحقول أيضًا:
- attachments: مصفوفة تضم حتى 30 صورة تُرسل كرسالة واحدة.
reply_toمع mid: ردّ على رسالة محددة سابقة، سواء من الشخص أو من الصفحة.quick_replies: حتى 13 زرًا فوق حقل الكتابة، وعنوان كل زر حتى 20 حرفًا.sender_action: مؤشر كتابة أو علامة مشاهدة أو تفاعل، يُرسل في طلب منفصل عن الرسالة نفسها.notification_type: القيمة الافتراضية REGULAR، أوSILENT_PUSHأوNO_PUSH.
ما الحد الأقصى لحجم المرفقات؟
يحدد دليل Meta لحفظ الأصول حدود الوسائط التي يجلبها Messenger Platform ويحتفظ بها: أصول حتى 25 MB، وصور حتى 8 MB عند رفعها من رابط، وصوت يُرسل بنوع Content-Type صوتي، وفيديو يُجلب خلال 75 ثانية. وضبط is_reusable على true يعيد attachment_id يمكن للصفحة المرسِلة وحدها إعادة استخدامه لمدة 90 يومًا، و POST /{page-id}/message_attachments يرفع الوسائط مسبقًا.
ما حدود معدل Send API؟
يحسب Meta الحدود لكل صفحة وبحسب نوع المحتوى. وتذكر صفحة مراجع رسائل الصفحة الرمز 613 بين أخطاء الإرسال، وهو يعني تجاوز حد الاستدعاءات، لذا يجب التباطؤ بدل إعادة المحاولة فورًا عند ظهوره:
- 300 استدعاء في الثانية لكل صفحة للرسائل التي تحتوي على نص وروابط وتفاعلات وملصقات.
- 10 استدعاءات في الثانية لكل صفحة للرسائل التي تحتوي على صوت أو فيديو.
- قد يُحدّ من الرسائل الكثيرة إلى خيط واحد بمعزل عن غيرها.
- استدعاءات Messenger API الإجمالية: 200 مرة عدد المستخدمين المتفاعلين، خلال 24 ساعة متدحرجة.
- فوق 40 رسالة في الثانية، يتوقف صندوق الوارد في الصفحة عن عرض الرسائل الجديدة، ولا تستطيع الصفحة الإرسال حتى ينخفض الحجم.
ما الأخطاء التي تعيدها Send API؟
يقرن جدول أخطاء Messenger لدى Meta كل رمز برمز فرعي يسمي السبب. هذه أكثر الأخطاء التي تواجهها الصفحة عند الإرسال:
- 10 مع 2018278 أو 2534022: الرسالة مُرسلة خارج النافذة المسموح بها.
- 10 مع 2018300: تطبيق آخر يتحكم في المحادثة.
- 100: معامل غير صالح، مثل معرّف مستلم خاطئ، والرمز الفرعي 2018001 يعني عدم العثور على مستخدم مطابق.
- 551: الشخص غير متاح، ربما لأنه حظر الصفحة أو عطّل حسابه، و200 مع 1545041 يعني أن هذا الشخص غير متاح الآن.
- 200 مع 2018028: لا يستطيع التطبيق مراسلة أشخاص خارج أدواره حتى تتم مراجعة
pages_messagingويصبح التطبيق متاحًا للعامة. - 10904: الرسائل معطّلة في إعدادات الصفحة.
كيف ترسل easyCoexistence عبرها؟
يأخذ send_social_dm الحقول account_id وrecipient_id للشخص، وهو sender.id في حدث رسائل مُعاد توجيهه، والنص، ثم يرسلها إلى /{page-id}/messages بالنوع messaging_type RESPONSE. والنتيجة هي رد Meta مع message_id، وعند رفض الإرسال يعود رمز الخطأ ورسالته من Meta. أما الوسائط وأزرار الرد السريع والقوالب ومؤشرات المرسِل فليست ضمن الأدوات: يرسل send_social_dm النص.
الأخطاء الشائعة
- إرسال مؤشر كتابة مع الرسالة. يريد Meta أن يكون sender_action وحده مع المستلم، والنص أو القوالب في طلب منفصل.
- إطلاق سيل من الرسائل على شخص واحد. قد يحدّ Meta من خيط واحد وحده، بمعزل عن حد الصفحة البالغ 300 استدعاء في الثانية.
- إرسال الصوت أو الفيديو بمعدل النص. الرسائل التي تحتوي صوتًا أو فيديو محدودة بـ 10 استدعاءات في الثانية لكل صفحة.
- إعادة استخدام attachment_id أقدم من 90 يومًا. تنتهي صلاحية معرّفات المرفقات المحفوظة، لذا ارفع الوسائط من جديد للحصول على معرّف جديد.
وتردّ الأتمتة على الرسائل الجديدة من تلقاء نفسها بنص ثابت أو بردّ من الذكاء الاصطناعي. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع أول 3 أيام مجانًا.
الأسئلة الشائعة
هل Messenger Send API مجانية؟
نعم، للرسائل العادية. تصف نظرة Meta العامة على Messenger Platform الاستخدام بأنه مجاني، فلا تدفع الصفحة التي ترد على من راسلها أي مبلغ مقابل كل رسالة؛ أما الرسائل التسويقية فتُحتسب رسومها لكل رسالة.
أي مهمة في الصفحة يحتاجها إرسال الرسالة؟
تطلب نظرة Meta العامة على Messenger رمز وصول للصفحة من شخص يستطيع تنفيذ المهمتين MESSAGING وMODERATE، مع منح إذن pages_messaging.
هل يستطيع easyCoexistence الرد بالصور على Messenger؟
ليس اليوم. يرسل send_social_dm النص، ولا ترسل أي أداة مرفقًا.
كم تكلف easyCoexistence لصفحة Facebook؟
كل صفحة تربطها تُحسب اتصالًا واحدًا، بسعر من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا بحسب عدد اتصالاتك، مع أول 3 أيام مجانًا.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في