خطاف الويب (webhook) messaging_postbacks في Instagram: كاسرات الجمود والأزرار
يُخطر حقل messaging_postbacks في webhook من Instagram التطبيقَ عندما ينقر شخص على سؤال من كاسرات الجمود، أو على زر postback في قالب، أو على عنصر في القائمة الثابتة ضمن محادثة مع حساب احترافي. يحمل كائن postback في الحدث العنوان (title)، وهو النص الذي نقره الشخص، وpayload، وهي السلسلة التي حددها التطبيق لذلك الخيار، وmid، وهو معرّف الرسالة، ابتداءً من Graph API v11.0.
يشترك easyCoexistence في التعليقات والرسائل والإشارات لكل حساب Instagram متصل، ويمرر هذه الأحداث، بما فيها نقرات الردود السريعة، إلى نقطة النهاية (endpoint) الخاصة بك عبر HTTPS فور وصولها، موقّعةً بالسرّ الخاص بذلك الحساب، دون الاحتفاظ بأي نسخة.
الحد الأقصى لعدد أسئلة كاسرات الجمود التي يمكن للحساب ضبطها عبر Ice Breaker API من Meta.
أول إصدار من Graph API تتضمن فيه أحداث postback الحقل mid، ويحتاج الحقل نفسه إلى الإصدار v8.0 أو أحدث.
أكثر الأزرار التي يمكن أن تتضمنها رسالة قالب الأزرار، وكل زر منها من نوع postback أو web_url.
المدة المتاحة للرد بعد أن ينقر شخص على عنصر من القائمة الثابتة، وهي فترة نافذة المراسلة القياسية.
أكثر الردود السريعة التي تعرضها رسالة واحدة؛ والرد السريع المنقور يصل عبر messages لا messaging_postbacks.
متى يُطلق messaging_postbacks؟
عندما ينقر شخص أحد الخيارات المنظمة للحساب في محادثة، بعد اشتراك التطبيق والحساب في الحقل. تذكر أدلة Meta هذه المصادر:
- سؤال من كاسرات الجمود، وهو واحد من 4 كحد أقصى يعرضها الحساب عند بدء المحادثة. غير متاح على سطح المكتب.
- زر postback في قالب أزرار، حتى 3 في الرسالة، أو في قالب عام، حتى 3 لكل عنصر.
- عنصر postback في القائمة الثابتة للحساب.
- كاسر جمود نُقر في محادثة جديدة فُتحت من رابط ig.me يحمل معامل ref: عندئذ يحمل postback أيضًا referral.
- اختبار المراسلة الذاتية، حيث ينقر الحساب زره الخاص: يضيف الحدث
is_selfوقيمته true.
كيف يبدو إشعار postback؟
حدث رسالة يحتوي كائن postback في المكان الذي ستظهر فيه الرسالة النصية في الرسالة المباشرة. يعرض مثال Meta لتسجيل الدخول عبر Instagram الحقول mid وtitle وpayload، ويعرض دليل كاسرات الجمود الكائن نفسه دون mid. يبدو الإشعار هكذا:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}ما معنى كل حقل؟
الحقول التي توثّقها Meta لكائن postback، من الخارج إلى الداخل:
- sender.id: معرّف الشخص الذي نقر، ضمن نطاق Instagram، وهو المعرّف الذي يُرد عليه. أما recipient.id وentry[].id فهما الحساب الاحترافي.
- timestamp: وقت النقر، وفق دليل كاسرات الجمود من Meta.
- postback.title: سؤال كاسر الجمود أو عنوان الزر كما رآه الشخص.
- postback.payload: السلسلة المحددة لذلك الخيار عند إنشائه، ويختارها التطبيق.
- postback.mid: معرّف الرسالة التي أرسلها النقر إلى الحساب، ابتداءً من Graph API v11.0.
- postback.referral: ref وsource وtype، عندما فُتحت المحادثة من رابط ig.me يحمل معامل ref.
is_self: يُضبط على true بجوار postback عندما ينقر الحساب زره في اختبار المراسلة الذاتية.
كيف تُضبط كاسرات الجمود؟
عبر POST /<IG_ID>/messenger_profile على graph.instagram.com، مع platform بقيمة instagram ومصفوفة ice_breakers تحتوي call_to_actions فيها ما يصل إلى 4 أزواج سؤال وpayload، مع locale لكل مجموعة مترجمة. يسرد GET /me/messenger_profile?fields=ice_breakers هذه الأسئلة، ويحذفها DELETE مع fields بقيمة ice_breakers. أما payload المختار هنا فهو ما يعيده messaging_postbacks عند نقر السؤال.
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}كيف تُرسل أزرار postback؟
داخل رسالة يرسلها الحساب عبر POST /<IG_ID>/messages. يحمل قالب الأزرار نصًا يصل إلى 640 حرفًا ومن 1 إلى 3 أزرار، ويحمل القالب العام حتى 10 عناصر، لكل منها حتى 3 أزرار. يعيد الزر من نوع postback حمولته payload على messaging_postbacks عند النقر، بينما يفتح زر web_url صفحة في المتصفح داخل التطبيق. وتقبل القائمة الثابتة، المضبوطة على messenger_profile، النوعين نفسيهما.
هل تستخدم الردود السريعة messaging_postbacks؟
لا، إذ تصل عبر messages. يُرسل الرد السريع المنقور عنوانه إلى المحادثة كرسالة، فيحمل حدث messages الحقل text بقيمة ذلك العنوان، والحقل quick_reply.payload بقيمة payload الخيار. يمكن للرسالة أن تعرض حتى 13 ردًا سريعًا، لا يتجاوز كل منها 20 حرفًا، ونص عادي فقط. ويذكر دليل المراسلة في Instagram من Meta أن messages يبلغ أيضًا باختيارات كاسرات الجمود والقوالب العامة، دون عينة payload.
هل ينقل النقر نافذة المراسلة؟
بالنسبة إلى القائمة الثابتة، تقول Meta ذلك: يفتح النقر على عنصر القائمة نافذة المراسلة القياسية، ويملك الحساب 24 ساعة للرد. أرسل الرد عبر POST /<IG_ID>/messages، مع recipient.id بقيمة sender.id في حدث postback. يعود رد الحساب على messages كصدى echo، مع is_echo بقيمة true.
هل يمرّر easyCoexistence أحداث postback؟
النقرات على الرد السريع فقط. تصل عبر messages، الذي يشترك فيه تطبيق easyCoexistence وكل حساب متصل، فتصل إلى endpoint الخاص بك مع quick_reply.payload. أما نقرات كاسرات الجمود والأزرار والقائمة فتصل عبر messaging_postbacks، الذي لا تشترك فيه easyCoexistence، لذلك لا تُمرَّر.
الأخطاء الشائعة
- انتظار الردود السريعة في messaging_postbacks. يصل الرد السريع عبر messages، مع quick_reply.payload بجوار نص الخيار المنقور.
- التوجيه بناءً على postback.title. العنوان هو ما رآه الشخص وقد يختلف حسب اللغة، لذا وجّه بناءً على payload الذي يضبطه التطبيق.
- توقّع mid في إصدار API أقدم. تتضمن Meta الحقل postback.mid ابتداءً من Graph API v11.0 فقط.
- ضبط أكثر من 4 كاسرات جمود، أو اختبارها على سطح المكتب. تسمح Ice Breaker API بما يصل إلى 4 أسئلة، والميزة غير متاحة على سطح المكتب.
تجيب send_social_dm الشخص ضمن نافذة 24 ساعة. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويتناقص السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية لأول 3 أيام.
الأسئلة الشائعة
ما حقل webhook الذي يبلغ بنقرات كاسرات الجمود في Instagram؟
messaging_postbacks. يحمل كائن postback السؤال في title، والقيمة payload المحددة له، إضافة إلى mid ابتداءً من Graph API v11.0.
كم عدد كاسرات الجمود التي يمكن أن يملكها حساب Instagram؟
حتى 4 أسئلة، تُضبط عبر POST /<IG_ID>/messenger_profile مع platform بقيمة instagram، ويمكن تحديدها لكل لغة.
كيف أرد على postback في Instagram؟
عبر POST /<IG_ID>/messages مع recipient.id بقيمة sender.id في postback، وهو المعرّف ضمن نطاق Instagram للشخص الذي نقر. وبعد نقر على عنصر القائمة الثابتة، تمنح Meta الحساب 24 ساعة للرد.
هل أوجّه postbacks في Instagram بناءً على title أم payload؟
بناءً على payload، وهي السلسلة التي حددها التطبيق للخيار. أما title فهو النص الذي رآه الشخص، وقد يختلف حسب اللغة.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في