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

וובהוק (Webhook) של ההודעות ב-Instagram: ה-payload של ה-DM, ההדים והשדות

השדה messages של Instagram מעביר הודעות ישירות של חשבון מקצועי כשהן מגיעות: טקסט, קבצים מצורפים, שיתופים, תגובות לסטורי ואזכורים, תשובות מצוטטות ומחיקות. כל אירוע יושב במערך messaging עם מזהה ה-Instagram-scoped של השולח, הנמען, חותמת זמן ואובייקט ההודעה, והודעות שהחשבון עצמו שולח חוזרות באותו שדה עם is_echo שמוגדר כ-true.

easyCoexistence מנויה לכל חשבון Instagram מחובר להודעות ומעבירה את ההודעות הישירות שלו, כולל ההדים, לנקודת הקצה ה-HTTPS שלכם כשהן מגיעות, חתומות בסוד של אותו חשבון; ההעברה אינה שומרת עותק, והודעות ישירות אינן נשמרות כברירת מחדל.

is_echo

מוגדר ל-true באירוע הודעה עבור הודעה שהחשבון עצמו שלח.

24 hours

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

ig_post

סוג הקובץ המצורף של פוסט ששותף; סוג השיתוף הישן נתמך רק עד 1 בפברואר 2026.

story_mention

סוג הקובץ המצורף של אירוע ה-DM שמטא שולחת כשמישהו מאזכר את החשבון בסטורי שלו.

2534041

קוד שגיאה משנה, תחת קוד 200, כאשר בעל החשבון השבית את הגישה להודעות ישירות ב-Instagram.

מתי שדה ההודעות מופעל?

כשאדם שולח לחשבון המקצועי הודעה ישירה, וכשהחשבון שולח אחת. לפי הדוגמאות וההפניות של Meta, המקרים הבאים מופיעים, וכל אחד מהם הוא אירוע הודעה עם אובייקט הודעה:

  • טקסט, ומדיה כקבצים מצורפים: תמונות, וידאו, אודיו וקבצים.
  • פוסט או ריל ששותפו, כקובץ מצורף מסוג ig_post, ig_reel או reel.
  • תשובה לסטורי של החשבון, עם reply_to.story, וסטורי שמאזכר את החשבון, כקובץ מצורף מסוג story_mention.
  • תשובה מוטמעת להודעה קודמת, עם reply_to.mid, ותשובה מהירה, עם quick_reply.payload.
  • הודעה שהאדם מחק (is_deleted), מדיה לא נתמכת (is_unsupported), והודעה ממי שלחץ על מודעת Click-to-Direct (referral).
  • הודעה שהחשבון שלח, שחוזרת עם is_echo שמוגדר ל-true.

איך נראית התראת ההודעות?

POST שה-JSON שלו מכיל object עם הערך instagram. בניגוד לתגובה, הודעה יושבת במערך messaging בתוך ה-entry של החשבון, וכל איבר נושא sender, recipient, timestamp ו-message. כך נראית תשובה לסטורי של החשבון:

A messages notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_TEXT>",
            "reply_to": {
              "story": {
                "url": "<CDN_URL_FOR_THE_STORY>",
                "id": "<STORY_ID>"
              }
            }
          }
        }
      ]
    }
  ]
}

מה כל שדה אומר?

השדות ש-Meta מתעדת לאירוע הודעה תחת Instagram Login, מבחוץ פנימה:

  • entry[].id: מזהה החשבון המקצועי. entry[].time: מתי Meta שלחה את ההתראה; הדוגמאות של Meta למסרי הודעות נותנות אותו במילישניות.
  • sender.id ו-recipient.id: בהודעה נכנסת, מזהה ה-Instagram-scoped של האדם ומזהה החשבון; בהד, אותם שני ערכים בסדר הפוך.
  • timestamp: מתי נשלחה ההודעה, במילישניות בדוגמאות של Meta. מיינו הודעות לפיו, לא לפי סדר ההגעה.
  • message.mid: מזהה ההודעה, לסינון כפילויות, לתגובה עליה ולהשבה לאותה הודעה עם reply_to.mid.
  • message.text: נכלל כשההודעה מכילה טקסט.
  • message.attachments[]: כל אחד עם type ו-payload, בדרך כלל url. ה-payload של פוסט ששותף מוסיף ig_post_media_id וכותרת title, שהיא הכיתוב.
  • message.reply_to: mid לתשובה מוטמעת, או story עם ה-url והמזהה של הסטורי לתשובה לסטורי.
  • message.quick_reply.payload ו-message.referral: התשובה המהירה שנבחרה, וה-ref, ad_id, source, type וה-ads_context_data של מודעת Click-to-Direct.
  • message.is_deleted, is_echo, is_self ו-is_unsupported: נכללים רק כשהם true.
  • message.admin_text ו-handoff_reason: באפליקציות זכאיות, הודעה על כך שאפליקציה של Meta, כמו Meta Business Agent, העבירה את השיחה הלאה; זה יכול להגיע בלי mid או טקסט.

