Story Mention

An Instagram Professional account can be notified when a user mentions them in a story. When this happens, the IG Professional account will get a message in the inbox referencing the story that the user posted. Due to a story being ephemeral by nature (it will disappear after 24 hours or when deleted by the user), you must meet specific requirements and implementation guidelines to comply and respect user privacy for ephemeral content.

Story mention is part of the app review requirements for instagram_manage_messages permission. Please ensure that you meet all the story mention requirements before submitting for app review.

Important Points

  • A Story mention webhook will only flow in if the user mentioning the account has their account setup as public. Story mentions from a private account will only flow in if the account follows the said account.
  • You must not store/cache the media content on your server.

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.

Developer Implementation Flow

  • You will get a webhook for every story mention received with the story CDN URL. You may store the CDN URL on your system to avoid repeated calls to conversation API. You must not store the media content on your server.
  • When the agent clicks on the content or opens the thread, it will trigger a call to your server.
  • The agent’s browser renders the content using the CDN URL obtained via webhooks/Conversation API.
  • Once the user deletes a story/expired, the URL will stop rendering and you should show a placeholder message indicating that the story content is no longer available.

Rendering Story in Agent’s Inbox/Client View

There are several options where you can choose to render the story content in the agent’s inbox:

  • In-thread rendering - For this scenario/behavior, when the agent clicks a particular thread, you will load the CDN URL and render it on the client’s side.
  • User action rendering - For this scenario/behavior, story content is rendered with a placeholder and when the user clicks on display/view button, you will load the CDN URL and render it on the client’s side.

Example webhook

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

Example request to retrieve story mention via Conversation API

GET <MESSAGE_ID>?fields=story

{
  "story": {
    "mention": {
      "link": "<CDN_URL>",
      "id": "<STORY_ID>"
    }
  },
  "id": "<MESSAGE_ID>"
}