התחברותהתחילו תקופת ניסיון
easyCoexistence ממשקי API רשמיים

וובהוק (Webhook) של Messenger לעמודי Facebook: הודעות ואזכורים

שדה messages בוובהוקי העמודים של Facebook מופעל כשאדם שולח לעמוד הודעת Messenger. ההתראה כוללת מערך messaging עם המזהה של השולח בתוך העמוד, מזהה העמוד, חותמת זמן, והמזהה mid של ההודעה יחד עם הטקסט או הקבצים המצורפים. שדה mention מדווח על אזכורים חדשים של העמוד בפוסטים ובתגובות, ו-Meta חותמת את שני השדות עם X-Hub-Signature-256.

easyCoexistence מעבירה את הודעות Messenger ואזכורים של כל עמוד מחובר לנקודת הקצה ב-HTTPS שלכם ברגע שהם מגיעים, חתומים במפתח ייעודי לאותו עמוד, בלי לשמור עותק.

5 seconds

כמה מהר נקודת הקצה של הוובהוק ב-Messenger צריכה להחזיר 200 OK לכל התראה.

1 hour

אחרי שמסירות נכשלות במשך פרק הזמן הזה, מבטלים את הרישום של האפליקציה מהוובהוקים של העמוד, עד שהאפליקציה תירשם שוב.

PSID

מזהה השולח בתוך העמוד באירוע messages, ייחודי לכל זוג של אדם ועמוד.

Workplace only

האופן שבו מדריך ההפניה של Meta מסמן את השדה sender באירוע mention.

No history

אי אפשר לשאול על התראות וובהוק שעברו מאוחר יותר, לכן המקבל צריך לשמור את מה שהוא צריך.

מה שדה messages שולח?

התראה כשאדם שולח לעמוד הודעת Messenger. נשלחות הודעות טקסט או הודעות עם קבצים מצורפים, כמו תמונות, אודיו, וידאו, קבצים וסטיקרים, ועוד סוגים. קישור ששותף יכול להגיע כקובץ מצורף חלופי. תשובה להודעה קודמת נושאת את reply_to עם המזהה mid של אותה הודעה, ותשובה מהירה נושאת את ה-payload שלה.

איך נראה אירוע messages?

בניגוד לשינויי feed, הודעה מגיעה כמערך messaging בתוך entry של העמוד. לכל אירוע יש sender, המזהה של השולח בתוך העמוד; recipient, העמוד; timestamp, חותמת הזמן; ושדה message, עם המזהה mid שלה והטקסט, או attachments עם type וכתובת ה-URL של ה-payload:

A messages event, as Meta sends it
{
  "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 שעות:

A forwarded messages event
{
  "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 דקות.

Node.js: verifying X-EC-Signature
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 של ההודעה לפני שפועלים.
עושים את זה עם EasyCoexistence

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 שעות מההודעה של האדם.

המשיכו לקרוא

וובהוק (Webhook) של feed בעמוד Facebook: אירועים של תגובות, פוסטים וריאקציותמה שוובהוק של feed בעמוד Facebook שולח על תגובות, פוסטים וריאקציות: שדות item ו-verb, מבנה ה-payload של Meta ואיך עמוד נרשם.חלון ההודעות של 24 שעות ב-Messenger: מתי עמוד Facebook יכול לשלוח הודעהמתי עמוד Facebook יכול לשלוח הודעה ב-Messenger: חלון ההודעות הרגיל של 24 שעות, הפעולות שפותחות אותו, ועד 7 ימים אחרי מודעה.ה-API לתשובות פרטיות ב-Facebook: הודעה למי שהגיב בעמודשליחת תשובה פרטית ב-Facebook עם ה-API של Meta: POST /{page-id}/messages עם מזהה התגובה, הודעה אחת תוך 7 ימים, והשגיאות.הרשאות דף Facebook API ודרישות App Reviewתשע הרשאות של דף Facebook, מה כל אחת פותחת, ומה Meta דורשת ב-App Review לגישה מתקדמת: אימות עסק וסרטון הקלטה.אסימון גישה לעמוד Facebook: כמה זמן הוא תקף ומה מבטל אותוהסבר איך מקבלים אסימון גישה לעמוד Facebook ללא תאריך תפוגה, מי יכול לקבל אותו, ומה גורם ל-Meta להפסיק לקבל אותו.שגיאה 551 של Facebook: האדם אינו זמין ב-Messengerשגיאה 551 ב-Facebook: Messenger לא הצליח להגיע לאדם שאולי חסם את הדף או השבית את חשבונו, וההודעה לא נשלחה.

מחברים את הערוץ הראשון שלכם תוך שתי דקות.

בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.

  • 3 ימי ניסיון חינם
  • ביטול בכל עת
  • רק ממשקי API רשמיים
  • ניטור 24/7

נבדק ב-