‏منصة Instagram‏

نشر المحتوى

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

بدءًا من 1 يوليو 2023، ستتم مشاركة كل مقاطع فيديو الموجز الفردية المنشورة عبر API نشر المحتوى على Instagram كريلز.

المتطلبات

رموز الوصول

يجب أن تتضمن جميع الطلبات رمز وصول المستخدم الخاص بمستخدم التطبيق.

الأذونات

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

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

الخادم العام

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

تصريح النشر على الصفحة

لا يمكن النشر على الحسابات الاحترافية في Instagram المرتبطة بصفحة تتطلب توفير تصريح بالنشر على الصفحة (PPA) حتى يتم إكمال تصريح PPA.

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

التقييدات

  • يُعد JPEG هو تنسيق الصور الوحيد المدعوم. لا يتم دعم تنسيقات JPEG الموسّعة، مثل MPO وJPS.
  • تكون علامات التسوق غير مدعومة.
  • تكون إشارات المحتوى المرتبط بعلامة تجارية غير مدعومة.
  • تكون الفلاتر غير مدعومة.
  • النشر على Instagram TV غير مدعوم.

لمزيد من التقييدات، ارجع إلى كل مرجع نقطة نهاية.

تقييد معدلات الاستدعاء

يتم تقييد حسابات Instagram عند 50 منشورًا يتم نشرها بواسطة API خلال فترة تستغرق 24 ساعة. تُعد الإعلانات الدوّارة منشورًا فرديًا. يتم فرض هذا التقييد على نقطة النهاية POST /{ig-user-id}/media_publish عند محاولة نشر حاوية وسائط. نوصي بأن يفرض تطبيقك أيضًا تقييدًا لمعدلات استدعاء النشر، خاصةً إذا كان تطبيقك يتيح لمستخدمي التطبيق جدولة المنشورات المطلوب نشرها في المستقبل.

للتحقق من استخدام تقييد معدلات الاستدعاء الحالي للحساب الاحترافي في Instagram، يمكنك الاستعلام عن نقطة النهاية GET /{ig-user-id}/content_publishing_limit.

نقاط النهاية

تتكون API من نقاط النهاية التالية: ويمكنك الرجوع إلى المستند المرجعي لكل نقطة نهاية للحصول على متطلبات الاستخدام.

منشورات الوسائط الفردية

تتكون عملية نشر صورة أو فيديو أو قصة أو مقطع ريلز فردي من خطوتين:

  1. استخدم نقطة النهاية POST /{ig-user-id}/media لإنشاء حاوية من الصورة أو الفيديو الذي تتم استضافته على الخادم العام.
  2. استخدام نقطة النهاية POST /{ig-user-id}/media_publish لنشر هذه الحاوية.

الخطوة 1 من 2: إنشاء حاوية

لنفترض أنه لديك صورة في...

https://www.example.com/images/bronz-fonz.jpg

... وتريد نشرها مع تضمين الهاشتاج "‎#BronzFonz" في الشرح التوضيحي. أرسل طلبًا إلى نقطة النهاية POST /{ig-user-id}/media:

عينة من الطلب

POST https://graph.facebook.com/v19.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

يؤدي هذا الطلب إلى إرجاع معرف حاوية الصورة.

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

{
  "id": "17889455560051444"  // IG Container ID
}

الخطوة 2 من 2: نشر حاوية

استخدم نقطة النهاية POST /{ig-user-id}/media_publish لنشر معرف الحاوية الذي تم إرجاعه في الخطوة السابقة.

عينة من الطلب

POST https://graph.facebook.com/v19.0/17841400008460056/media_publish ?creation_id=17889455560051444

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

{
  "id": "17920238422030506" // IG Media ID
}

منشورات الإعلانات الدوّارة

يمكنك نشر ما يصل إلى 10 صور أو مقاطع فيديو أو مزيج من الاثنين في منشور فردي (منشور إعلان دوّار). تتكون عملية نشر الإعلانات الدوّارة من ثلاث خطوات:

  1. استخدم نقطة النهاية POST /{ig-user-id}/media لإنشاء حاويات عنصر فردي لكل صورة وفيديو سيظهر في الإعلان الدوّار.
  2. استخدم نقطة النهاية POST /{ig-user-id}/media مرة أخرى لإنشاء حاوية إعلان دوّار فردية للعناصر.
  3. استخدم نقطة النهاية POST /{ig-user-id}/media_publish لنشر حاوية الإعلان الدوّار.

تُعد منشورات الإعلان الدوّار منشورًا فرديًا ضمن نطاق تقييد معدلات الاستدعاء للحساب.

