Conversation API

Conversation API can be used to retrieve conversation history from an Instagram business account. Conversation API consists of 3 main API:

Conversation list
Message list
Message details

Conversation List

This API allows you to query list of conversations between a user and an Instagram business account. You can leverage this API to do inbox syncing on past conversations when an IG business account is newly connected to your app.

GET <PAGE_ID>/conversations?platform=instagram
{
  "conversations": {
    "data": [
      {
        "id": "<THREAD_ID1>"
      },
      {
        "id": "<THREAD_ID2>"
      },
      ...
   ]
}

IGSID Filtering

The API supports additional filtering by IGSID. When user_id is specified in the conversation API, it will only return the thread which belongs to the specific user.

GET <PAGE_ID>/conversations?platform=instagram&user_id=<IGSID>
{
  "conversations": {
    "data": [
      {
        "id": "<THREAD_ID>"
      },
   ]
}

Thread Metadata

Graph API v12.0+ Conversation API will no longer return user_id field. This change will take effect on all older Graph API versions starting Dec 14th, 2021. Developer should leverage IGSID as the primary identifier of the thread between user and business.

The API supports various thread metadata to allow you to get more context on the specific thread/conversation.

GET <THREAD_ID>?fields=...
      {
        "id": "<THREAD_ID>"
        "messages": <EDGE_TO_MESSAGES>
        "participants": {
            'data': [
                {
                    "username": "<IG_USER_NAME>" // user name of the user 
                    "id":  "<IGSID>" // ig scoped id of the user  
                },
                {
                    "username": "<IG_USER_NAME>",// username of the business
                    "id":  "<IGID>", // business id      
                },
            ]
        }
      }

Fields

Name	Description	Type
`id`	The ID of a conversation	`string`
`updated_time`	Last update time	`datetime`
`participants`	Participants on this conversation	Array of `Struct` { `username` => string, `id` => string }

Message List

The messages field can be used to retrieve a list of message_id from a specific thread.

GET <THREAD_ID>?fields=messages
{
  "data": [
      {
        "id": "<MESSAGE_ID1>",
        "created_time": "<TIMESTAMP>"
      },
      {
        "id": "<MESSAGE_ID2>",
        "created_time": "<TIMESTAMP>"
      },
      ...
   ]
}

Fields

Name	Description	Type
`id`	The ID of a message	`string`
`created_time`	Created time	`datetime`

Message Details

The API supports various fields to retrieve more details from a specific message_id.

GET <MESSAGE_ID>?fields=...

    {
      "id": "<MESSAGE_ID>",
      "created_time": "<TIMESTAMP>",
      "from": {
        "username": "<IG_USERNAME>",
        "id": "<IGSID|IGID>", // if sender is business then IGID else IGSID
      },
      "message": "<MESSAGE_TEXT>",
      "to": {
        "data": [
          {
            "username": "<IG_USERNAME>",
            "id": "<IGSID|IGID>", // if sent to business then IGID else IGSID
          }
        ]
      },
      "is_unsupported": "true",// not included if message type is supported
      "attachments": {
        "data": [
          <Attachment>
        ],
      },
       "reactions" : {
            "data": [
                <Reaction>
            ]
        },
      "shares": { //Please note, for the shares object you need to request the sub-fields also inorder to retrieve the data.
        "data": [
          <Share>
        ],
      },
     "story" : { 
        "reply_to": <StoryReply>, // Story Reply Feature
        "mention": <StoryMention> // Story Mention Feature
      },
    }

Attachment:
{
    "id": "<ID>",
    "image_data": {
        "url": "<CDN_URL>"
    },
    "name": "<NAME>",
    "video_data": {
        "url": "<CDN_URL>",
    }
    "file_url": "<CDN_URL>"
 }

Share: //Please note, for the shares object you need to request the sub-fields 
{      //also inorder to retrieve the data.
    "link": "<URL>",
    "template": <Product>
}

Reaction:
{
    "reaction": "love",
    "users" : [
        {
            "username": "<IG_USERNAME>",
            "id": "<IGSID|IGID>", //if sent to business then IGID else IGSID
         },
    ]
}

StoryReply: 
{
    "link": "<CDN_URL>",
    "id": "<STORY_ID>"
}

StoryMention: 
{
    "link": "<CDN_URL>",
    "id": "<STORY_ID>"
}

Product:  // Graph API v8.0+
"shares": {
  "data": [{
    "template": {
      "payload":{
        "product": {
           "elements":{ // multiple elements in Hscroll
             "data": [
              {
                "id" : "<Product_id>", // 0 if business can't see this product
                "retailer_id": "<EXTERNAL_ID>", 
                "image_url" : "https://fb.cdn.com/sdsd",
                "name" : "Some product title",
                "price" : "$10"
              },
              {..}],
             }
           }
         }
       }
    }]
}

Fields

Name	Description	Type
`id`	The ID of a message	`string`
`created_time`	Created time	`datetime`
`from`	The sender of message	`Struct` { `username` => string, `id` => string}
`to`	The recipient of message	Array of `Struct` { `username` => string, `id` => string}
`is_unsupported`	Flag on whether the message type is supported. The field will not be returned for supported message type	`boolean`
`message`	Text content of the message	`string`
`attachments`	Attachment of the message	`Attachment Struct`
`reactions`	Reaction (like/love) on the existing message	`Reaction Struct`
`shares`	Media shares (post, product template) of the message	`Share Struct`
`story`	Story content of the message. Only `story mention` and `story reply` are supported.	`Story Struct`

Attachment Struct

Name	Description	Type
`id`	The ID of the attachment	`string`
`image_data`	Image data	`Struct` { `url` => string }
`name`	Name of the attachment	`string`
`video_data`	Video data	`Struct` { `url` => string }. (Note: `preview_url` field is not supported and will return the same value as `url`)
`file_url`	File URL	`string`

Reaction Struct

Name	Description	Type
`reaction`	Reaction type	`string`
`users`	Image data	Array of `Struct` { `username` => string, `id` => string, `user_id` => string }

Share Struct

Name	Description	Type
`link`	URL of the shared content	`string`
`template`	Product template details	Array of `Struct` { `id` => string, `retailer_id` => string, `image_url` => string, `name` => string, `price` => string }

Story Struct

Name	Description	Type
`id`	The id of the story	`string`
`link`	URL of the shared content	`string`

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.

Error Codes

Code	Subcode	Message
`100`	`33`	Unsupported get request. Object with ID 'ABC' does not exist, cannot be loaded due to missing permissions, or does not support this operation.

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.