# Empty Python project (`decent_nestling/fb-group-crawler-python`) Actor

Empty project in Python.

- **URL**: https://apify.com/decent\_nestling/fb-group-crawler-python.md
- **Developed by:** [Sa Ph](https://apify.com/decent_nestling) (community)
- **Categories:** Automation
- **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Facebook Group Crawler do?

**Facebook Group Crawler** crawls posts from selected [Facebook](https://www.facebook.com/) groups, detects engagement counters, extracts member count when visible, and returns a structured dataset with the hottest post and all collected posts. You can run it manually, schedule it on Apify, call it through the Apify API, export results, and optionally send a Telegram report or write full crawl history to Google Sheets.

The Actor is designed for monitoring public or accessible Facebook groups where your provided Facebook session has permission to view content. It uses Playwright with a saved browser/session state, so the quality of results depends on the active Facebook account, group access, and Facebook page layout at run time.

### Why use Facebook Group Crawler?

Use this Actor to monitor community activity, identify posts with high engagement, track active discussion groups, and send daily summaries to an operations or marketing team. Results can stay in Apify Dataset for API access and export, or be mirrored into Google Sheets for reporting workflows.

Key benefits:

- Crawl one group, multiple groups, or groups listed in Google Sheets.
- Detect a top/hot post by engagement score.
- Store full post history to Google Sheets with one row per post.
- Send a compact Telegram summary after the run.
- Schedule recurring runs with Apify Saved tasks and schedules.

### How to use Facebook Group Crawler

1. Open the Actor on Apify Console.
2. Enter `groupUrl` and `groupName`, or provide a `groups` array.
3. Optionally enable `useGoogleSheet` and provide Google Sheet settings.
4. Optionally enable `writeFullHistoryToGoogleSheet` to save every post row.
5. Optionally enable `sendTelegram` and provide Telegram credentials through input or environment variables.
6. Run the Actor and check the Dataset output.
7. For daily runs, create an Apify Saved task and schedule it.

### Input

You can configure the Actor from the Input tab. Main fields:

- `groupUrl`: one Facebook group URL.
- `groupName`: display name for the single group.
- `groups`: JSON array like `[{"name":"Group A","url":"https://www.facebook.com/groups/..."}]`.
- `maxRounds`: number of scroll rounds.
- `useGoogleSheet`: read group list from a Google Sheet.
- `writeFullHistoryToGoogleSheet`: write every collected post to a Google Sheet.
- `googleSpreadsheetId`, `googleInputSheetName`, `googleOutputSheetName`: Google Sheet settings.
- `googleCredentialsJson` or `GOOGLE_CREDENTIALS_JSON`: service account credentials.
- `sendTelegram`, `telegramBotToken`, `telegramChatId`: Telegram report settings.

Google Sheet input rows should include `group_url` and `name` columns. The Actor also accepts common alternatives such as `URL`, `url`, `groupName`, and `Tên Group`.

### Output

The Actor pushes one dataset item per group. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Example:

```json
{
  "group_name": "Example Group",
  "group_url": "https://www.facebook.com/groups/example",
  "member_count": "12K members",
  "posts_fetched": 18,
  "posts_with_time_count": 6,
  "hot_post": {
    "author": "Nguyen Van A",
    "content": "Sample post content",
    "reactions": 10,
    "comments": 25,
    "shares": 2,
    "score": 37,
    "url": "https://www.facebook.com/groups/example/posts/123/"
  },
  "posts": []
}
```

### Data table

| Field | Description |
| --- | --- |
| `group_name` | Input group name |
| `group_title` | Title detected from Facebook |
| `group_url` | Group URL |
| `member_count` | Visible member count |
| `posts_fetched` | Number of posts collected |
| `posts_with_time_count` | Posts with detected timestamp |
| `hot_post` | Highest scoring post |
| `posts` | Full collected post list |
| `status` | Crawl status |

### Pricing / Cost estimation

How much does it cost to scrape Facebook group data? Cost depends mainly on `maxRounds`, number of groups, and whether Facebook loads slowly. A small single-group run usually uses a small amount of compute. Larger Google Sheet runs with many groups should be scheduled carefully and tested with a low `maxRounds` first. Apify free tier limits may apply based on your account plan.

### Tips or Advanced options

Keep `maxRounds` modest for scheduled monitoring. Use Apify schedules instead of running an internal scheduler in the Actor. Store Telegram and Google credentials as Apify secrets or environment variables rather than plain input. Refresh the Facebook session if runs start showing login forms or zero posts. For Google Sheets output, the Actor writes these columns: `crawl_time`, `group_url`, `group_title`, `member_count`, `crawl_status`, `error_message`, `posts_fetched`, `has_top_post_24h`, `user`, `time_vn`, `url`, `likesCount`, `commentsCount`, `sharesCount`, `engagement`, and `text`.

### FAQ, disclaimers, and support

Is this legal? Scraping may be subject to Facebook terms, privacy rules, and local laws. Only collect data you are allowed to access and process.

Why is output empty? The Facebook session may be expired, the group may be private, Facebook may show a checkpoint, or the page layout may have changed.

Can it send Telegram alerts? Yes. Enable `sendTelegram` and provide `TELEGRAM_TOKEN` and `TELEGRAM_CHAT_ID`, or the equivalent input fields.

Can it read groups from Google Sheets? Yes. Enable `useGoogleSheet`, provide a spreadsheet ID, input sheet name, and service account credentials with access to the sheet.

For bugs or feature requests, use the Issues tab on the Actor page. Custom extraction fields, dashboards, and workflow integrations can be added as a custom solution.

# Actor input Schema

## `groupUrl` (type: `string`):

Dan link Facebook group can crawl. Bo trong neu dung groups hoac Google Sheet.

## `groupName` (type: `string`):

Ten group khi chi crawl mot link groupUrl.

## `groups` (type: `array`):

Danh sach group dang \[{"name":"Group name","url":"https://www.facebook.com/groups/..."}].

## `maxRounds` (type: `integer`):

So vong scroll de tai them bai viet.

## `useGoogleSheet` (type: `boolean`):

Bat de lay danh sach group tu Google Sheet. Sheet can co cot group\_url va name.

## `writeFullHistoryToGoogleSheet` (type: `boolean`):

Bat de luu moi post crawl duoc vao Google Sheet output.

## `googleSpreadsheetId` (type: `string`):

Spreadsheet ID. Co the thay bang env SPREADSHEET\_ID.

## `googleInputSheetName` (type: `string`):

Tab chua danh sach group. Co the thay bang env GOOGLE\_SHEET\_NAME.

## `googleOutputSheetName` (type: `string`):

Tab de ghi lich su crawl. Co the thay bang env GOOGLE\_SHEET\_NAME\_APPEND.

## `googleCredentialsJson` (type: `string`):

Noi dung JSON service account. Nen cau hinh bang Apify secret/env GOOGLE\_CREDENTIALS\_JSON.

## `googleCredentialsPath` (type: `string`):

Duong dan file credentials neu chay local. Co the thay bang env GOOGLE\_CREDENTIALS\_PATH.

## `sendTelegram` (type: `boolean`):

Bat de gui bao cao Telegram sau khi crawl xong.

## `telegramBotToken` (type: `string`):

Bot token. Nen cau hinh bang Apify secret/env TELEGRAM\_TOKEN.

## `telegramChatId` (type: `string`):

Chat ID nhan bao cao. Co the thay bang env TELEGRAM\_CHAT\_ID.

## Actor input object example

```json
{
  "groupUrl": "https://www.facebook.com/groups/n8n.automation",
  "groupName": "Cong dong n8n AI Automation Viet Nam",
  "groups": [],
  "maxRounds": 15,
  "useGoogleSheet": false,
  "writeFullHistoryToGoogleSheet": false,
  "sendTelegram": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "groupUrl": "https://www.facebook.com/groups/n8n.automation",
    "groupName": "Cong dong n8n AI Automation Viet Nam"
};

// Run the Actor and wait for it to finish
const run = await client.actor("decent_nestling/fb-group-crawler-python").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "groupUrl": "https://www.facebook.com/groups/n8n.automation",
    "groupName": "Cong dong n8n AI Automation Viet Nam",
}

# Run the Actor and wait for it to finish
run = client.actor("decent_nestling/fb-group-crawler-python").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "groupUrl": "https://www.facebook.com/groups/n8n.automation",
  "groupName": "Cong dong n8n AI Automation Viet Nam"
}' |
apify call decent_nestling/fb-group-crawler-python --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,decent_nestling/fb-group-crawler-python"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3xWicdY3FAhlBDiNR/builds/Pb31savFSgSpg2Nxq/openapi.json