URL: /code/integrations/facebook · Id: `page:/code/integrations/facebook`

# Facebook

> Your agents post to your Facebook page on schedule, answer comments and messages as the page, and qualify each lead-form entry within seconds.

Your agents post to your Facebook [page](https://startupbuilder.dev/business/nouns/page) on schedule, answer comments and messages as the page, and qualify each lead-form entry within seconds.

```text title="Run it · Ask"
Schedule the free rent-reminder template for my Page on Thursday at 9:00 Central, and show me the post.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Post.schedule({ handle: 'facebook:leaseline', body: 'Free template: the 3-text rent reminder schedule our pilot buildings use.', link: 'https://leaseline.app/templates/rent-reminders', at: '2026-10-29T14:00:00Z' })
```

```json title="Run it · Response"
{
  "$type": "Post",
  "mode": "try",
  "stored": false,
  "venue": "facebook",
  "status": "scheduled",
  "at": "2026-10-29T14:00:00Z",
  "linkPreview": {
    "title": "Rent reminder template",
    "host": "leaseline.app"
  }
}
```

- **Connect:** Sign in once, 5 grants
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Read your page’s reach for the last 28 days, free on your account
- **Sites:** [Facebook](/venues#facebook)

## Connect once
1. Call `Integration.connect` with `system: 'social'` and `venue: 'facebook'`, then open the `connectUrl` it returns and sign in as yourself with Meta.
2. Pick the page your agents speak for; you need a role on it that can post.
3. Call `Handle.connect` to bind the page as your account.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Your pages | The list of pages you can act for, so you pick one | `pages_show_list` |
| Post | Text, links, photos, videos and reels posted as the page, now or later | `pages_manage_posts` |
| Read and answer | Reach and comments on each post, and replies to them | `pages_read_engagement pages_manage_engagement` |
| Messenger | Answers to the people who message the page | `pages_messaging` |
| Lead forms | Each lead-form entry, the moment it is submitted | `leads_retrieval` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops every call through Meta at once and keeps the token; `Integration.resume` picks up from the same cursor. |
| Reconnect | `Integration.reconnect` returns a fresh `connectUrl` that lasts one hour, and keeps the Integration's id and cursor, so nothing imports twice. |
| Disconnect | `Integration.revoke` revokes the token with Meta; every record it brought in stays in your records. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Post the rent-reminder template link to my page on Thursday at 9:00. | [`Post.schedule`](/code/apps/social/schedule) | Your account | Free |
| Post this update to my page now. | [`Post.publish`](/code/apps/social/publish) | Your account | Free |
| Answer each comment and Messenger message as the page. | [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | Your account | Free |
| Qualify each lead-form entry as it arrives and open a deal for the ones that fit. | [`Lead.qualify`](/code/apps/crm/qualify) | Your account | Free |
| Show me my page’s reach and each post’s reach this month. | [`Metric.query`](/code/apps/analytics-and-experiments/query) | Your account | Free |

Calls on your own account are free.

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Post](https://startupbuilder.dev/business/nouns/post) | `post` | Your agent publishes or schedules | Your records |
| [Message](https://startupbuilder.dev/business/nouns/message) | `comment or message` | Someone comments or writes to the page | The account |
| [Lead](https://startupbuilder.dev/business/nouns/lead) | `leadgen entry` | Someone submits a lead form | The account |
| [Review](https://startupbuilder.dev/business/nouns/review) | `rating` | Someone recommends the page or not | The account |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Post.published`, `Post.scheduled`, `Message.created`, `Lead.created`, `Lead.qualified` |
| Hears `feed` | Becomes `Message.created` |
| Hears `messages` | Becomes `Message.created` |
| Hears `leadgen` | Becomes `Lead.created` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| Messenger replies | Go out within 24 hours of the person’s last message; after that the answer waits until they write again | [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) |
| Lead-form entries | Arrive by webhook within seconds; the agent qualifies each and drafts the first reply within 5 minutes | [`Lead.qualify`](/code/apps/crm/qualify) |
| Your role on the page | Posting needs a role that can post; a role removed in Meta’s settings ends the connection with `needs-reauth` | Every call |

## Field map
| Our field | Facebook’s field | Notes | Calls |
| --- | --- | --- | --- |
| `Post.body` | `message` | None. | [`Post.publish`](/code/apps/social/publish), [`Post.schedule`](/code/apps/social/schedule) |
| `Post.link` | `link` | None. | [`Post.publish`](/code/apps/social/publish), [`Post.schedule`](/code/apps/social/schedule) |
| `Post.publishAt` | `scheduled_publish_time` | Sent with published false | [`Post.schedule`](/code/apps/social/schedule) |
| `Lead.interest` | `leadgen.field_data` | Each form question and answer, as you wrote the form | [`Lead.qualify`](/code/apps/crm/qualify) |

## What try does here
Returns the post as your page will show it, with the time it goes live; nothing is posted or scheduled.

## How long a connection lasts
A connection lasts until you remove the app or give up your role on the page: a page token made from Meta’s long-lived sign-in has no expiration date.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Formats
| Site | Format | Size | Limits |
| --- | --- | --- | --- |
| [Facebook](/venues#facebook) | Feed image ad | 1440 × 1800, 4:5 | Primary text 50 to 150 characters; headline 27; up to 30 megabytes |

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Paid social](/plays/paid-social), [Retargeting](/plays/retargeting), [Video ladder](/plays/video-ladder), [Instant response](/plays/instant-response), [Organic social](/plays/organic-social) |
| Strategies | [Paid](/strategy/paid) |

## Used by
No Workflow, agent task or Service acts through it yet: your agents call it directly.

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Post.schedule`](/code/apps/social/schedule) | `POST /posts/schedule` | Free |
| [`Post.publish`](/code/apps/social/publish) | `POST /posts/publish` | Free |
| [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | `POST /conversations/answer` | Free |
| [`Lead.qualify`](/code/apps/crm/qualify) | `POST /leads/qualify` | Free |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | `POST /metrics/query` | Free |