Guide to WhatsApp channel update data

Fetching information about channel updates sent on a specific WhatsApp channel requires that you first obtain the Meta Content Library ID for the channel by using the get() method with the /whatsapp/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 WhatsApp 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 channel updates using either a synchronous endpoint (accepts one ID) or an asynchronous endpoint (accepts multiple IDs).

This document describes the parameters and explains how to fetch updates 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 channel updates sent on a single WhatsApp channel by using the get() method with the /whatsapp/channels/{mcl_id}/updates/preview path. Only the last 1000 channel updates sent from the channel are fetched and no filtering or sorting is applied to the response. 10 channel updates are available by default.

Parameters

Asynchronous endpoint

Using the asynchronous endpoint, you can fetch channel updates from multiple WhatsApp 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 request 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, and even significantly higher, than the actual number of returned channel updates.

Call the Meta Content Library API client post() method with the whatsapp/channel-updates/job path, and include the CHANNEL_IDS parameter.

Parameters

Sample queries

Fetch information about channel updates sent on one WhatsApp 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 updates
response <- client$get(path="whatsapp/channels/553792874450847/updates/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 updates
response = client.get(path="whatsapp/channels/553792874450847/updates/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 channel updates from multiple channels, filtered by specified text

The following example retrieves channel updates from multiple channels and also filters the loaded channel updates 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)

# Submit an asynchronous query using POST whatsapp/channel-updates/job
response <- client$post(path="whatsapp/channel-updates/job", params=list("channel_ids"=list("911092061091664", "1457577498566346"), "text_filter"="champion"))

jsonlite::fromJSON(response$text, flatten=TRUE) # Display the query handle

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

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

# Submit an asynchronous query using POST whatsapp/channel-updates/job
response = client.post(
    path="whatsapp/channel-updates/job",
    params={"channel_ids":["911092061091664","1457577498566346"], "text_filter": "champion"},
)

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 or audio) and a Meta Content Library ID. 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, the URL is included in multimedia responses in third-party cleanrooms.

• 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 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(<MCL_ID_1>, <MCL_ID_2>)
# 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>)

ffrom metacontentlibraryapi import MetaContentLibraryAPIMultimediaUtils as utils
from typing import List
# Provide a comma-separated list of content ids as strings
ids_to_download: List[str] = [<MCL_ID_1>, <MCL_ID_2>] # 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)
# The file path is displayed when the above command is run
utils.display_media(<FILE_PATH>)

Learn More

• Guide to WhatsApp channel data
• Search guide
• Data dictionary
• Guide to bulk comments data