Webhooks for Instagram Messaging

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 Advanced Access

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

App Modes

  • Development Mode – Webhooks will only be sent if the person using your app has a role on the app, even if your app has Advanced Access. You can only access data you own or administer.
  • Live Mode – Webhooks will be sent depending on access level.
    • Standard Access – 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.
    • Advanced Access – Webhooks will be sent when any person uses your app as long as the prerequisite permissions have been granted.

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

Limitations

  • When a customer reacts to or fowards 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.

Webhook Events

Webhook FieldDescription

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 triggger 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"
               }
            }
         ]
      }
   ]
}

See Also

  • Messenger Handover Protocol – If you have more than one app handling messages, for example, one app handles automated responses and one app handles escalations to a human agent, then you will need to implement the Handover Protocol to pass the conversation from one app to another.
  • Click To Direct, CTD – Visit the Business Helpcenter to learn more about creating ads that click to Instagram Direct.

Developer Support