Conversation API can be used to retrieve conversation history from an Instagram business account. Conversation API consists of 3 main API:
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>" }, ... ] }
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>" }, ] }
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 }, ] } }
Name | Description | Type |
---|---|---|
| The ID of a conversation |
|
| Last update time |
|
| Participants on this conversation | Array of |
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>" }, ... ] }
Name | Description | Type |
---|---|---|
| The ID of a message |
|
| Created time |
|
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" }, {..}], } } } } }] }
Name | Description | Type |
---|---|---|
| The ID of a message |
|
| Created time |
|
| The sender of message |
|
| The recipient of message | Array of |
| Flag on whether the message type is supported. The field will not be returned for supported message type |
|
| Text content of the message |
|
| Attachment of the message |
|
| Reaction (like/love) on the existing message |
|
| Media shares (post, product template) of the message |
|
| Story content of the message. Only |
|
Name | Description | Type |
---|---|---|
| The ID of the attachment |
|
| Image data |
|
| Name of the attachment |
|
| Video data |
|
| File URL |
|
Name | Description | Type |
---|---|---|
| Reaction type |
|
| Image data | Array of |
Name | Description | Type |
---|---|---|
| URL of the shared content |
|
| Product template details | Array of |
Name | Description | Type |
---|---|---|
| The id of the story |
|
| URL of the shared content |
|
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. 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.
Code | Subcode | Message |
---|---|---|
|
| Unsupported get request. Object with ID 'ABC' does not exist, cannot be loaded due to missing permissions, or does not support this operation. |
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:
For more details, please refer to this link.