تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

خطاف الويب (webhook) messaging_referral في Instagram: روابط ig.me وإحالات الإعلانات

يُعلم حقل messaging_referral في webhook الخاص بـ Instagram التطبيق عندما يفتح شخص لديه محادثة مسبقة مع الحساب المهني رابط ig.me يحمل معامل ref. يحتوي الحدث على كائن referral على المستوى الأعلى: ref وهي قيمة المعامل، والحقل source قيمته SHORTLINKS، والحقل type قيمته OPEN_THREAD. أما ref في محادثة جديدة فيصل ضمن حدث messages أو messaging_postbacks بدلاً من ذلك.

يشترك easyCoexistence في التعليقات والرسائل والإشارات لكل حساب Instagram متصل، لذلك تصل قيمة ref في أول رسالة من محادثة جديدة، وإحالة إعلان Click-to-Direct، إلى endpoint الخاصة بك عبر HTTPS داخل الرسالة المباشرة المُمرّرة، موقعة بسر ذلك الحساب.

2,083

أقصى طول لمعامل ref في روابط ig.me، ويقبل الحروف والأرقام والشرطات والشرطات السفلية وعلامة المساواة فقط.

OPEN_THREAD

نوع الإحالة لروابط ig.me، ويستخدمه إعلان Click-to-Direct أيضاً، والحقل source فيه ADS بدلاً من ذلك.

24 hours

المدة الزمنية التي يملكها التطبيق للرد بعد إحالة في محادثة قائمة، وتعيد هذه الإحالة ضبط نافذة الرسائل القياسية.

7 days

مدة النافذة التي يمكن أن تستمر من أول رسالة تُرسل بعد النقر على إعلان Click-to-Direct، ويمكن أن تصل إلى 7 أيام.

Instagram Web

أين لا تُدعم روابط ig.me، وفق دليل Meta الخاص بها.

متى يُرسل messaging_referral؟

عندما يملك شخص محادثة قائمة مع الحساب المهني، ويفتح رابط ig.me يحمل معامل ref. يفتح Instagram المحادثة الموجودة، وتُرسل Meta الإحالة وحدها دون أي رسالة. ويختلف المكان الذي تصل فيه الإحالة بحسب المحادثة وما يفعله الشخص:

Existing threadmessaging_referral: a referral object beside sender, with no message.
New thread, ice breaker tappedmessaging_postbacks: postback.referral beside title and payload.
New thread, message typedmessages: message.referral beside mid.
Click-to-Direct admessages: message.referral with source ADS, ad_id and ads_context_data.

كيف يبدو إشعار الإحالة؟

حدث رسائل يقع فيه كائن referral إلى جانب الحقول sender وrecipient وtimestamp، دون رسالة أو postback حوله. يعطي دليل ig.me من Meta قيم الإحالة، داخل الغلاف نفسه الذي تُرسل فيه أحداث رسائل Instagram الأخرى:

A messaging_referral notification
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "referral": {
            "ref": "<REF_PARAMETER_VALUE>",
            "source": "SHORTLINKS",
            "type": "OPEN_THREAD"
          }
        }
      ]
    }
  ]
}

ما معنى كل حقل؟

الحقول التي توثقها Meta لإحالة ig.me، من الخارج إلى الداخل:

  • sender.id: المعرّف ضمن نطاق Instagram للشخص الذي فتح الرابط. أما recipient.id والحقل entry[].id فهما معرّف الحساب المهني.
  • referral.ref: قيمة معامل ref في الرابط، كما حمله الرابط تماماً.
  • referral.source: القيمة SHORTLINKS في أمثلة Meta لروابط ig.me. يكتبها أحد جداول دليل Instagram Messaging بصيغة SHORTLINK، وتعرض صفحة الأمثلة فيه قيمة نائبة.
  • referral.type: القيمة OPEN_THREAD التي تستخدمها Meta لإحالات ig.me.
  • timestamp: وقت تشغيل الحدث، ويكون بالمللي ثانية في أمثلة Meta كما هو موضح.

كيف تبني رابط ig.me مع ref؟

بالصيغة https://ig.me/<USERNAME>?ref=<VALUE>، حيث USERNAME هو اسم المستخدم للحساب المهني، وذلك في دليل Instagram Login من Meta. أما دليل Instagram Messaging فيكتبها https://ig.me/m/<USERNAME>. يمكن أن يبلغ طول ref 2,083 حرفاً من الحروف والأرقام والشرطات والشرطات السفلية وعلامات المساواة. تقترح Meta استخدام ref لتتبع القنوات، أو لربط الشخص بجلسة في تطبيق آخر، أو لتوجيهه إلى محتوى محدد، وتوصي بوضع كاسرات الجليد (ice breakers) لكل منها ref خاص بها للمحادثات الجديدة.

أين تصل إحالات الإعلانات؟

في الرسائل. يُنتج الشخص الذي ينقر على إعلان يفتح Instagram Direct ويرسل رسالة حدث messages يحتوي message.referral، وفيه ref الإعلان إن وُضع، وad_id، وsource بقيمة ADS، وtype بقيمة OPEN_THREAD، وads_context_data بعنوان الإعلان والصورة photo_url أو الفيديو video_url الذي نُقر عليه. وتوثق صفحات Instagram في Meta الحدث messaging_referral لروابط ig.me فقط.

