Instagram Messaging

Webhooks for Instagram Messaging

Updated: Apr 1, 2026

Webhooks allows you to receive real-time HTTP notifications of changes to specific objects in the Meta social graph. For example, we could send you a notification when a customer sends your Instagram Professional account a message. Webhooks notifications allow you to track messaging changes and avoid rate limits that would occur if you were querying the Messenger Platform endpoints to track changes.

Requirements

You will need to implement the following requirements to receive Webhooks notifications for Instagram Messaging.

The instagram_basic, instagram_manage_messages, and pages_manage_metadata permissions

To get webhooks notification that include data owned or managed by people who do not have a role on your app, your app must have been approved in App Review. Your app user must have granted your app the prerequisite permissions.

If your app has not been approve, pending or review is not needed, Webhooks will only be sent if the person using your app has a role on the app. You can only access data you own or administer.

Your app must be published, regardless of app review status, to receive webhooks.

Note: You will need to subscribe all messaging apps for your business to the messaging webhooks.

Learn more about access levels, app modes and app roles.

Limitations

When a customer reacts to or forwards an image from a carousel in an Instagram Post, the notification will include the first image in the carousel which may not be the image the customer reacted to or forwarded.

Only the URL for the shared media or post is included in the notification when a customer sends a message with a share.

Messages with gifs and stickers are not supported. If a person sends a message with a gif or sticker a webhook will not be triggered and a webhook notification will not be sent.

Disappearing media⁠ (view once, allow replay) is not supported on Instagram media webhooks.

Webhook Events

Webhook Field	Description
`message_reactions`	A notification is sent when a customer reacts or unreacts to a message Graph API v12.0 and later supports `angry`, `sad`, `wow`, `love`, `like`, `laugh`, and `other` reactions.
`messages`	A notification is sent when a customer sends your business: a message with text or media (image/video/file/audio) a share (media/post shares) a story reply or mention. Only story mentions will trigger a webhook. Tagging on regular posts will not trigger a webhook. Story Replies webhook currently doesn’t support GIF or sticker. an inline message reply or sticker a quick reply or Icebreaker option or Generic Template button is selected a customer deletes a message a message from a customer is unsupported a customer sends a message from an Instagram Shops product detail page a customer clicks an ad that goes to an Instagram Messaging conversation (Click To Direct, CTD)⁠ A notification is also sent when your business sends a message to a customer. A notification will not be sent when your business reacts or unreacts to a customer message. This callback will occur when a message has been sent by your Instagram account. `is_echo` flag will be present to indicate that the message is sent from the Instagram account itself. `message_reactions` event will not have an echo webhook delivered
`messaging_postbacks`	A notification is sent when a customer clicked an Icebreaker option or Generic Template button Requires v8.0 or later. Requires v11.0 or later for inclusion of the `mid` field.
`messaging_seen`	A notification is sent when a message has been read by the recipient
`messaging_referral`	A notification is sent when an `ig.me` link with a referral parameter is clicked by a customer in an existing conversation
`standby`	When the messaging flow has multiple apps, a notification is sent when a customer sends your business a message but the app is not in control of the conversation at the time the message was sent.

Example Notifications

The following are examples for the types of webhooks notifications you can receive.

Messages

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business

            "text": "MESSAGE-TEXT"     // Included when a customer sends a message containing text

            "attachments": [           // Included when a customer sends multiple media attachments or a URL for a story mention or share
              {
                "type":"image",             // Can be audio, file, image (image or sticker), share, story_mention, video, ig_reel or reel
                "payload":{ "url":"LINK" }
              },
              {
                "type":"video",
                "payload":{ "url":"LINK" }
              }
            ]

            "is_deleted": true         // Included when a customer deletes a message

            "is_echo": true            // Included when your business sends a message to the customer

            "is_unsupported": true,    // Included when a customer sends a message with unsupported media

            "quick_reply": {           // Included when a customer clicks a quick reply
              "payload": "CUSTOMER-RESPONSE-PAYLOAD"   // The payload with the option selected by the customer
            },

            "referral": {              // Included when a customer clicks an Instagram Shop product
              "product": {
                "id": "PRODUCT-ID"
            }

            "referral": {                   // Included when a customer clicks an CTD ad
              "ref": "REF-DATA-IN-AD-IF-SPECIFIED"
              "ad_id": AD-ID,
              "source": "ADS",
              "type": "OPEN_THREAD",
              "ads_context_data": {
                "ad_title": TITLE-FOR-THE-AD,
                "photo_url": IMAGE-URL-THAT-WAS-CLICKED,
                "video_url": THUMBNAIL-URL-FOR-THE-AD-VIDEO,
              }
            }

            "reply_to":{               // Included when a customer sends an inline reply
              "mid":"MESSAGE-ID"
            }

            "reply_to": {               // Included when a customer replies to a story
              "story": {
                "url":"CDN-URL",
                "id":"STORY-ID"
              }
            }
          }
        }
      ]
    }
  ]
}

Message Reactions

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID for your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID for your Instagram Professional account
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "MESSAGE-ID",
            "action": "react",    // or unreact
            "reaction": "love", // optional, to unreact if there is no reaction field
            "emoji": "\u{2764}\u{FE0F}" // optional, to unreact if there is no emoji field
          }
        }
      ]
    }
  ]
}

Messaging Postbacks

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1502905976377,
          "postback": {
            "mid":"MESSAGE-ID",           // ID for the message sent to your business
            "title": "SELECTED-ICEBREAKER-REPLY-OR-CTA-BUTTON",
            "payload": "CUSTOMER-RESPONSE-PAYLOAD",  // The payload with the option selected by the customer
          }
        }
      ]
    }
  ]
}

Messaging Referral

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID of your Instagram Professional account
          },
          "timestamp": 1502905976377,
          "referral": {
                 "ref": "INFORMATION-INCLUDED-IN-REF-PARAMETER-OF-IGME-LINK"
                 "source": "IGME-SOURCE-LINK"
                 "type":  "OPEN_THREAD"  // Only supported for existing conversations
          }
        }
      ]
    }
  ]
}

Messaging Seen

{
   "object":"instagram",
   "entry":[
      {
         "id":"IGID",  // ID for your Instagram Professional account
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"IGSID"  // Instagram-scoped ID for the customer who sent the message
               },
               "recipient":{
                  "id":"IGID"  // ID for your Instagram Professional account
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"MESSAGE-ID"
               }
            }
         ]
      }
   ]
}

Disappearing Media

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business
            "attachments": [
              {
                "type":"ephemeral" // no URL is included for ephemeral media
              }
            ]
          }
        }
      ]
    }
  ]
}