וובהוק (Webhook) של Messenger לעמודי Facebook: הודעות ואזכורים
שדה messages בוובהוקי העמודים של Facebook מופעל כשאדם שולח לעמוד הודעת Messenger. ההתראה כוללת מערך messaging עם המזהה של השולח בתוך העמוד, מזהה העמוד, חותמת זמן, והמזהה mid של ההודעה יחד עם הטקסט או הקבצים המצורפים. שדה mention מדווח על אזכורים חדשים של העמוד בפוסטים ובתגובות, ו-Meta חותמת את שני השדות עם X-Hub-Signature-256.
easyCoexistence מעבירה את הודעות Messenger ואזכורים של כל עמוד מחובר לנקודת הקצה ב-HTTPS שלכם ברגע שהם מגיעים, חתומים במפתח ייעודי לאותו עמוד, בלי לשמור עותק.
כמה מהר נקודת הקצה של הוובהוק ב-Messenger צריכה להחזיר 200 OK לכל התראה.
אחרי שמסירות נכשלות במשך פרק הזמן הזה, מבטלים את הרישום של האפליקציה מהוובהוקים של העמוד, עד שהאפליקציה תירשם שוב.
מזהה השולח בתוך העמוד באירוע messages, ייחודי לכל זוג של אדם ועמוד.
האופן שבו מדריך ההפניה של Meta מסמן את השדה sender באירוע mention.
אי אפשר לשאול על התראות וובהוק שעברו מאוחר יותר, לכן המקבל צריך לשמור את מה שהוא צריך.
מה שדה messages שולח?
התראה כשאדם שולח לעמוד הודעת Messenger. נשלחות הודעות טקסט או הודעות עם קבצים מצורפים, כמו תמונות, אודיו, וידאו, קבצים וסטיקרים, ועוד סוגים. קישור ששותף יכול להגיע כקובץ מצורף חלופי. תשובה להודעה קודמת נושאת את reply_to עם המזהה mid של אותה הודעה, ותשובה מהירה נושאת את ה-payload שלה.
איך נראה אירוע messages?
בניגוד לשינויי feed, הודעה מגיעה כמערך messaging בתוך entry של העמוד. לכל אירוע יש sender, המזהה של השולח בתוך העמוד; recipient, העמוד; timestamp, חותמת הזמן; ושדה message, עם המזהה mid שלה והטקסט, או attachments עם type וכתובת ה-URL של ה-payload:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}מה שדה mention שולח?
שינוי עם השדה mention כשמזכירים את העמוד בפוסט או בתגובה, ונושא את post_id או comment_id, את ההודעה, קישור, תמונה או וידאו אם יש, וגם את השדה item והשדה verb. לפי התיעוד של Meta, חלק ממזהי הפוסטים והתגובות לא ניתנים לשאילתה, בגלל חוסר הרשאה או פרטיות. התיעוד מסמן את שדה sender כ-Workplace בלבד, כך שאזכור עשוי להגיע בלי מחברו.
אילו שדות של Messenger לא מועברים?
easyCoexistence רושמת את העמודים לשדה messages, ולא לשדות message_echoes, messaging_postbacks, message_reads או message_deliveries. לכן הודעות שהעמוד שולח, לחיצות על כפתורים ואישורי קריאה ומסירה אינם מועברים. תשובה שנשלחת עם send_social_dm מחזירה במקום זה מזהה הודעה משלה.
איך אירועים מגיעים לנקודת הקצה שלכם?
וובהוקי העמודים נמסרים לאפליקציה שהעמוד התקין, דרך כתובת callback אחת לכל האפליקציה. easyCoexistence בודקת את X-Hub-Signature-256 בכל מסירה, עונה ל-Meta מיד, ומעבירה כל entry של עמוד מחובר לנקודת הקצה שהגדרתם לו ב-HTTPS, חתום במפתח החתימה של אותו עמוד. להגדיר אותה אפשר עם set_social_webhook_destination מ-Claude או מ-ChatGPT, או עם PUT /channels/:id/webhook ב-Partner API. המפתח מוצג פעם אחת, הגדרה חוזרת מנפיקה מפתח חדש, וערך null בכתובת ה-URL מכבה את ההעברה.
איך נראה אירוע שהועבר?
בקשת POST שמכילה את platform, את account_id שמחזירה list_social_accounts לחיבור של העמוד, את המזהה של העמוד כ-external_id, ואת entry, עם הערך של Meta לעמוד ללא שינוי. הערך sender.id הוא הערך שנדרש בפרמטר recipient_id של send_social_dm לתשובה בתוך חלון של 24 שעות:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}איך מאמתים אירוע שהועבר?
כל בקשת POST שהועברה נושאת את הכותרת X-EC-Signature בצורה t=<unix>,v1=<hex>, כאשר v1 הוא HMAC-SHA256 של חותמת הזמן, נקודה והגוף הגולמי של הבקשה, במפתח החתימה של העמוד. מחשבים אותו על הגוף בדיוק כפי שהתקבל, משווים בזמן קבוע, ודוחים חותמת זמן שישנה מ-5 דקות.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}האם מסירה נשלחת שוב?
לא על ידי easyCoexistence. כל entry מועבר פעם אחת, בזיכרון, בלי עותק שממנו אפשר לנסות שוב. ההעברה ממתינה 8 שניות לתשובה, לא עוקבת אחר הפניות, ונשלחת רק לכתובת HTTPS שנפתרת לכתובת IP ציבורית. לפי התיעוד של Meta, אי אפשר לשאול על התראות קודמות מאוחר יותר, לכן שמרו את מה שאתם צריכים ברגע שהוא מגיע. מצד Meta, מסירה שנכשלה נשלחת שוב כמה פעמים מיד, ולכן אותה הודעה יכולה להגיע אליכם פעמיים לעיתים רחוקות: בצעו הסרת כפילויות לפי המזהה mid שלה.
טעויות נפוצות
- לעשות את העבודה לפני התשובה. ההעברה לא מנסה שוב, לכן החזירו 2xx מיד ועבדו את האירוע אחר כך.
- לאמת את החתימה על JSON מפוענח. חשבו את ה-HMAC על הגוף הגולמי בדיוק כפי שהגיע.
- להניח שלהודעה יש תמיד טקסט. סטיקר, תמונה או קישור ששותף מגיעים כקבצים מצורפים, בלי שדה text.
- לדלג על הסרת כפילויות. אחרי כשל, אירוע עשוי להימסר שוב, לכן השתמשו במזהה mid של ההודעה לפני שפועלים.
send_social_dm משיב בתוך חלון של 24 שעות. הפעילו את ההעברה עם set_social_webhook_destination או דרך ה-Partner API. US$ 9 עד US$ 0.75 לחיבור בחודש, שיורד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
לאילו שדות וובהוק easyCoexistence רושמת עמוד?
השדה messages להודעות Messenger, והשדה mention לאזכורים, לצד השדה feed לפוסטים ולתגובות של העמוד.
האם לסטיקר או לתמונה ב-Messenger יש טקסט?
לא. סטיקר, תמונה או קישור ששותף מגיעים בקבצים מצורפים, שלכל אחד מהם type וכתובת ה-URL של ה-payload, ואין בהודעה שדה text.
תוך כמה זמן נקודת הקצה של הוובהוק של Messenger צריכה לענות?
להחזיר 200 OK תוך 5 שניות. אחרי שעה של מסירות כושלות, מבטלים את הרישום של האפליקציה לוובהוקים של העמוד.
איך משיבים להודעה שהועברה?
מפעילים את send_social_dm עם sender.id מהאירוע כערך של recipient_id, בתוך 24 שעות מההודעה של האדם.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-