Webhook

The Messenger Platform sends events to your webhook to notify you when a variety of interactions or events happen, including when a person sends a message. Webhook events are sent by the Messenger Platform as POST requests to your webhook.

Basic Webhook Requirements

To receive Messenger API support for Instagram (also known as Instagram Messaging API in our Developer Policies) webhook events, all the following must be met:

Webhooks in Live Mode/Advanced Access

To receive webhooks for events from the public (users who do not have a role on your app, and outside of developer testing), all the following conditions must be met:

Webhooks in Development Mode/Testing/Standard Access

To receive webhooks for apps in development mode or with standard access, all the following conditions must be met:

And, the sender’s IG Account is any one of the following:

  • The IG account has a connected FB account with a tester role on the app (i.e. the IG account connected to the FB tester will work as an IG tester account)
  • The IG account has a connected FB account that has an app admin role
  • The IG account has a connected FB account that has a role of an app developer

Webhook Setup

Step 1: Create an Endpoint and Configure the Webhooks Product

Follow our Getting Started guide to create an endpoint that can accept and process Webhooks notifications and configure the Webhooks product using the App Dashboard(configuration via the App Subscriptions edge is not supported). During configuration, make sure to choose the Instagram object and subscribe to message field and select version >= 5.0.

Step 2: Enable Page Subscriptions

Your app must enable Page subscriptions on the Page connected to the app user's account by sending a POST request to the Page Subscribed Apps edge and subscribing to any page webhook field.

Endpoint Requirements

Request Syntax

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &fields={fields}

Request Parameters

Value Placeholder Value Description

{page_id}

ID of the Page connected to the app user's account.

{access_token}

The app user's Page Access Token.

{fields}

A Page Field (e.g, feed).

Technically it doesn't matter which Page Field you subscribe to. Your app will not receive notifications of changes to that field unless you configure Page subscriptions in the App Dashboard and subscribe to that field.

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/v12.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Sample Response

{
  "success": true
}

Confirm the connection by making a GET request which should return a non empty response.

curl -i -X GET \
 "https://graph.facebook.com/v12.0/me/subscribed_apps?access_token={PAGE_ACCESS_TOKEN_WITH_PAGES_MANAGE_METADATA}"

RESPONSE  
  "data": [
    {
      "category": "Business",
      "link": "https://www.example.com",
      "name": "ig-test-account",
      "id": "25415311452393514",
      "subscribed_fields": [
        "feed"
      ]    
    }
  ]  

Step 3: Subscribe to message webhook field

You will need to subscribe to the message webhook field under Instagram topic to start receiving webhooks.

  • Ensure that your app has added Webhooks product and setup the proper callback URL.
  • In the app dashboard, go to the webhook product section and subscribe your app to the messages webhook field under the Instagram topic with version >=v5.0.
  • In the app dashboard, toggle your app to live mode (apps in development mode won’t receive live webhooks).

Guidance on handling Messenger API support for Instagram CDN URLs

Messenger API support for Instagram (also known as Instagram Messaging API in our Developer Policies) leverages CDN URLs which allow you to retrieve rich media content shared by users. The CDN URL returned via webhooks, and the Conversation API, is privacy-aware. This means, the CDN URL will not return the media when the content is deleted or expired. You must not download, retain, or otherwise store on your system the media content sent or made accessible by any user via the API (or enable any third party to do so) and you, or any third party, must not do anything to circumvent expiration and/or removal of any link to such media content, without our prior permission. Instead, if your app requires continued access to the media made available via the IG Messaging API, you must only store the privacy aware CDN URL in your system and use that to render the media made accessible via the API.

Instagram Inbox Folder Behavior

When you switch to a Professional account, you’ll have access to an inbox that allows you to organize messages and control notifications. This organized inbox has 2 tabs: Primary and General.

  • Primary: The Primary tab is for messages you’d like to see first. All messages will appear in the Primary tab, but you can swipe them into the General tab. Notifications for unread messages are turned on for the Primary tab, but you can turn them off in Settings.

  • General: The General tab is for messages you’d like to get back to later. Notifications for unread messages are turned off for the General tab, but you can turn them on in Settings.

  • Requests: You can also see message requests in your inbox. Requests are direct messages from accounts that you don’t follow. You can choose to accept or deny these requests, and request messages aren’t marked as “seen” until you accept them. You can also move accepted messages into the Primary or General tabs.

