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

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

NameDescriptionType

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

NameDescriptionType

id

The ID of a message

string

created_time

Created time

datetime

Message Details

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

NameDescriptionType

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

NameDescriptionType

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

NameDescriptionType

reaction

Reaction type

string

users

Image data

Array of Struct { username => string, id => string, user_id => string }

Share Struct

NameDescriptionType

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

NameDescriptionType

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

CodeSubcodeMessage

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.