Guide to WhatsApp channel data

You can perform WhatsApp channel searches by calling the Meta Content Library API client get() method with the whatsapp/channels/preview path. This document describes the parameters, and shows how to perform basic queries using the method.

All of the examples in this document are taken from a Secure Research Environment use case and assume you have created a Jupyter notebook and a client object. See Getting started to learn more. See Data dictionary for detailed information about the fields that are available on a WhatsApp channel node.

Parameters

Parameter	Type	Description
`Q` Required if `CHANNEL_IDS` parameter is not provided. Optional otherwise.	String	Keyword(s) to search for. Searches the channel `name` and `description` fields. See Advanced search guidelines for information about how multiple keyword searches with Boolean operators are handled.
`CHANNEL_IDS` Required if `Q` parameter is not provided. Optional otherwise.	List	Comma-separated list of Meta Content Library WhatsApp channel IDs to include in the search.
`CATEGORIES` Optional	List	Comma-separated list of category names to include in the search. Keywords can be used to match categories. Categories are visible in the Meta Content Library UI.
`SORT` Optional	Enum	Sort mode specifying the order in which channels are returned (only available for synchronous searches). Available options: `most_to_least_follower_count`: Channels are sorted by the number of followers on the channel, from most to least. `most_to_least_channel_updates`: Channels are sorted by the number of updates on the channel, from most to least. Sorting can be delayed by up to 2 days and only the updates from the last 30 days are available. `oldest_to_newest`: Channels are returned in chronological order according to creation time (oldest first). `newest_to_oldest`: Channels are returned in reverse chronological order according to creation time (newest first). Default: `most_to_least_follower_count`
`FOLLOWER_COUNT_MIN` Optional	Int	Returns channels with the specified minimum number of followers. Can be used with `FOLLOWER_COUNT_MAX` to specify a follower count range.
`FOLLOWER_COUNT_MAX` Optional	Int	Returns channels with the specified maximum number of followers or fewer. Can be used with `FOLLOWER_COUNT_MIN` to specify a follower count range. If you specify a follower count maximum but no minimum, the minimum defaults to 0.
`IS_CHANNEL_VERIFIED` Optional	Boolean	Whether the channel has a verified badge.
`LIMIT` Optional	Int	Integer from 10 to 50 specifying the page size for search results.
`SINCE` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. WhatsApp channels created on or after this date or timestamp are returned (used with `UNTIL` to define a time range). `SINCE` and `UNTIL` are based on UTC time zone, regardless of the local time zone of the channel owner. If both `SINCE` and `UNTIL` are included, the search includes the time range defined by those values. If `SINCE` is included and `UNTIL` is omitted, the search includes the `SINCE` time through the present time. If `SINCE` is omitted and `UNTIL` is included, the search goes from the beginning of WhatsApp time through the `UNTIL` time. If `SINCE` and `UNTIL` are both omitted, the search goes from the beginning of WhatsApp time to the present time. If `SINCE` and `UNTIL` are the same UNIX timestamp, the search includes the `SINCE` time through the `SINCE` time plus one hour. If `SINCE` and `UNTIL` are the same date (YYYY-MM-DD), the search includes the `SINCE` date through the `SINCE` date plus one day.
`UNTIL` Optional	String or Integer	Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. WhatsApp channels created on or before this date or timestamp are returned (used with `SINCE` to define a time range). `SINCE` and `UNTIL` are based on UTC time zone, regardless of the local time zone of the channel owner. If both `SINCE` and `UNTIL` are included, the search includes the time range defined by those values. If `SINCE` is included and `UNTIL` is omitted, the search includes the `SINCE` time through the present time. If `SINCE` is omitted and `UNTIL` is included, the search goes from the beginning of WhatsApp time through the `UNTIL` time. If `SINCE` and `UNTIL` are both omitted, the search goes from the beginning of WhatsApp time to the present time. If `SINCE` and `UNTIL` are the same UNIX timestamp, the search includes the `SINCE` time through the `SINCE` time plus one hour. If `SINCE` and `UNTIL` are the same date (YYYY-MM-DD), the search includes the `SINCE` date through the `SINCE` date plus one day.

Sample queries

Search for channels by keyword

To search for WhatsApp channels that contain a specific keyword use the get() method with the q parameter. See Advanced search guidelines for information about how multiple keyword searches are handled.

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

client$set_default_version(client$LATEST_VERSION)

response <- client$get(path="whatsapp/channels/preview", params=list("q"="whatsapp"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

from metacontentlibraryapi import MetaContentLibraryAPIClient as client
client.set_default_version(client.LATEST_VERSION)
response = client.get(
    path="whatsapp/channels/preview",
    params={"q":"whatsapp"},
)
display(response.json()) # Display first page

You can iterate through responses by using the query_next_page() method. You can keep calling query_next_page() to get the next page of 10 results, until all the search results have been returned. You can call has_next_page() to check if there is more data. See Search guide for other display and storage options.

Search for channels by follower count

To search for WhatsApp channels that have a follower count within a specific range, use the get() method with the follower_count_min and follower_count_max parameters. You do not have to use both.

The following example returns channels that have 10,000 to 50,000 followers.

response <- client$get(path="whatsapp/channels/preview", params=list("follower_count_min"="10000", "follower_count_max"="50000", "q":"whatsapp"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

response = client.get(
    path="whatsapp/channels/preview",
    params={"follower_count_min":"10000", "follower_count_max":"50000", "q":"whatsapp"},
)
display(response.json()) # Display first page

Search for channels by verified status and category

The following example shows searching for verified channels with a specified category using the get() method with the is_verified and categories parameters.

response <- client$get(path="whatsapp/channels/preview", params=list("categories"="news", "is_verified"=TRUE, "q"="news"))
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page