Knowledge & tools

Facebook tool

The Facebook tool lets an agent manage a Facebook Page through the Graph API - publish posts, read comments and insights, reply to and moderate comments, and edit or delete posts. Connect your Page with Facebook, or paste a Page access token, then assign the tool to a bot.

This tool acts as your Page. Connect only the Pages it should manage, and read Safety in autonomous runs before scheduling a bot that posts on its own.

What it can do

The agent chooses an action per call. Available actions:

  • Publish - text, link, photo, multi-photo, video, and reel posts (optionally scheduled).
  • Read - posts, a single post, comments, ratings, and insights/analytics.
  • Engage - comment on a post (comment_post adds a new top-level comment - the usual way to put a link or a photo credit under the Page's own post), reply to existing comments, and hide/unhide comments and posts.
  • Manage - edit, pin/unpin, and delete posts.
  • Discover - list_pages returns the Pages the token manages (id, name, tasks).

Connect your Page

Open Tools → Add tool → Facebook Page. There are three ways in.

Connect with Facebook

The quickest. Click Continue with Facebook, sign in, and pick your Page in the window that opens. There's no token to copy. Hania names the configuration after the Page, for example "Facebook Page (Acme Bakery)", and locks it to that one Page.

Pick a single Page. If you grant more than one, Hania asks you to run Connect again and grant only the Page you want.

Use a connected Messenger channel

If the Page is already connected as a Messenger channel under Channels, choose Use a connected Messenger channel and pick it. No new sign-in is needed. It works the other way round too: when you connect a Messenger channel, Use an existing Facebook Page tool connection sets the channel up from a Page you connected here.

Enter the details manually

Choose Enter the details manually instead and fill in the fields below. You'll need an access token, and How to get an access token walks you through it. This is also the way to set up multi-page mode.

When the assistant sets up an agent that needs your Page, it can ask for it in the chat. The card there has the same Continue with Facebook button.

Reconnecting

A Page connected with Facebook or from a channel shows as Connected when you edit it, and its credentials aren't editable there. To replace them, use Reconnect and run either option again. The name and description stay as they are, and you can change the description and safety settings at any time.

A Page you set up with a token can be switched over too. Edit it, choose Connect with Facebook or a channel instead, and connect. Hania replaces the stored token with the new connection. Do this if a Page set up with a token from your own Meta app won't connect as a Messenger channel.

Configuration

If you enter the details manually, the tool has three fields:

  • Access token (required) - a Facebook Page access token, or a User access token that manages the Page. Stored encrypted and never shown again after saving. See How to get a token.
  • Page ID (optional) - the numeric Page ID. Set it to lock the configuration to one Page; leave it blank for multi-page mode.
  • API version (optional) - the Graph API version. Defaults to v25.0; most users never change it.

How to get an access token

You only need this if you enter the details manually. Connect with Facebook doesn't ask for a token.

Meta changes this UI periodically, so treat the concepts as authoritative and the exact button labels as approximate. The endpoints and permissions below are current.

Prerequisites

  • You must be an admin (full control) of the Facebook Page.
  • You need a Meta app: developers.facebook.com/apps → Create app → type Business. Managing your own Page works at Standard Access - no App Review needed.
  • The app must have Page permissions enabled - add the Facebook Login product, or (newer dashboard) a use case that includes Page management. Without this the permissions below can't be requested.

Required permissions

Request all six:

  • pages_show_list - list the Pages you manage
  • pages_read_engagement - read Page content & follower data
  • pages_read_user_content - read posts, comments, and ratings
  • pages_manage_posts - create, edit, delete Page posts
  • pages_manage_engagement - create/edit/delete comments; manage likes
  • read_insights - read Page & post analytics

Quick path - short-lived token (testing, ~1–2 hours)

  1. Open the Graph API Explorer.
  2. Top-right Meta App dropdown → select your app.
  3. User or Page → Get User Access Token → tick the six permissions → Generate Access Token → log in / authorize, keeping your Page selected in the opt-in step.
  4. Reopen User or Page → under Page Access Tokens, click your Page. The token field switches to the Page token - that's the value to paste. (Sanity check: with it selected, GET /me returns your Page's name, not your profile.)

Durable path - long-lived Page token (recommended for production)

A Page token derived from a long-lived user token is effectively non-expiring.

  1. Get a short-lived User token (steps 1–3 above; stop at the user token).
  2. Exchange it for a long-lived user token (~60 days), using your App ID and App Secret:
    GET https://graph.facebook.com/v25.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_USER_TOKEN}
  3. Read your Page tokens:
    GET https://graph.facebook.com/v25.0/me/accounts?fields=id,name,access_token
    Copy the access_token for your Page - that's the durable Page token.

Page token vs User token

  • Page token → scoped to one Page. Best when this config manages a single Page (pair with Page ID set, or leave it blank and the tool auto-detects the Page).
  • User token → can manage many Pages you administer. Best for multi-page mode - the tool resolves the correct Page token per Page via /me/accounts automatically. On Meta's "New Pages Experience" a user token alone can't post; the tool converts it to the needed Page token.

Finding the Page ID

Simplest: save the tool without a Page ID, then have the bot call the list_pages action - it returns each manageable Page's id and name. You can also read it from GET /me/accounts, or find it on the Page under About / Page transparency.

Single-page vs multi-page mode

  • Single-page - set Page ID. The bot is locked to that Page and can't post anywhere else. Safest for a Page-specific bot.
  • Multi-page - leave Page ID blank and use a User token. One configuration then drives every Page the token manages; the agent supplies the Page per action (and can list_pages to discover them). Note that in this mode the AI chooses which Page to act on, limited to Pages the token already controls.

You can also create multiple separate configurations (one per Page) - fully supported; each just needs a distinct name.

Token expiry & refresh

Tokens can expire or be invalidated - a password change, a security event, or the ~1–2 hour life of an Explorer token. When that happens, every action fails with a clear error like "Session has expired" or "Error validating access token." For production, use the durable path above. There is no automatic refresh - if a token dies, edit the config and paste a new one (leaving the token blank on edit keeps the stored one, so you must retype to replace it).

Behavior to expect

  • Hide/unhide applies to visitors' posts and comments, not the Page's own - Facebook won't let a Page hide its own content. Use edit or delete for the Page's own posts.
  • Scheduling window - a scheduled post must be roughly 10 minutes to 30 days in the future; outside that, Facebook rejects it.
  • Insights metrics - metric names change over time and many classic ones are retired (e.g. page_impressions, page_fans, post_impressions are invalid). Current working examples include page_post_engagements, page_views_total, page_daily_follows, post_clicks. The tool passes names through as-is - check Meta's current Page/Post Insights metric reference.
  • Pin/unpin may be rejected depending on the token's rights ("insufficient permissions") - treat it as best-effort.
  • Media - image and video sources must be publicly reachable https URLs; Facebook fetches them server-side.

Safety in autonomous runs

A new Facebook Page configuration starts with read-only, destructive and sends-data-externally all off. Read-only is off because the tool posts, edits and deletes. Destructive is off because turning it on would stop every post in unattended runs unless the agent is allowed destructive actions. To have an agent wait for your sign-off before it uses the tool, set the tool's Approval to Always on that agent.

Like any tool, the Facebook tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Classify the configuration to match what its token can actually do, and prefer the tighter control: scope the token (a single Page, only the permissions you need) so a limit is enforced by Facebook rather than only by an app-layer flag. Interactive chat is never gated by these flags.

Security

The access token is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a token is set. Editing a configuration without retyping the token preserves the stored one.