איך עובדים הדים?

כשהחשבון שולח הודעה, Meta שולחת עבורה גם אירוע הודעה, עם is_echo שמוגדר ל-true. אז sender.id הוא החשבון ו-recipient.id הוא מזהה ה-Instagram-scoped של האדם, והודעת בדיקה שהחשבון שולח לעצמו נושאת גם is_self. ההדים מתעדים את מה שהחשבון אמר, וזה נחוץ ליומן שיחות, אבל מטפל שמחליט אם להשיב חייב לדלג עליהם. Meta לא שולחת הד כשהחשבון מגיב להודעה בריאקציה או מסיר ריאקציה.

An echo of a message the account sent
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448061203,
      "messaging": [
        {
          "sender": { "id": "<IG_ID>" },
          "recipient": { "id": "<IGSID>" },
          "timestamp": 1793448060950,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<REPLY_TEXT>",
            "is_echo": true
          }
        }
      ]
    }
  ]
}

לאיזה מזהה משיבים?

sender.id, מזהה ה-Instagram-scoped של האדם. Meta יוצרת אותו כשמישהו שולח הודעה לחשבון או מגיב על המדיה שלו, והוא ייחודי לאותו אדם ולאותו חשבון. POST /<IG_ID>/messages עם recipient.id שמוגדר אליו שולח את התשובה. לאירוע אין שם או שם משתמש; GET /<IGSID> עם שדות כמו name ו-username מחזיר אותם, כי אדם ששלח הודעה לחשבון נתן את ההסכמה שהחיפוש הזה דורש.

איך הודעה פותחת את חלון ה-24 השעות?

אפליקציה יכולה לשלוח הודעה לאדם רק אחרי שהוא שלח הודעה לחשבון, ורק בתוך חלון ההודעות הסטנדרטי שהפעולה שלו פותחת. ברוב הפעולות החלון נמשך 24 שעות, ועד 7 ימים מהודעה ראשונה שנשלחה אחרי לחיצה על מודעת Click-to-Direct. הודעה חדשה מהאדם פותחת חלון חדש, לכן יש לעקוב אחרי חותמת הזמן האחרונה שלו; הד הוא הודעה של החשבון עצמו ואינו מאריך כלום. תשובות שכתב אדם יכולות להשתמש בחלון נפרד של 7 ימים של Meta, Human Agent, עם התג human_agent.

מה אירוע ההודעה לא כולל?

כמה דברים שמטפל עשוי לחפש חסרים, לפי ההפניות להודעות של Meta:

  • שם או שם משתמש של האדם: רק מזהה ה-Instagram-scoped, ש-GET /<IGSID> מפענח.
  • מדיה לצפייה חד-פעמית: היא מגיעה כקובץ מצורף חולף ללא כתובת.
  • את תמונת הקרוסלה המדויקת: ריאקציה לתמונה אחת או העברה שלה בפוסט קרוסלה מדווחת על התמונה הראשונה.
  • ריאקציות, עריכות ואישורי קריאה, שמגיעים בשדות משלהם.
  • סימון קריאה: הודעה שנמסרה בוובהוק נשארת לא נקראה בתיבת Instagram עד שנשלחת תשובה.

אילו שדות הודעה אחרים Meta מפרטת?

רשימת השדות והדוגמאות של Meta ל-Instagram Login מציינת, בנוסף להודעות, את אלה, וכל אחד מהם הוא אירוע הודעה משלו. easyCoexistence מנויה לכל חשבון רק להודעות, לתגובות ולאזכורים, ולכן אף אחד מהם לא חלק ממה שהיא מעבירה:

  • message_reactions: אדם מגיב להודעה או מסיר ריאקציה, עם reaction.mid, action שמוגדר ל-react או unreact, וה-reaction וה-emoji.
  • message_edit: אדם עורך הודעה, עם message_edit.mid, הטקסט החדש ו-num_edit.
  • messaging_postbacks: אדם לוחץ על icebreaker או על כפתור תבנית, עם postback.mid, title ו-payload.
  • messaging_referral: אדם שכבר בשיחה פותח קישור ig.me עם פרמטר ref.
  • messaging_seen: אדם קורא הודעה, עם read.mid.
  • messaging_optins, messaging_handover ו-standby: שני האחרונים מיועדים לאפליקציות שחולקות שיחה לפי פרוטוקול ה-handover של Meta.

מה החשבון צריך להפעיל?

לאפשר גישה להודעות (Allow access to messages). Meta דורשת מחשבון מקצועי להפעיל אותה לפני שניתן לנהל את ההודעות שלו דרך ה-API, באפליקציית Instagram תחת Settings, Messages and story replies, Message controls, Connected tools. כשהיא כבויה, שליחות נכשלות עם קוד 200, תת-קוד 2534041. האפליקציה צריכה גם את instagram_business_basic ו-instagram_business_manage_messages, וגישה Advanced Access כדי לשרת חשבונות שהיא לא בעלת עליהם או לא מנהלת.

