Guide to Instagram channel message data

Fetching information about messages sent on a specific Instagram channel requires that you first obtain the Meta Content Library ID for the channel by using the get() method with the instagram/channels/preview path. The search results will include the ID field by default (you don't have to specify it in your query). See Guide to Instagram channel data to learn about this method. Meta Content Library IDs are unique IDs, each linked to an entity in Meta Content Library. These IDs cannot be used to search on Meta technologies.

Once you have the channel ID, you can use it to fetch information about messages using either a synchronous endpoint (accepts one ID) or an asynchronous endpoint (accepts multiple IDs).

Channel messages can have comments which you can retrieve using the get() method with the instagram/channels/<instagram_channel_id>/messages/preview path. See Guide to Instagram comments data for more information.

This document describes the parameters and shows how to fetch messages using the synchronous and asynchronous endpoints.

All of the examples in this document are taken from a Secure Research Environment use case and assume you have already created a Python or R Jupyter notebook and have created a client object. See Getting started to learn more.

See Data dictionary for detailed information about the data fields that are returned.

Synchronous endpoint

You can fetch information about messages sent on a single Instagram channel by using the get() method with the <IG_CHANNEL_MCL_ID>/messages path. Only the last 1000 messages sent from the channel are fetched and no filtering or sorting is applied to the response.

Parameters

Asynchronous endpoint

Using the asynchronous endpoint, you can fetch messages from multiple Instagram channels in one request, and you can narrow the results based on a text filter. This is similar to retrieving bulk comments. The maximum number of channel IDs that can be included in a single query is 250.

Note: You can estimate the size of results as described in the Search guide, but the text filter is not applied until after the estimate is generated. Because the returned estimate does not take into account the text filter, it is likely to be higher, even significantly higher, than the actual number of returned messages.

Call the Meta Content Library API client post() method with the /instagram/channel-messages/job path, and include the channel_ids parameter.

Parameters

Sample queries

Fetch information about messages sent on one Instagram channel

The following synchronous query example would return 10 results per page. You can keep calling query_next_page() and has_next_page() to get the next page of 10 results, until all the query results have been returned.

library(reticulate)
client <- import("metacontentlibraryapi")$MetaContentLibraryAPIClient

client$set_default_version(client$LATEST_VERSION)


# Fetch first 10 messages
response <- client$get("path=instagram/channels/<instagram_channel_id>/messages/preview")
jsonlite::fromJSON(response$text, flatten=TRUE)


# Fetch next page
if (client$has_next_page(response)) {
    response <- client$query_next_page(response)
    jsonlite::fromJSON(response$text, flatten=TRUE) # Display second page
}

from metacontentlibraryapi import MetaContentLibraryAPIClient as client
client.set_default_version(client.LATEST_VERSION)


# Fetch first 10 messages
response = client.get(path="instagram/channels/<instagram_channel_id>/messages/preview")

display(response.json()) # Display first page


# Fetch next page
if client.has_next_page(response):
    response = client.query_next_page(response)
    display(response.json()) # Display second page

Request messages from multiple channels

This example shows using the channel_ids parameter to specify the Instagram channel IDs for which to retrieve messages. The IDs would be known to you after querying for Instagram channels. This example also shows checking the status of the asynchronous query and retrieving the results of the query once the status is complete. These are functions available for all asynchronous queries.

library(reticulate)
meta_content_library_api <- import("metacontentlibraryapi")
client <- meta_content_library_api$MetaContentLibraryAPIClient


# Set the default version to the latest available
client$set_default_version(client$LATEST_VERSION)

async_utils <- meta_content_library_api$MetaContentLibraryAPIAsyncUtils


# Submit an asynchronous query using instagram/channel-messages/job
response <- client$post(path="instagram/channel-messages/job", params=list("channel_ids"=list("588715460327330", "702578718914175")))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display the query handle


# Check the status of an asynchronous query
status_response <- async_utils$get_status(response=response)
jsonlite::fromJSON(status_response$text, flatten=TRUE) # Display the query status


# Retrieve the results of an asynchronous query when status is "COMPLETE"
get_data_response <- async_utils$get_data(response=response)
jsonlite::fromJSON(get_data_response$text, flatten=TRUE) # Display the query results

from metacontentlibraryapi import (
    MetaContentLibraryAPIClient as client,
    MetaContentLibraryAPIAsyncUtils as async_utils,
)

# Set the default version to the latest available
client.set_default_version(client.LATEST_VERSION)


# Submit an asynchronous query using instagram/channel-messages/job
response = client.post(
    path="instagram/channel-messages/job",
    params={"channel_ids":["588715460327330","702578718914175"]},
)
display(response.json()) # Display the query handle


# Check the status of an asynchronous query
status_response = async_utils.get_status(response=response)
display(status_response.json()) # Display the query status


# Retrieve the results of an asynchronous query when status is "COMPLETE"
get_data_response = async_utils.get_data(response=response)
display(get_data_response.json()) # Display the query results

Request messages from multiple channels, filtered by specified text

The following example retrieves messages from multiple channels and also filters the loaded messages by the specified text.

library(reticulate)
meta_content_library_api <- import("metacontentlibraryapi")
client <- meta_content_library_api$MetaContentLibraryAPIClient


# Set the default version to the latest available
client$set_default_version(client$LATEST_VERSION)


async_utils <- meta_content_library_api$MetaContentLibraryAPIAsyncUtils


# Submit an asynchronous query using instagram/channel-messages/job
response <- client$post(path="instagram/channel-messages/job", params=list("channel_ids"=list("588715460327330", "702578718914175"), "text_filter"="meta"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display the query handle

from metacontentlibraryapi import (
    MetaContentLibraryAPIClient as client,
    MetaContentLibraryAPIAsyncUtils as async_utils,
)


# Set the default version to the latest available
client.set_default_version(client.LATEST_VERSION)


# Submit an asynchronous query using instagram/channel-messages/job and a text filter
response = client.post(
    path="instagram/channel-messages/job",
    params={"channel_ids":["588715460327330","702578718914175"], "text_filter": "meta"},
)
display(response.json()) # Display the query handle

Including multimedia in search results

Multimedia in responses to queries on Secure Research Environment include the type of media (photo, video), a Meta Content Library ID, the duration and any user tags. You can get the URL for the media by querying for ”fields”=”multimedia{url}”.

Multimedia is not included in responses to queries in third-party cleanrooms by default. Third-party cleanroom users can get multimedia by querying for ”fields”=”multimedia”. In addition to the type, Meta Content Library ID, duration and user tags, the URL is included in multimedia responses in third-party cleanrooms. Multimedia is available in posts from Facebook Pages, profiles, groups, and events.

• Include the keyword multimedia in your query (fields parameter) on third-party cleanrooms, because multimedia is not included by default.

• Include the keyword multimedia{url} in your query (fields parameter) on Secure Research Environment to obtain the media URL, because the URL is not included by default.

• To display multimedia in Secure Research Environment use display_media().

• The number of calls allowed that include multimedia is controlled by a multimedia query budget specific to the third-party cleanroom environment. See Rate limiting and query budgeting for multimedia for more information. To download multimedia content, use download_multimedia_by_content_ids() with a list of known content IDs. See Guide to ID-based retrieval for information on how to retrieve content IDs.

# Load required libraries
library(reticulate)
meta_content_library_api <- import("metacontentlibraryapi")
utils <- meta_content_library_api$MetaContentLibraryAPIMultimediaUtils
# Provide a comma-separated list of content ids as strings
ids_to_download <- c("553170087752425", "681021651202495")
# Download the multimedia content
utils$download_multimedia_by_content_ids(ids_to_download)
# The file path is displayed when the above command is run
utils$display_media(<FILE_PATH>)

from metacontentlibraryapi import MetaContentLibraryAPIMultimediaUtils as 
      utils
from typing import List
# Provide a comma-separated list of content ids as strings
ids_to_download: List[str] = ['553170087752425', '681021651202495'] # List of IDs to download
# You will receive the path of each content id as output
# You can also view multimedia in media folder with path media/<content_id>/
utils.download_multimedia_by_content_ids(ids_to_download, response=response)
# The file path is displayed when the above command is run
utils.display_media(<FILE_PATH>)

Learn More

• Getting started
• Data dictionary
• Guide to Instagram channel data
• Search guide
• Guide to ID-based retrieval
• Guide to Instagram comments data
• Guide to bulk comments data