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 IG Messaging 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 role of an IG tester in the IG app
  • 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/v11.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/v11.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 Instagram Messaging CDN URLs

Instagram Messaging API 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.

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 business account sends a message

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

In-line Liking

Webhook when a user react/unreact to a message

Message With Text

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",// ig id of the business
      "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,
         "message":[
            {
               "sender":{
                  "id":"<IGSID>"
               },
               "recipient":{
                  "id":"<IGID>"
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"<LAST_MESSAGE_ID_READ>"
               }
            }
         ]
      }
   ]
}

In-like Liking

In-line Liking webhook is only be available on Graph API v7.0+

In-line liking webhook will be delivered when a user react/unreact on a specific message.

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>", // ig id of business
      "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
          } 
        }
      ]
    }
  ],
}  

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.

{
  "object": "instagram",
  "entry": [
    {
      "id": "<IGID>",// ig id of the business
      "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 business
      "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

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