ذكر القصص والردود عليها في webhook إنستغرام
يرسل إنستغرام ذكر القصص والردود عليها كرسائل مباشرة ضمن حقل messages في خطاف الويب (webhook). يصل الذكر كرسالة تحتوي مرفقاتها على عنصر من نوع story_mention، ويحمل payload.url رابط شبكة توصيل المحتوى (CDN) الخاص بالقصة. ويحمل الرد نص الشخص وكائن reply_to.story الذي يتضمن الحقلين url وid الخاصين بالقصة، وفي حالة القصة التي تحتوي على ملصق رابط يظهر link_sticker_url أيضاً.
يشترك easyCoexistence في حدث messages لكل حساب إنستغرام متصل، فتصل ذكر القصص وردودها إلى نقطة النهاية (endpoint) الخاصة بك عبر HTTPS مع الرسائل المباشرة الأخرى فور وصولها، موقَّعة بسر ذلك الحساب دون الاحتفاظ بأي نسخة.
نوع المرفق في حدث messages الذي ترسله Meta عند ذكر شخص للحساب في قصته.
الحقل الذي أضافته Meta إلى reply_to.story في 12 ديسمبر 2025، ويحمل عنوان URL لملصق الرابط في القصة التي جرى الرد عليها.
مدة بقاء القصة؛ فبمجرد انتهائها أو حذفها يتوقف رابط الذكر عن العرض.
الحسابات التي يصل منها ذكر القصص؛ ولا يصل ذكر الحساب الخاص إلا إذا كان يتابع الحساب المهني.
ردود القصص التي لا يدعمها webhook بحسب دليل مراسلة إنستغرام الصادر عن Meta.
كيف يصل ذكر القصة؟
كرسالة مباشرة. عندما يذكر شخص الحساب المهني في قصته، يضع إنستغرام رسالة تشير إلى تلك القصة في صندوق الوارد الخاص بالحساب، وترسل Meta حدث messages لها. يحمل sender.id معرّف الشخص الخاص بإنستغرام، ويحتوي message.attachments على عنصر واحد من نوع story_mention، يحمل payload.url رابط CDN الخاص بالقصة. لا تتضمن عينات Meta أي نص، لذلك اقرأ المرفق:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{
"type": "story_mention",
"payload": { "url": "<CDN_URL>" }
}
]
}
}
]
}
]
}كيف يصل الرد على القصة؟
أيضاً كرسالة مباشرة، تتضمن رسالة الشخص وكائن reply_to يشير إلى قصة الحساب. يحمل reply_to.story رابط CDN الخاص بالقصة في url، ومعرّفها في id. وتدرج مرجعية webhook من Meta أيضاً link_sticker_url هناك، وقد أضافته Meta في ديسمبر 2025 للردود على القصص التي تحتوي على ملصق رابط، وتقترح استخدامه لتوجيه الأتمتة حسب الرابط. أما الرد المضمن على رسالة سابقة فيستخدم reply_to.mid بدلاً من ذلك.
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL>",
"id": "<STORY_ID>"
}
}
}ما معنى كل حقل؟
الحقول التي توثقها Meta لهذين الحدثين، من الخارج إلى الداخل:
- entry[].id و recipient.id: الحساب المهني. أما sender.id فهو معرّف الشخص الخاص بإنستغرام، وهو المعرّف الذي يُوجَّه إليه الرد.
- timestamp: وقت إرسال الرسالة، بالمللي ثانية في عينات Meta؛ أما entry[].time فهو وقت إرسال Meta للإشعار.
- message.mid: معرّف الرسالة، ويُستخدم لإزالة تكرار المحاولات المعادة وللرد عبر
reply_to.mid. - attachments[].type
story_mentionو payload.url: ذكر، ورابط CDN للقصة التي أنشأته. reply_to.story.url وreply_to.story.id: القصة التي رد عليها الشخص من قصص الحساب.reply_to.story.link_sticker_url: الرابط الموجود على ملصق الرابط في تلك القصة.- message.text: كلمات الرد، وتُدرج عندما تحتوي الرسالة على نص.
كم يبقى رابط القصة صالحاً؟
طالما بقيت القصة. تختفي القصة بعد 24 ساعة أو عند حذفها من صاحبها، وتقول إرشادات ذكر القصص من Meta إن الرابط يتوقف عندها عن العرض؛ وتضيف نظرة عامة أن روابط CDN في إنستغرام تراعي الخصوصية، فلا تعيد شيئاً للمحتوى المحذوف أو المنتهي. ويسمح الدليل نفسه بالاحتفاظ برابط CDN دون الوسائط: فلا يجوز للتطبيق تخزين محتوى القصة أو تخزينه مؤقتاً على خوادمه، وينبغي أن يعرض عنصراً بديلاً بعد اختفاء القصة.
متى لا يُطلق أيٌّ من الحدثين؟
تذكر أدلة Meta هذه الحالات، حيث لا يتلقى المعالج المنتظر لحدث القصة أي شيء:
- ذكر قصة من حساب خاص لا يتابع الحساب المهني.
- وسم في منشور عادي: تقول Meta إن ذكر القصص وحده يطلق webhook الرسائل، لا الوسم في المنشورات.
- رد على قصة بصورة GIF أو بملصق، وهو ما لا يدعمه webhook.
- القصص عبر واجهة الذكر: لا تدعمها GET /<
IG_ID>/tags وPOST /<IG_ID>/mentions، لذلك يصل ذكر القصة عبر الرسالة المباشرة.
هل يفتح ذكر القصص والردود نافذة المراسلة؟
الرد رسالة من الشخص، وتدرج Meta ذكر القصص ضمن القنوات التي يبدأ عبرها الشخص محادثة. تستمر النافذة التي يفتحها الإجراء 24 ساعة لمعظم الإجراءات، فيمكن للحساب الرد عبر POST /<IG_ID>/messages مع ضبط recipient.id على sender.id الخاص بالحدث ما دامت النافذة مفتوحة. ويعود رد الحساب على messages بوصفه echo، مع ضبط is_echo على true.
كيف تُمرّرها easyCoexistence؟
عبر حقل messages الذي يشترك فيه كل حساب متصل، لذلك تصل ذكر القصص وردودها إلى نقطة النهاية (endpoint) الخاصة بك مع الرسائل المباشرة الأخرى للحساب: كل إدخال داخل مغلف يحوي platform وaccount_id وexternal_id وentry، ويُوقَّع في X-EC-Signature بسر الحساب، ويُرسل مرة واحدة دون الاحتفاظ بأي نسخة. ويرد send_social_dm على الشخص بوضع sender.id الخاص بالحدث في recipient_id، ضمن نافذة 24 ساعة.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "story_mention", "payload": { "url": "<CDN_URL>" } }
]
}
}
]
}
}الأخطاء الشائعة
- تخزين وسائط القصة. يسمح دليل ذكر القصص من Meta بالاحتفاظ برابط CDN لا بالمحتوى، ولا يجوز تخزين المحتوى أو تخزينه مؤقتاً على خوادمك.
- قراءة message.text فقط. يحمل ذكر القصة مرفقاً من نوع story_mention، ولا يحتوي في عينات Meta على نص، فيرى المعالج الذي يقرأ النص فقط رسالة فارغة.
- عرض رابط القصة بعد أيام. يتوقف الرابط عن العمل بعد انتهاء القصة بعد 24 ساعة أو حذفها، فاعرض عنصراً بديلاً من تلك اللحظة فصاعداً.
- البحث عن ذكر القصص في حقل comments أو في واجهة الذكر. تسلمها Meta كرسائل مباشرة ضمن messages.
ويرد send_social_dm على الشخص خلال نافذة 24 ساعة، من Claude أو ChatGPT أو من كودك الخاص. من US$ 9 إلى US$ 0.75 لكل اتصال شهرياً، ينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل يتضمن حدث ذكر القصة في إنستغرام نصاً؟
ليس في عينات Meta. يحمل ذكر القصة مرفقاً من نوع story_mention مع رابط CDN للقصة، لذا فالمعالج الذي يقرأ message.text فقط يرى رسالة فارغة.
ما هو link_sticker_url في رد على قصة في إنستغرام؟
هو الرابط الموجود على ملصق الرابط في القصة التي رد عليها الشخص، ويأتي في reply_to.story.link_sticker_url. أضافته Meta في 12 ديسمبر 2025، وتقترح استخدامه لتوجيه الأتمتة حسب الرابط.
هل تُطلق الردود على القصص بصورة GIF أو بملصق webhook؟
لا. يقول دليل مراسلة إنستغرام من Meta إن webhook لا يدعم الردود على القصص المرسلة بصورة GIF أو بملصق.
هل تُطلق الحسابات الخاصة إشارات ذكر القصص؟
فقط إذا كان الحساب الخاص يتابع الحساب المهني. تصل الذكرات من الحسابات العامة فور حدوثها.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في