التكامل مع Meta Graph API وInstagram: المصادقة والأذونات وWebhooks

ماذا ستخرج به من هذا المقال؟

عندما تقرر ربط نظامك — متجرًا أو منصة أو تطبيق مراسلة — بمنتجات Meta (فيسبوك وإنستغرام)، يبدأ كل شيء من سؤال واحد: كيف أصل إلى واجهة Graph API بشكل آمن ومستقر في الإنتاج؟ الواجهة أشبه بطبقة واحدة تُضاء خلفها كل المنتجات: صفحات فيسبوك، وإنستغرام، وحسابات الأعمال، والرسائل عبر ماسنجر، والإعلانات. هذا المقال يبني لك الاستيعاب الكامل بدءًا من تسجيل التطبيق، عبر تدفقات المصادقة وأذونات الوصول، وصولًا إلى جلب بيانات إنستغرام ونشر المحتوى وتلقي الأحداث بالـ Webhooks.

ستتعرف على الفرق بين رموز الوصول قصيرة وطويلة الأمد، وكيف تحوّل رمز العميل إلى رمز طويل من دون تدخل يدوي، وكيف تتعامل مع صفحة `paging.cursors` عند جلب القوائم، وكيف تشترك في أحداث التطبيق وتستقبلها بشكل موثوق. كل خطوة مرفقة بمثال عملي واعتبارات أمان تُطبق قبل النشر.

لماذا تُبنى كل شيء على Graph API؟

قبل ماسنجر بلاستيكي كان لكل منتج واجهة مختلفة وصعبة. قررت Meta توجيه كل شيء إلى جذر موحد: أجوبة HTTP تستقر على `graph.facebook.com/v21.0`. المعنى العملي: ما تتعلمه لصفحة فيسبوك هو نفسه لإنستغرام ولماسنجر لحسابات الأعمال؛ الاختلاف في الأذونات المستَعمَلة وفي شكل الحمولة التي ترجعها كل عقدة.

بنية الرابط غالبًا: /{node-id} للقراءة، و/{node-id}/{edge} للعلاقات مثل `me/accounts` أو `{ig-user-id}/media`، و/{node-id}/{edge} مع POST للنشر مثل `{ig-user-id}/media` ثم `{ig-user-id}/media_publish`. منخفض المستوى، لكنه ثابت التصميم وموثّق جيدًا.

المصادقة: التطبيقُ أولًا ثم المستخدم ثم الرمز

كل شيء يبدأ من لوحة مطوري Meta: تنشئ تطبيقًا، وتضيف المنتج المناسب (Instagram API أو Messenger أو Graph API عادي). ثم تنتقل إلى خطوات المصادقة التي تمرّ بثلاث طبقات:

• طبقة التطبيق: app_id وapp_secret. لا تخرجهما من الخادم أبدًا، وخزّنهما في متغيرات بيئة لا في سجلات Git.


• طبقة المستخدم: بعد موافقة المستخدم (والتسجيل في أوقات الحراسة للـ OAuth) تقوم Meta بتحويلك إلى access_token قصير الأمد صالح لساعات إلى يومين.


• طبقة الرمز: للاستخدام طويل الأمد نستبدل الرمز القصير برمز طويل (60-90 يومًا) عبر استدعاء خاص، ثم نجدّده قبل انتهائه بواسطة مخطّط زمني — لا نتركه ينتهي لأن المستخدم سيعيد التفويض.

// تبادل الرمز القصير برمز طويل الأمد

$url = 'https://graph.facebook.com/v21.0/oauth/access_token?' . http_build_query([

    'grant_type'        => 'fb_exchange_token',

    'client_id'         => env('META_APP_ID'),

    'client_secret'     => env('META_APP_SECRET'),

    'fb_exchange_token' => $shortLivedToken,

]);

الأذونات: أقل نطاق يكمل العمل

مبدأ الحرية: كل منتج يحتاج أذونات (permissions). للمراسلة: pages_messaging. لقراءة صفحاتك: pages_show_listوpages_read_engagement. لإنستغرام: instagram_basicوinstagram_content_publishوقراءة الرسائل عبر pages_messaging مع خاصية الحساب المتصل. لا تضيف أذونات لا تحتاجها: كل إذن يوسّع سطح الهجوم ويرفع نسبة رفض المراجعة.

قراءة بيانات إنستغرام وتنظيم الصفحات

لاسترداد صفحتك أو حسابات إنستغرام المتاحة، تقرأ عقدة `me` مع الإذن `pages_show_list`: تُرجع لك قائمة الصفحات مع access_token خاصة بكل صفحة. من الصفحة تحصل على instagram_business_account المرتبط إن وُجد.

GET /me?fields=id,name,accounts{{business_management}}

→ accounts.data[0]: { id, name, access_token, instagram_business_account: { id } }

التنقل عبر الصفحات (Pagination)