A Click-to-Direct ad referral, inside messages
"message": {
  "mid": "<MESSAGE_ID>",
  "referral": {
    "ref": "<AD_REF_IF_SET>",
    "ad_id": "<AD_ID>",
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ads_context_data": {
      "ad_title": "<AD_TITLE>",
      "photo_url": "<IMAGE_URL_CLICKED>",
      "video_url": "<THUMBNAIL_URL_FOR_THE_AD_VIDEO>"
    }
  }
}

هل تفتح الإحالة نافذة الرسائل؟

نعم، في المحادثة القائمة. يذكر دليل ig.me من Meta أن الإحالة تعيد ضبط نافذة الرسائل القياسية لمدة 24 ساعة، فيمكن للتطبيق الرد خلال 24 ساعة من الحدث. ويمكن لأول رسالة تُرسل بعد النقر على إعلان Click-to-Direct أن تفتح نافذة تصل إلى 7 أيام من تلك الرسالة. للرد استخدم POST /<IG_ID>/messages مع تحديد recipient.id بقيمة sender.id الخاصة بالحدث.

هل تمرر easyCoexistence الإحالات؟

تمرر الإحالات التي تأتي ضمن الرسائل. يشترك كل حساب Instagram متصل في التعليقات والرسائل والإشارات، لذلك تصل قيمة ref في أول رسالة من محادثة جديدة، وإحالة إعلان Click-to-Direct، إلى نقطة النهاية (endpoint) الخاصة بك داخل رسالة مباشرة (DM) مُمرّرة، بصيغة message.referral. أما messaging_referral للمحادثات القائمة، وmessaging_postbacks للنقر على كاسرات الجليد، فهما حقلان منفصلان تسلمهما Meta إلى التطبيقات المشتركة فيهما.

الأخطاء الشائعة

  • انتظار messaging_referral في محادثة جديدة. هناك تصل قيمة ref عبر messages أو messaging_postbacks، بحسب ما إذا كان الشخص كتب رسالة أو نقر على كاسر جليد.
  • وضع أحرف أخرى في ref. تقبل Meta الحروف والأرقام والشرطات والشرطات السفلية وعلامات المساواة فقط، حتى 2,083 حرفاً.
  • مطابقة source مع سلسلة نصية واحدة. تعرض أمثلة Meta القيمتين SHORTLINKS لـ ig.me وADS للإعلانات، لكن أحد جداولها يكتب SHORTLINK، لذلك افصل المعالجة حسب مكان الإحالة وحسب المعامل نفسه.
  • اختبار الروابط على Instagram Web. لا تدعم Meta روابط ig.me هناك، لذلك افتحها في تطبيق Instagram للهواتف.
إنجاز ذلك باستخدام EasyCoexistence

تردّ الأداة send_social_dm داخل نافذة 24 ساعة. من US$ 9 إلى US$ 0.75 لكل اتصال شهرياً، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية لمدة 3 أيام من أول اتصال.

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

ماذا يحتوي الحقل referral.source في إحالة الرابط؟

SHORTLINKS في أمثلة Meta لروابط ig.me، وADS لإعلان Click-to-Direct، لكن أحد جداول دليل Instagram Messaging في Meta يكتبها SHORTLINK. فرّع المعالجة حسب مكان الإحالة وحسب المعامل ref بدلاً من الاعتماد على قيمة نصية واحدة دقيقة.

ما أقصى طول مسموح به لمعامل ref؟

حتى 2,083 حرفاً، باستخدام الحروف والأرقام والشرطات والشرطات السفلية وعلامات المساواة فقط.

أين يصل معامل ref في المحادثة الجديدة؟

في messages عندما يكتب الشخص رسالة أولى، أو في messaging_postbacks عندما ينقر على كاسر جليد. أما messaging_referral فيغطي المحادثات القائمة فقط.

هل تعمل روابط ig.me في نسخة الويب؟

لا. يذكر دليل ig.me من Meta أنها غير مدعومة في نسخة الويب.

تابع القراءة

خطاف الويب (webhook) messaging_postbacks في Instagram: كاسرات الجمود والأزرارما يرسله خطاف messaging_postbacks من Instagram عند نقر شخص على كاسر الجمود أو زر أو عنصر قائمة: العنوان وpayload وmid، وطريقة الإعداد.خطاف الويب (webhook) للرسائل على Instagram: حمولة الرسالة المباشرة (DM) والأصداء والحقولما يرسله webhook الرسائل على Instagram لكل رسالة مباشرة: معرّف المرسل المحدود والنص والمرفقات والردود على القصص والأصداء، حقلاً حقلاً، مع نافذة 24 ساعة.حقول خطاف الويب (webhook) في Instagram: القائمة الكاملةحقول webhook التي تُدرجها Meta لـ Instagram Login: ما يُطلق كل حقل، والإذن الذي يلزمه، والحقول المتروكة لـ Facebook Login.رسائل Instagram المباشرة عبر API ونافذة الـ24 ساعةطريقة عمل رسائل Instagram المباشرة عبر API: من يمكن للحساب مراسلته، ونافذة الرسائل 24 ساعة، والردود الخاصة، وإعداد السماح بالوصول.أحداث Instagram عبر خطاف الويب (webhook): التعليقات والإشارات والرسائل المباشرةكيف تصل تعليقات Instagram والإشارات والرسائل المباشرة إلى نقطة النهاية (endpoint) كأحداث webhook، وما تحمله كل حمولة، وكيف يُوقَّع كل تسليم.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في