بدء الاستخدام

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

قبل البدء

ستحتاج إلى الوصول إلى ما يلي:

• حساب Instagram احترافي
• صفحة فيسبوك مرتبطة بهذا الحساب
• حساب مطوّر Meta يمكنه إجراء المهمة MODERATE في تلك الصفحة
• تطبيق Meta تم إنشاؤه بحالة استخدام تسجيل دخول فيسبوك ومع تكوين الإعدادات الأساسية

المطوّرون الجدد في منصة Messenger

• اتبع الدليل التفصيلي أدناه حول كيفية إنشاء رمز وصول الصفحة وإعداد أحداث webhooks.
• تعرف على ميزات المنصة المتنوعة واستخدمها بما يناسب احتياجاتك.

المطوّرون الذين يتمتعون بخبرة مسبقة على منصة Messenger

• تتشابه مفاهيم رمز الوصول مع مفاهيم أحداث webhooks. وسيتطلب دعم واجهة Messenger API في Instagram توفير instagram_manage_messages في رمز وصول الصفحة وأحداث webhooks لموضوع Instagram التي تم الاشتراك فيها.
• تتشابه معظم الميزات مع ميزات واجهة Messenger API. ويمكنك مراجعة التفاصيل الخاصة بقائمة الميزات واستخدامها بما يناسب احتياجاتك.

دفق تسجيل الدخول

يمكنك استخدام تسجيل دخول فيسبوك أو تسجيل دخول الأعمال في Instagram لطلب الأذونات التي تحتاج إليها من مستخدمي التطبيق.

يتيح دفق تسجيل دخول النشاط التجاري في Instagram للشخص إكمال ما يلي أثناء التواجد في دفق تسجيل الدخول:

• تحويل حساب Instagram إلى حساب احترافي على Instagram
• إنشاء صفحة فيسبوك للنشاط التجاري
• ربط هذه الصفحة بالحساب الاحترافي على Instagram

لتنفيذ تسجيل دخول الأعمال في Instagram، تفضل بزيارة دليل تسجيل دخول الأعمال في Instagram ثم عُد إلى هذا الدليل.

1. الحصول على رمز وصول مستخدم

تأكد من أنك سجّلت الدخول إلى حساب المطوّر على فيسبوك، ثم قم بالوصول إلى تطبيقك وتشغيل نموذج تسجيل دخول فيسبوك المشروط. تذكّر أنه يجب أن يكون حساب المطوّر على فيسبوك قادرًا على تنفيذ المهام بمستوى وصول "متوسط" على الأقل على صفحة فيسبوك المرتبطة بحساب Instagram الذي تريد الاستعلام عنه.

بمجرد تشغيل تسجيل الدخول المشروط، انقر على "موافق" لمنح تطبيقك الأذونات instagram_basic وinstagram_manage_messages وpages_manage_metadata.

يجب أن تقوم واجهة API بإرجاع رمز وصول مستخدم. واحصل على الرمز المميز بحيث يمكن لتطبيقك استخدامه في بعض الاستعلامات التالية. إذا كنت تستخدم مستكشف Graph API، فسيتم الحصول عليه تلقائيًا وعرضه في الحقل رمز الوصول من أجل الرجوع إليه:

2. الحصول على صفحات المستخدم

استعلم عن نقطة النهاية GET /me/accounts (تتحول هذه إلى GET /{user-id}/accounts بحيث تعمل على تنفيذ طلب GET في عقدة مستخدم Facebook بناءً على رمز الوصول المتوفر لديك).

curl -i -X GET \
 "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"

يجب أن يؤدي ذلك إلى إرجاع مجموعة من صفحات Facebook بحيث يمكن لمستخدم Facebook الحالي تنفيذ المهام MANAGE أو CREATE_CONTENT أو MODERATE أو ADVERTISE بها:

{
  "data": [
    {
      "access_token": "EAAJjmJ...",
      "category": "App Page",
      "category_list": [
        {
          "id": "2301",
          "name": "App Page"
        }
      ],
      "name": "Metricsaurus",
      "id": "134895793791914",  // capture the Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ]
}

احصل على معرف صفحة Facebook المرتبط بحساب Instagram الذي تريد الاستعلام عنه. تذكّر أنه يمكن لمستخدمي تطبيقك تنفيذ مهام بصفحات متعددة، لذلك سيتعين عليك في نهاية الأمر تقديم منطق يمكنه تحديد معرف الصفحة الصحيح المطلوب الحصول عليه (أو تصميم واجهة مستخدم حيث يمكن لمستخدمي تطبيقك تحديد الصفحة الصحيحة نيابة عنك).

3. الحصول على رمز وصول الصفحة

لتنفيذ الاستدعاءات المتنوعة في API المراسلة في Instagram، ستحتاج إلى استخدام رمز وصول الصفحة (PAT) ذي الصلة والخاص بحساب Instagram الاحترافي المعني الذي تم منحه مسبقًا عبر دفق تسجيل دخول فيسبوك.

أرسل طلب GET إلى نقطة النهاية /{page-id} باستخدام رمز وصول المستخدم. على سبيل المثال:

curl -i -X GET "https://graph.facebook.com/{page-id}?
  fields=access_token&
  access_token={user-access-token}"  

عند نجاح العملية، يحصل تطبيقك على هذه الاستجابة:

{
  "access_token":"{page-access-token}",
  "id":"{page-id}"              
}  

• إذا كنت تستخدم رمز وصول مستخدم قصير الأجل، فسيكون رمز وصول الصفحة صالحًا لمدة ساعة واحدة فقط.
• إذا كنت تستخدم رمز وصول مستخدم طويل الأجل، فلن يتوفر لدى رمز وصول الصفحة تاريخ انتهاء صلاحية.

لإنشاء رمز وصول صفحة طويل الأجل، يمكنك اتباع الدليل هنا.

3أ. الحصول على رمز وصول الصفحة عبر أداة لوحة معلومات مطوّر Instagram

بشكل اختياري، إذا كنت تمتلك الأصول (حساب Instagram وصفحة FB) التي تريد إعدادها لاستخدام دعم Messenger API في Instagram، فيمكنك الاستفادة من أداة الإعداد في Instagram ضمن لوحة معلومات تطبيق المطوّر للسماح لك بإعداد رموز وصول الصفحة وأحداث Webhooks بسهولة. يمكنك العثور على الأداة ضمن لوحة معلومات تطبيق المطوّر ← Messenger ← إعدادات Instagram. لا تزال الطريقة الحالية لتكوين رموز الوصول وحدث webhook تعمل، ولكن هذه الأداة ستمنحك طريقة أسهل لإعداد بيئتك.

4. تمكين إعدادات الأدوات المرتبطة بالتحكم في الرسالة

لإدارة رسائل Instagram عبر API، ستحتاج حسابات Instagram الاحترافية إلى تمكين زر التبديل في الأدوات المرتبطة والموجودة ضمن إعدادات التحكم في الرسالة.

5. الحصول على كائنات البريد الوارد في حساب Instagram الاحترافي

يمكنك استخدام معرف الصفحة الذي حصلت عليه ورمز وصول الصفحة (PAT) للاستعلام عن نقطة النهاية GET /{page-id}/conversations?platform=instagram:

curl -i -X GET \
 "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"  

يجب أن يؤدي ذلك إلى إرجاع معرفات كل كائنات سلاسل الرسائل لدى مستخدم Instagram:

{
  "data": [
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0"
    }
}

إذا كان بإمكانك تنفيذ هذا الاستعلام النهائي بنجاح، فيجب أن تكون قادرًا على إجراء استعلامات باستخدام إحدى نقاط نهاية دعم Messenger API في Instagram، وما عليك سوى الرجوع إلى الدلائل والمراجع المتنوعة التي نوفرها لمعرفة ما يمكن أن تفعله كل نقطة نهاية والأذونات التي تتطلبها.

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

• قم بتطوير تطبيقك على نطاق أوسع بحيث يمكنه استخدام أي نقاط نهاية أخرى يحتاج إليها بنجاح، وتتبع الأذونات التي تطلبها كل نقطة نهاية
• أكمل إعداد حدث webhook بحيث يمكن استلام الإشعارات في الوقت الفعلي عندما يرسل المستخدم رسالة إلى حساب Instagram الاحترافي.
• أكمل عملية مراجعة التطبيقات واطلب اعتماد كل الأذونات التي سيحتاج إليها تطبيقك بحيث يمكن لمستخدمي التطبيق منحها بينما يكون تطبيقك في مرحلة الإنتاج.