عقد مثل `{ig-user-id}/media` ترجع 25 عنصرًا افتراضيًا مع كائن paging. المفتاح paging.cursors.after هو مؤشر قاعدة يُمرَّر كبارامتر after في الطلب التالي. لا تفترض ترقيمًا صفحاتيًا، بل تتبّع المؤشر حتى يصل data فارغًا.

نشر محتوى على إنستغرام ديناميكيًا

النشر على حساب عمل (Professional/ Business) يتم في خطوتين: أولًا ترفع الميديا إلى {ig-user-id}/media (صورة أو فيديو أو Reel) وتستلم creation_id، ثم تنشر بالاستدعاء /media_publish بذلك المعرّف. نص التسمية والهاشتاغات تمرّ ضمن حقل caption في مرحلة الرفع.

معالجة إنشاءات الوسائط غير الجاهزة

أحيانًا تبقى حالة الميديا IN_PROGRESS لدقائق (خصوصًا الفيديو). اقرأ حالة الصياغة عبر /{creation_id}?fields=status,status_code وأعد المحاولة بفاصل تصاعدي حتى تصبح FINISHED، وتجاهل ERROR سجّل السبب من status_code.

الاستماع للأحداث: الـ Webhooks عبر تطبيقك

بدل أن تجلب الرسائل والتنبيهات كل ثانية، تشترك تطبيقك في أحداث. في لوحة التطبيق تضبط Callback URL مع Verify Token تختاره بنفسك. عند الطلب، ترجع `hub.challenge` فقط إذا طابق `hub.verify_token` قيمتك، عندها تكتمل الاشتراكات الموجودة لأحداث في مثل الرسائل الجديدة.

• طلبات GET: التحقق من الاشتراك. استجب بـ hub.challenge كـ text/plain.


• طلبات POST: الأحداث. تحقق من X-Hub-Signature-256 باستخدام الـ App Secret باستخدام خوارزمية HMAC-SHA256 قبل المعالجة.

$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';

$expected  = 'sha256=' . hash_hmac('sha256', $rawBody, env('META_APP_SECRET'));

if (!hash_equals($expected, $signature)) { abort(401); }

معدلات الاستخدام ومعالجة الأخطاء

الواجهة تعمل بنظام حصص (Rate Limits) على مستوى التطبيق والمستخدم. عند تجاوز الحد ترجع error.code بقيم مثل 4 (App-to-Page) و613 (مؤقت). اعتمد إعادة المحاولة بفاصل تصاعدي مع احترام x-business-use-case-usage الذي ترجعه الرؤوس، وأعد المحاولة للمخارج المؤقتة فقط (HTTP 500/504 أو أخطاء 4/613)، ولا تُعد لـ 400 أبدًا لأنها لن تنجح.

قائمة تحقق قبل الإنتاج

• الرموز القصيرة والطويلة مخزّنة في النظام مع مخطّط تجديد قبل الانتهاء.


• الأذونات حدّدتها بالحد الأدنى وراجعت حالة التطبيق ليست في وضع التطوير.


• الـ Webhook متحقق منه بتوقيع HMAC ويعيد 200 بسرعة مع طابعة أحداث.


• التفويض يمر عبر OAuth كامل، ولا رموز في السجلات أو Git.


• إعادة المحاولة تصاعدية وتفصل الأخطاء الدائمة عن المؤقتة.


• حالة إنستغرام مرتبطة بالصفحة وكود اختبر النشر والفيديو IN_PROGRESS.

الأسئلة الشائعة

لماذا رموز ماسنجر أصبحت صفحة الوصول للرسائل؟

لأن الرسائل تعمل عبر عقدة الصفحة/page مع إذن pages_messaging؛ رمز الصفحة (Page Token) هو الذي يحمل التوقيع ولا يحمل رمز المستخدم.

كيف أعرّف أن الرمز مازال ساريًا؟

استدعي /me برمز ساري؛ أي error.code=190 يعني انتهاء الصلاحية أو إلغاء. الفحص الدوري مع التجديد المبكر هو الممارسة السليمة.

هل يعمل ذلك للملكية الواحدة (Single Business)؟

نعم. الأدوات مثل Business Manager تساعد في جلب رموز صفحات متعددة تحت منظومة واحد، لكن البنية مباشرة عبر OAuth عادية من التطبيق الواحد.

الخلاصة

الخطوة التالية

جربتُلك الواجهة ببيانات تجريبية قبل ربط حساب حقيقي: أنشئ تطبيقًا في وضع التطوير، أضف المستخدم التجريبي، وبنِ تدفق OAuth كاملًا. في المقال القادم ننتقل إلى WhatsApp Business API وهو بنفس الركيزة لكن بمنطق مختلف للرسائل والقوالب.

flowchart LR

    A["طلب العميل"]

    B["مصادقة وتوثيق"]

    C["طبقة التكامل"]

    D["الخدمة الخارجية"]

    E["التحقق والتدقيق"]

    A --> B

    B --> C

    C --> D

    D --> E