איך easyCoexistence מעבירה הודעה ישירה?

כמו תגובה: כל ערך ש-Meta מוסרת לחשבון נשלח ב-POST לנקודת הקצה ה-HTTPS שלכם, בתוך מעטפה עם platform, account_id, external_id ו-entry, חתומה ב-X-EC-Signature עם הסוד של החשבון, פעם אחת, בלי לשמור עותק. הדים מועברים עם השאר, לכן בדקו את is_echo לפני שמשיבים. כדי לענות, קראו ל-send_social_dm עם account_id ועם sender.id של האירוע כ-recipient_id, בתוך חלון ה-24 שעות. אוטומציות שמופעלות מהודעה ישירה רצות על אותם אירועים.

A forwarded DM with an image
{
  "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": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
          ]
        }
      }
    ]
  }
}

טעויות נפוצות

  • השבה להדים: אירוע שבו is_echo מוגדר הוא הודעה של החשבון עצמו, ותשובה אליו שולחת את החשבון ללולאה עם עצמו.
  • הנחה שלהודעה תמיד יש טקסט: קבצים מצורפים, שיתופים, אזכורים בסטורי ומחיקות מגיעים בלי שדה טקסט, לכן הסתעפו לפי מה שאובייקט ההודעה מכיל.
  • מיון הודעות לפי סדר ההגעה: Meta יכולה למסור הודעות שלא לפי הסדר אחרי כשל, לכן מיינו לפי timestamp.
  • ניתוח time ו-timestamp כשניות: הדוגמאות של Meta נותנות את שניהם במילישניות, וכשקוראים אותם כשניות הם הופכים לתאריכים רחוקים בעתיד.
עושים את זה עם EasyCoexistence

send_social_dm משיב בתוך חלון ה-24 שעות, והאוטומציות יכולות להשיב לבד עם טקסט קבוע או עם AI. מ-US$ 9 ועד US$ 0.75 לחיבור לחודש, כשהמחיר יורד ככל שמוסיפים חיבורים, עם 3 הימים הראשונים בחינם.

שאלות נפוצות

האם חותמות הזמן בוובהוק ההודעות של Instagram הן בשניות או במילישניות?

במילישניות, לפי הדוגמאות של Meta למסרי הודעות, גם לשדה timestamp וגם לשדה entry.time. אם קוראים אותן כשניות, הן הופכות לתאריכים רחוקים בעתיד.

איך מקבלים את שם המשתמש של השולח מוובהוק של הודעה ישירה ב-Instagram?

קוראים ל-GET /<IGSID> עם שדות כמו name ו-username. באירוע יש רק מזהה ה-Instagram-scoped של האדם.

למה וובהוק ההודעות שלי לא מגיע?

בדקו שהחשבון הפעיל לאפשר גישה להודעות, שהוא רשום להודעות דרך /subscribed_apps, ושהאפליקציה במצב Live עם Advanced Access לחשבונות שאינה בעלת עליהם.

האם easyCoexistence מעבירה ריאקציות להודעות ב-Instagram?

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

המשיכו לקרוא

וובהוק התגובות של Instagram (Webhook): ה-payload, שדה אחר שדהמה וובהוק התגובות של Instagram שולח כשמישהו מגיב לפוסטים וה-Reels של חשבון: ה-payload שדה אחר שדה, מה שהוא לא כולל, והמלכודות.אימות וובהוק (Webhook) של Instagram: hub.challenge וגם X-Hub-Signature-256איך מגדירים וובהוקים של Instagram: עונים ל-hub.challenge, בודקים את X-Hub-Signature-256 עם סוד האפליקציה, רושמים כל חשבון ומטפלים בניסיונות חוזרים.אירועי וובהוק (Webhook) של Instagram: תגובות, תיוגים והודעות DMכך מגיעים תגובות, תיוגים והודעות DM של Instagram לנקודת הקצה שלכם כאירועי וובהוק: מה כל payload כולל, איך נחתמות המסירות ומה לבדוק.הודעות DM ב-Instagram דרך ה-API וחלון ההודעות של 24 שעותאיך פועלות הודעות DM ב-Instagram דרך ה-API: למי אפשר לכתוב, חלון 24 השעות, תגובות פרטיות והגדרת הגישה להודעות.תגובות פרטיות ב-Instagram דרך ה-API: מענה לתגובה בהודעה ישירהשליחת תגובה פרטית ב-Instagram עם ה-API: POST /<IG_ID>/messages עם מזהה התגובה, אחת לכל תגובה תוך 7 ימים, וקוד שגיאה 2534025.@mentions ב-Instagram דרך ה-API: איתור ומענה להםאיך מגיעים @mentions של Instagram דרך ה-API ובוובהוק (Webhook) התגובות עם Instagram Login, ואיך משיבים להם בתגובות ובכיתובים.

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

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

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

נבדק ב-