Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Facebook

Scalekit connector
Open markdown

The Facebook connector lets your AI agent act in each user's Facebook account. Each user signs in to Facebook once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 166 tools.

Tools
166
What they doRead · write · destructive
90 · 49 · 2790 read49 write27 destructive
Users sign in with
OAuth app
Your own Facebook app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Facebook connection

    In AgentKit > Connections, create a Facebook connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Facebook connections use your own OAuth app. Register one with Facebook and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Facebook connection.

    Console steps with screenshots

    Create a Meta app with Facebook Login enabled so Scalekit can authorize access to your users’ Facebook Pages on their behalf. You’ll register the Scalekit redirect URI in the app, then add the app’s ID and secret to your Scalekit connection.

    1. Create or open a Meta app

      • Go to the Meta for Developers dashboard.

      • Select an existing app or click Create App and choose the Business app type.

        Meta app dashboard showing app ID, app mode, and available products

    2. Add the Facebook Login product

      • From the app’s Add Product page, add Facebook Login. Scalekit uses it to run the OAuth authorization flow.

      • Use the app switcher at the top of the dashboard to move between apps or create a new one.

        App switcher dropdown for selecting or creating a Meta app

    3. Copy the redirect URI from Scalekit

      • In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Facebook and click Create.

      • Click Use your own credentials and copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

    4. Add the redirect URI to Facebook Login settings

      • In your Meta app, go to Facebook Login > Settings.

      • Paste the redirect URI you copied into Valid OAuth Redirect URIs and save changes.

        Facebook Login settings showing the Valid OAuth Redirect URIs list

    5. Copy your App ID and App secret

      • Go to App settings > Basic.

      • Copy the App ID and click Show to reveal and copy the App secret.

        App settings Basic page showing App ID and App secret fields

    6. Add credentials in Scalekit

      • Return to the connection you created in Scalekit and enter:
        • Client ID — your Meta app’s App ID
        • Client Secret — your Meta app’s App secret
      • Click Save.
    7. Request permissions and go live

      • In your Meta app, go to App Review > Permissions and Features and request the permissions your tools need, such as pages_show_list, pages_read_engagement, pages_manage_posts, pages_manage_engagement, or pages_messaging.

      • While the app is in Development mode, only people with a role on the app (admins, developers, testers) can authorize it, and permissions work without review for them.

      • To let other users connect, complete App Review for the permissions you requested, then switch the app to Live mode.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'facebook'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Facebook:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'facebook_list_message_template_library',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • facebook_debug_access_tokenInspect an access token (input_token) to see its owning app, token type, user, validity, expiry, granted scopes and the Page or object IDs each granular scope covers.Read-only

    Debug Access Token

    Inspect an access token (input_token) to see its owning app, token type, user, validity, expiry, granted scopes and the Page or object IDs each granular scope covers. Returns a data object with app_id, application, type, user_id, is_valid, issued_at, expires_at, data_access_expires_at, scopes, and granular_scopes pairing each scope with its target_ids. Use it to check whether a token is valid and which scopes and Pages it covers. Works only when the connected user has a role on the app: the calling token must be an app access token or an app developer's token from the same app as input_token.

    Inputs

    input_tokenstringrequired
    The access token (user, Page or session-info token) to inspect.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
  • facebook_get_canvas_previewGet the preview of an Instant Experience (canvas) as an HTML embed element.Read-only

    Get Canvas Preview

    Get the preview of an Instant Experience (canvas) as an HTML embed element. Returns the embed element in a paginated Graph API response. Use it to get embeddable preview HTML for a canvas. Permissions per Meta's Page canvases edge: pages_show_list, pages_manage_posts and pages_read_user_content. Needs a Page access token: call facebook_list_my_pages and pass the Page's access_token as page_access_token.

    Inputs

    canvas_idstringrequired
    The Canvas ID to operate on.
    afterstring
    Pagination cursor to fetch the next page of results.
    fieldsstring
    Comma-separated list of fields to return.
    limitinteger
    Max number of items to return per page.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
  • facebook_get_insightsGet insights metrics for a Page, post, photo or Page story (object_id is the Page, post, photo or story ID).Read-only

    Get Insights

    Get insights metrics for a Page, post, photo or Page story (object_id is the Page, post, photo or story ID). Returns an array of metrics, each with name, period, values (value and end_time) and title; metric is required and the valid metrics depend on the object type. Use facebook_get_video_insights for video metrics. Story insights are unverified against Meta's v26.0 reference (parameters from Meta's SDK spec). Needs a Page access token: call facebook_list_my_pages and pass the Page's access_token as page_access_token.

    Inputs

    metricstringrequired
    Comma-separated list of metric names. Required: Meta returns error 3001 when none is given. The valid metrics depend on the object, for example page_media_view for a Page or post_media_view,post_total_media_view_unique,post_reactions_by_type_total for a post or photo.
    object_idstringrequired
    ID of the Page, post, photo or Page story to read metrics for.
    afterstring
    Pagination cursor to fetch the next page of results.
    breakdownstring
    Comma-separated breakdown dimension(s) for the metric(s), e.g. is_from_ads or is_from_followers for page_media_view; valid values depend on the metric.
    date_presetstring
    Predefined date range used instead of since/until.one of todayyesterdaythis_monthlast_monththis_quartermaximumdata_maximumlast_3dlast_7dlast_14dlast_28dlast_30dlast_90dlast_week_mon_sunlast_week_sun_satlast_quarterlast_yearthis_week_mon_todaythis_week_sun_todaythis_year
    fieldsstring
    Comma-separated list of fields to return, for example id,name. Omit it to get Graph's default fields.
    limitinteger
    Max number of items to return per page.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
    periodstring
    Aggregation period: day, week, days_28, month, lifetime or total_over_range; the valid values depend on the metric.
    show_description_from_api_docboolean
    Return Meta's API-doc description for each metric in the response (default false).
    sincestring
    Lower bound of the time range (Unix timestamp or date string).
    untilstring
    Upper bound of the time range (Unix timestamp or date string); at most a 90-day window together with since.
  • facebook_get_messenger_call_permissionsCheck whether one Messenger user, identified by psid, has granted the Page permission to call them, and which call actions the Page can currently take.Read-only

    Get Messenger Call Permissions

    Check whether one Messenger user, identified by psid, has granted the Page permission to call them, and which call actions the Page can currently take. Returns permission (status no_permission or has_permission, with expiration_time) and actions (send_call_permission_request, start_call), each with can_perform and limits. Use to see whether the Page can ask the user for call permission or start a call. Errors when audio calling is not enabled or business-initiated calling is not allowed. Needs a Page access token: call facebook_list_my_pages and pass the Page's access_token as page_access_token.

    Inputs

    page_idstringrequired
    The Page ID to operate on.
    psidstringrequired
    Page-scoped ID (PSID) of the consumer to check.
    fieldsstring
    Comma-separated list of fields to return.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
  • facebook_get_messenger_call_settingsRead a Page's Messenger calling settings: audio and video availability, call icon, call hours and inbound call routing.Read-only

    Get Messenger Call Settings

    Read a Page's Messenger calling settings: audio and video availability, call icon, call hours and inbound call routing. Returns audio_enabled, video_enabled, icon_enabled, call_hours (timezone_id, weekly_operating_hours) and call_routing (ring_target); list the ones you need in fields. Use to inspect current settings; use facebook_update_messenger_call_settings to change them. Needs the app's calling capability and a calling-eligible Page (messenger_api_calling ENABLED, limited countries). Needs a Page access token: call facebook_list_my_pages and pass the Page's access_token as page_access_token.

    Inputs

    page_idstringrequired
    The Page ID to operate on.
    fieldsstring
    Comma-separated list of fields to return.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
  • facebook_get_messenger_profileRead the Messenger Profile settings of a Page: get started button, persistent menu, ice breakers, commands, allowlisted domains and account linking URL.Read-only

    Get Messenger Profile

    Read the Messenger Profile settings of a Page: get started button, persistent menu, ice breakers, commands, allowlisted domains and account linking URL. Returns a data array holding one object with the requested properties; name them in fields (get_started, persistent_menu, ice_breakers, commands, whitelisted_domains, account_linking_url). Use facebook_update_messenger_profile to set properties. Use facebook_delete_messenger_profile to remove them. Standard Access apps see settings only for people with a role on the app. Needs a Page access token: call facebook_list_my_pages and pass the Page's access_token as page_access_token.

    Inputs

    page_idstringrequired
    The Page ID to operate on.
    fieldsstring
    Comma-separated list of fields to return.
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
    platformstring
    Messaging platform whose profile is read; defaults to MESSENGER.one of MESSENGERINSTAGRAM
  • facebook_get_objectRead any Facebook Graph object by ID (a Page, user or me, post, photo, album, comment, video, live video, persona, poll, app, message and more) and return the fields you ask for.Read-only

    Get Object

    Read any Facebook Graph object by ID (a Page, user or me, post, photo, album, comment, video, live video, persona, poll, app, message and more) and return the fields you ask for. Returns the object's id plus the fields named in fields; without fields Graph returns only a few default fields. Use it for one object whose ID you have; use facebook_list_posts, facebook_list_comments, facebook_list_photos or facebook_list_likes for an object's connections and facebook_list_my_pages to find Page IDs. A Page access token (page_access_token from facebook_list_my_pages) is needed for Page-owned objects; some node types need extra permissions or Meta features.

    Inputs

    object_idstringrequired
    ID of the Graph object to read: a Page, post, photo, video, album, comment, live video, persona, poll, app, message and so on, or me for the connected user.
    account_linking_tokenstring
    Page nodes only: a short-lived (5 min) Messenger account linking token; with fields=recipient it returns the PSID for the user-Page pair.
    fieldsstring
    Comma-separated list of fields to return, for example id,name,created_time. The available fields depend on the object type; Graph returns only a few default fields when omitted.
    icon_sizestring
    Place topic nodes only: size in pixels of the topic icon to return.one of 24364872
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
    target_tokenstring
    Live video and live video input stream nodes only: a target token recently returned by Meta's speed test API.
  • facebook_get_page_oembedGet oEmbed JSON with ready-to-paste Page plugin HTML for a public Facebook Page URL, with options for cover, header, facepile, posts and size.Read-only

    Get Page Oembed

    Get oEmbed JSON with ready-to-paste Page plugin HTML for a public Facebook Page URL, with options for cover, header, facepile, posts and size. Returns html, width, height, type, version, provider_name and provider_url; the fields parameter trims the response. Use it to embed a public Facebook Page; Meta lifted the token requirement on 2026-06-15, and sending a token needs Meta oEmbed Read approval (App Review and business verification). For a post or video URL use facebook_get_post_oembed or facebook_get_video_oembed.

    Inputs

    urlstringrequired
    Public Facebook Page URL to embed.
    adapt_container_widthboolean
    Try to fit inside the container width (default true).
    hide_coverboolean
    Hide the cover photo in the header (default false).
    maxheightinteger
    Maximum height of the returned media.
    maxwidthinteger
    Maximum width of the returned media.
    omitscriptboolean
    If true the embed HTML omits the JavaScript (default false).
    page_access_tokenstring
    Optional Page access token to use instead of the connected user token. Required for most Page-scoped reads/writes (feed, posts, comments, insights, photos) — get it from facebook_list_my_pages (request the access_token field).
    sdklocalestring
    Locale for the embedded plugin, e.g. en_US.
    show_facepileboolean
    Show profile photos of friends who like the Page (default true).
    show_postsboolean
    Show the Page timeline posts (default true).
    small_headerboolean
    Use the small header instead of the cover header (default false).