Instagram Messaging APIs currently doesn’t support inbox folder capability. All messages (regardless of it's folder grouping in Instagram app Inbox) will be delivered without any indication on where the thread is located on the Instagram app Inbox folder. Webhooks/messages received via API will not be considered as read in the Instagram app inbox. Once the business reply via the API, the thread will be considered read.

To help keep your Instagram inbox organized, all message requests that you answer using a third-party tool will be moved to the General folder. Here’s how your Instagram inbox will function:

  • New chats from people you follow will continue to appear in the Primary folder.
  • Existing chats that are already in your Instagram inbox will remain in the folder you’ve previously selected.
  • Even if you've changed your settings to allow messages from certain people to go directly to your Primary folder, if you're answering these messages using a third-party tool, they'll go to your General folder.
  • You’ll still be able to move individual messages between the General and Primary folders.

For more details, please refer to this link.

Webhook Events

Webhook FieldWebhook EventDescription

messages

Message with text

Webhook when text message is received

messages

Message with media (image/video/file/audio)

Webhook when media is received

messages

Shares (media/post shares)

Webhook when media/post shares is received

messages

Story replies

Webhook when story replies is received

messages

Story mention

Webhook when story mention is received

messages

Inline message replies

Webhook when an inline message replies is received

messages

Stickers

Webhook when a sticker is received

messages

Message delete

Webhook when a message is deleted

messages

Message from Instagram Shops product detail page

Webhook when a user sends a message from IG Shops product detail page

messages

Echo webhook

Webhook when an IG Professional account sends a message. message_reactions event will not have an echo webhook delivered.

messages

Message unsupported

Webhook when an unsupported message is received

messages

Quick Replies

Webhook when a quick reply is selected

messaging_postbacks

Icebreaker, Generic Template

Webhook when an Icebreaker option or Generic Template button is selected

messaging_seen

Messaging Seen

Webhook when a message has been read by the recipient

message_reactions

Message Reaction

Webhook when a user react/unreact to a message

Message With Text

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",// ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_CONTENT>"
          }
        }
      ]
    }
  ],
}

Messaging Seen

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"<LAST_MESSAGE_ID_READ>"
               }
            }
         ]
      }
   ]
}

Message Reaction

Graph API v12.0+ message reaction webhook will return a new unicode format for emoji field. This change will take effect on all older Graph API versions starting Dec 14th, 2021.

Message reaction webhook will be delivered when a user react/unreact on a specific message. Message reaction webhook is only be available on Graph API v7.0+.

Graph API v11.0 and older before Dec 14th, 2021 (only support love reaction):

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>", // ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "<MID>",
            "action": "{react|unreact}",
            "reaction": "love", // optional i.e  in case of unreact no reaction field
            "emoji": "\\u{2764}\\u{FE0F}" // optional i.e  in case of unreact no emoji field
          } 
        }
      ]
    }
  ],
}  

Graph API v11.0 and older after Dec 14th, 2021 (only support love reaction):

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>", // ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "<MID>",
            "action": "{react|unreact}",
            "reaction": "love", // optional i.e  in case of unreact no reaction field
            "emoji": "\u{2764}\u{FE0F}" // [NEW] optional i.e  in case of unreact no emoji field
          } 
        }
      ]
    }
  ],
}  

Graph API v12.0+ supports multiple types of reactions

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>", // ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "<MID>",
            "action": "{react|unreact}",
            "reaction": "{angry|sad|wow|love|like|laugh|other}", // [NEW] optional i.e  in case of unreact no reaction field
            "emoji": "{\u{1F621}|\u{1F622}|\u{1F62E}|\u{2764}\u{FE0F}|\u{1F44D}|\u{1F602}|...other_emojis_unicode" // [NEW] optional i.e  in case of unreact no emoji field
          } 
        }
      ]
    }
  ],
}    