التقييدات

  • لا يمكن ترويج الإعلانات الدوّارة.
  • يتم تقييد الإعلانات الدوّارة عند 10 صور أو مقاطع فيديو أو مزيج من الاثنين.
  • يتم اقتصاص الصور الدوّارة كلها استنادًا إلى الصورة الأولى في الإعلان الدوّار، مع نسبة العرض إلى الارتفاع الافتراضية 1:1.

الخطوة 1 من 3: إنشاء حاوية العنصر

استخدم نقطة النهاية POST /{ig-user-id}/media لإنشاء حاوية عنصر للصورة أو الفيديو الذي سيظهر في الإعلان الدوّار. يمكن أن تتضمن الإعلانات الدوّارة حتى 10 صور أو مقاطع فيديو أو مزيجًا من الاثنين.

POST /{ig-user-id}/media

المعلمات

المعلمات التالية مطلوبة. يمكنك الرجوع إلى مرجع نقطة النهاية POST /{ig-user-id}/media لمعرفة المعلمات الإضافية المدعومة.

  • is_carousel_item — يتم التعيين إلى true. ويشير إلى أن الصورة أو الفيديو سيظهر في الإعلان الدوّار.
  • image_url — (صور فقط) تمثل مسار الصورة. وسيتم إجراء طلبات cURL للصورة لديك باستخدام عنوان URL الذي تم إدخاله، لذا يجب أن تتوفر هذه الصورة على خادم عام.
  • media_type — (مقاطع الفيديو فقط) يتم التعيين إلى VIDEO. ويشير إلى أن الوسائط عبارة عن مقطع فيديو.
  • video_url — (مقاطع الفيديو فقط) تمثل مسار الفيديو. وسيتم إجراء طلبات cURL للفيديو لديك باستخدام عنوان URL الذي تم إدخاله، لذا يجب أن يتوفر هذا الفيديو على خادم عام.

إذا كانت العملية ناجحة، فستُرجع API معرف حاوية العنصر الذي يمكن استخدامه عند إنشاء حاوية إعلان دوّار.

كرّر هذه العملية لكل صورة أو فيديو يجب أن يظهر في الإعلان الدوّار.

عينة من الطلب

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

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

{
  "id": "17899506308402767"
}

الخطوة 2 من 3: إنشاء حاوية إعلان دوّار

استخدم نقطة النهاية POST /{ig-user-id}/media لإنشاء حاوية إعلان دوّار.

POST /{ig-user-id}/media

المعلمات

المعلمات التالية مطلوبة. يمكنك الرجوع إلى مرجع نقطة النهاية POST /{ig-user-id}/media لمعرفة المعلمات الإضافية المدعومة.

  • media_type — يتم التعيين إلى CAROUSEL. ويشير إلى أن الحاوية مخصصة لإعلان دوّار.
  • children — تمثل مصفوفة تضم حتى 10 معرفات حاوية لكل صورة أو فيديو يجب أن يظهر في الإعلان الدوّار المنشور. يمكن أن تتضمن الإعلانات الدوّارة حتى 10 صور أو مقاطع فيديو أو مزيجًا من الاثنين.

عينة من الطلب

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

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

{
  "id": "18000748627392977"
}

الخطوة 3 من 3: نشر حاوية إعلان دوّار

استخدم نقطة النهاية POST /{ig-user-id}/media_publish لنشر حاوية إعلان دوّار (منشور إعلان دوّار). يتم تقييد الحسابات عند 50 منشورًا يتم نشرها خلال فترة 24 ساعة. يُعد نشر إعلان دوّار منشورًا فرديًا.

POST /{ig-user-id}/media_publish

المعلمات

يلزم توفير المعلمات التالية.

  • creation_id — تمثل معرف حاوية الإعلان الدوّار.

إذا كانت العملية ناجحة، فستُرجع API معرف وسائط IG لألبوم الإعلان الدوّار.

عينة من الطلب

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

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

{
  "id": "90010778390276"
}

منشورات ريلز

مقاطع ريلز هي مقاطع فيديو قصيرة مؤهلة للظهور في علامة التبويب مقاطع ريلز ضمن تطبيق Instagram إذا كانت تفي بمواصفات معينة وتم تحديدها بواسطة الخوارزمية لدينا. لنشر مقطع ريلز، اتبع الخطوات المطلوبة لنشر منشور وسائط فردي وقم بتضمين المعلمة media_type=REELS إلى جانب مسار الفيديو باستخدام المعلمة video_url.

لاحظ أن ريلز ليست نوع وسائط جديد، على الرغم من تعيين المعلمة media_type=REELS عند نشر مقطع ريلز. إذا نشرت مقطع ريلز ثم طلبت الحقل media_type المرتبط به، فسيتم إرجاع القيمة VIDEO. لاكتشاف ما إذا كان قد تم تحديد فيديو تم نشره كمقطع ريلز، اطلب الحقل media_product_type المرتبط به بدلاً من ذلك.

