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.

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