Message from Instagram Shops Product Detail Page

Message webhook from Facebook Shops product detail page is only available on Graph API v8.0+

{
  "sender": {
    "id": "<IGSID>"
  },
  "recipient": {
    "id": "<IGID>"
  },
  "timestamp": 1458692752478,
  "message": {
    "mid": "mid.1457764197618:41d102a3e1ae206a38",
    "text": "hello, world!",
    "referral": {
      "product": {
        "id": "<PRODUCT_ID>"
      }
    }
  }
}    

Echo Webhook

This callback will occur when a message has been sent by your IG account. is_echo flag will be present to indicate that the message is sent from the IG account itself. message_reactions event will not have an echo webhook delivered

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",// ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_CONTENT>"
            "is_echo": true
          }
        }
      ]
    }
  ],
}

Quick Replies

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGSID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1502905976377,
          "message": {
            "quick_reply": {
              "payload": "<PAYLOAD>"
            },
            "mid": "<MID>",
            "text": "<SOME_TEXT>"
          }
        }
      ]
    }
  ]
}

Icebreaker

June 8th, 2021 Announcement

The mid field was added in Graph API v11.0+

In order to receive postback webhooks from Icebreakers, make sure that the app has subscribed to messaging_postbacks v8.0+ webhook under Instagram topic on the app settings.

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGSID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1502905976377,
          "postback": {
            "mid":"<MESSAGE_ID>",
            "title": "<SELECTED_ICEBREAKER_QUESTION>",
            "payload": "<USER_DEFINED_PAYLOAD>",
          }
        }
      ]
    }
  ]
}

     

Generic Template

June 8th, 2021 Announcement

The mid field was added in Graph API v11.0+

In order to receive postback webhooks from Generic Template, make sure that the app has subscribed to messaging_postbacks v8.0+ webhook under Instagram topic on the app settings.

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGSID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1502905976377,
          "postback": {
            "mid":"<MESSAGE_ID>",
            "title": "<TITLE_FOR_THE_CTA>",
            "payload": "<USER_DEFINED_PAYLOAD>",
          }
        }
      ]
    }
  ]
}
     

Message Unsupported

For any unsupported message type, we send the following webhook event:

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",// ig id of the Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "<IGSID>"
          },
          "recipient": {
            "id": "<IGID>"
          },
          "timestamp": 1569262485349,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_CONTENT>" // optional
            "is_unsupported": "true", //not included if message is supported
          }
        }
      ]
    }
  ],
}

Message With Media (Permanent image/video/file/media share)

For messages that contain media, we send a message unsupported webhook event, so you can leverage the Conversations API to fetch messages with an attachment. If the Conversations API returns the is_unsupported message flag, it indicates that the media is not yet supported.

Message With Media (image/video/file/audio)

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "attachments":[
                     {
                        "type":"{video|audio|file|image}",
                        "payload":{
                           "url":"<CDN_LINK>"
                        }
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Shares (media/post shares)

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "attachments":[
                     {
                        "type":"share",
                        "payload":{
                           "url":"<CDN_URL>"
                        }
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Story Replies

Story Replies webhook currently doesn't support GIF or sticker.

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "text":"<MESSAGE_CONTENT>",
                  "reply_to":{
                     "story":{
                        "url":"<CDN_URL>",
                        "id":"story_id"
                     }
                  }
               }
            }
         ]
      }
   ]
}

Story Mention

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "attachments":[
                     {
                        "type":"story_mention",
                        "payload":{
                           "url":"<CDN_URL>"
                        }
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Inine Message Replies

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "text":"<MESSAGE_CONTENT>",
                  "reply_to":{
                     "mid":"<MESSAGE_ID>"
                  }
               }
            }
         ]
      }
   ]
}

Stickers

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "attachments":[
                     {
                        "type":"image",
                        "payload":{
                           "url":"<STICKER_LINK>"
                        }
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Message Delete

{
   "object":"instagram",
   "entry":[
      {
         "id":"<IGID>",
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "message":{
                  "mid":"<MESSAGE_ID>",
                  "is_deleted":"true"
               }
            }
         ]
      }
   ]
}