يمكنك استخدام عينة الرمز المتوفرة على GitHub (insta_reels_publishing_api_sample) للتعرف على كيفية نشر مقاطع ريلز على Instagram.

لجعل الأمر أكثر ملاءمة للمطوّرين، نشرت Meta المجموعة الكاملة من استدعاءات Graph API في ريلز من Instagram على منصة Postman API. لمزيد من المعلومات، راجع تشكيلات Postman في ريلز من فيسبوك وريلز من Instagram.

لمزيد من المعلومات حول ريلز، راجع وثائق مطوّر ريلز.

منشورات القصة

يمكن لحسابات الأعمال فقط نشر القصص باستخدام API نشر المحتوى في الوقت الحالي.

القصص هي مقاطع فيديو وصور يتم نشرها كقصص IG على Instagram. لنشر قصة ما، اتبع الخطوات ذاتها المطلوبة لنشر منشور وسائط فردي وقم بتضمين المعلمة media_type=STORIES إلى جانب مسار الصورة/الفيديو باستخدام المعلمة image_url أو video_url.

ملاحظة: القصص لا تُعد نوع وسائط جديد، على الرغم من إعداد المعلمة media_type=STORIES عند نشر قصة. إذا نشرت قصة ثم طلبت الحقل media_type، فسيتم إرجاع القيمة كـ IMAGE/VIDEO. لاكتشاف ما إذا كان قد تم تحديد الصورة/الفيديو الذي تم نشره كقصة، اطلب الحقل media_product_type المرتبط به بدلاً من ذلك.

إشارات المساهمة

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

عينة من الطلب

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

ملاحظات

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

إشارات الموقع

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

التقييدات

من أجل أن تكون مؤهلاً للإشارة، يجب أن تحتوي الصفحة على بيانات موقع تتضمن خطوط العرض وخطوط الطول.

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

بمجرد الحصول على معرف الصفحة، قم بتعيينه إلى المعلمة location_id عند نشر حاويات عنصر الوسائط الفردية أو الإعلان الدوّار.

عمليات الإشارة إلى المنتجات

يمكنك نشر منشورات الوسائط الفردية ومنشورات الإعلانات الدوَّارة التي تتضمن إشارات منتجات التسوق على Instagram. يمكنك الرجوع إلى الدليل الإشارة إلى المنتجات للتعرف على كيفية القيام بذلك.

إشارات المستخدم

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

للإشارة إلى مستخدمين في صورة، اتبع خطوات منشورات الوسائط الفردية أعلاه، ولكن عند إنشاء حاوية الوسائط، احرص على تضمين المعلمة user_tags ومصفوفة من الكائنات تشير إلى مستخدمي Instagram الذين تمت الإشارة إليهم في الصورة بالإضافة إلى إحداثيات x/y ضمن الصورة ذاتها.

عينة من الطلب

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

يُرجع هذا الطلب معرف الحاوية الذي تنشره بعد ذلك باستخدام نقطة نهاية نشر وسائط مستخدم IG.

ملاحظات

  • يجب أن تكون قيمة user_tags عبارة عن مصفوفة من كائنات بتنسيق بلغة JSON.
  • يمكنك فقط الإشارة إلى المستخدمين الذين لديهم حسابات Instagram عامة.
  • يجب أن يحتوي الكائن على كل الخصائص الثلاث وهي (username وx وy) لكل مستخدم.
  • يجب أن تكون القيمتان x وy عبارة عن أرقام float تنشأ من أعلى يمين الصورة بنطاق يتراوح من 0.0 إلى 1.0.
  • يمكن استخدام إشارات المستخدم مع الصور الموجودة في الإعلانات الدوّارة.

استكشاف الأخطاء وإصلاحها

إذا كان بإمكانك إنشاء حاوية لفيديو ولكن لا تقوم نقطة النهاية POST /{ig-user-id}/media_publish بإرجاع معرف الوسائط المنشورة، فيمكنك الحصول على حالة نشر الحاوية من خلال الاستعلام عن نقطة النهاية GET /{ig-container-id}?fields=status_code. وستعمل نقطة النهاية هذه على إرجاع أحد العناصر التالية:

  • EXPIRED — لم يتم نشر الحاوية في غضون 24 ساعة وانتهت صلاحيتها.
  • ERROR — فشلت الحاوية في إكمال عملية النشر.
  • FINISHED — تكون الحاوية وكائن الوسائط التابع لها جاهزين للنشر.
  • IN_PROGRESS — لا تزال الحاوية قيد عملية النشر.
  • PUBLISHED — تم نشر كائن وسائط الحاوية.

نوصي بالاستعلام عن حالة الحاوية مرة واحدة في الدقيقة ولمدة لا تزيد عن 5 دقائق.

الأخطاء

يمكنك الاطّلاع على مرجع رموز الخطأ.