> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Facebook Messenger

> Let end users message your Facebook Page and get answers from your agent, connected with Facebook Login in the admin dashboard or a Page token in the CLI

After this guide, messages sent to your Facebook Page reach your agent and its replies appear in the Messenger thread. You need admin access to the Page. The admin dashboard connects it with Facebook Login and nothing to copy; the CLI takes a Page access token from a Meta app you own.

*Verified against lua-cli 3.33.0.*

**Before you begin**

* Admin access to a Facebook Page.
* For the CLI path: a Meta app with the Messenger product, its Page access token, and the Page ID, from Meta's [Messenger Platform documentation](https://developers.facebook.com/docs/messenger-platform/).
* An agent with a promoted production version; see [Release an agent](/ship/releasing).

<Steps>
  <Step title="Link the Page">
    <Tabs>
      <Tab title="Dashboard">
        In the [admin dashboard](/get-started/for-operators) open **Agents**, select the agent, select **+** in **Channels**, and choose **Facebook**. Accept the terms and select **Connect**. Facebook Login asks for `pages_show_list`, `pages_messaging`, `pages_read_engagement`, `pages_manage_metadata`, and `business_management`; grant them and pick the Page. Lua subscribes the Page to the `messages` and `messaging_postbacks` webhook fields for you.&#x20;
      </Tab>

      <Tab title="CLI">
        Run `lua channels`, choose **Link new channel**, then **Facebook Messenger**, and enter the Page access token (masked) and the Page ID. The CLI validates the token against the Page and prints the Page name, identifier, category, and the webhook URL. It does not subscribe the Page to a webhook; the next step does.

        ```bash theme={null}
        lua channels
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Provider console: point your app's webhook at Lua">
    Skip this step on the admin dashboard path. In your Meta app open **Messenger → Settings → Webhooks**, set the callback URL to `https://wa.heylua.ai/fb/webhook`, enter the verify token, and subscribe the Page to the `messages` and `messaging_postbacks` fields. Meta's [webhooks guide](https://developers.facebook.com/docs/messenger-platform/webhooks) has the current screens.

    The verify token is Lua's, not one you choose, and the CLI doesn't print it.&#x20;
  </Step>

  <Step title="Verify">
    From a personal Facebook account, message the Page with `hello`. The agent replies in the thread, and `lua channels list` shows a `FACEBOOK` entry with the Page name.

    ```bash theme={null}
    lua channels list
    ```
  </Step>
</Steps>

## Channel behavior

| Capability                      | Supported                                                                                                                                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inbound text and attachments    | Yes                                                                                                                                                                                             |
| Inbound events that are dropped | Message echoes, deletions, reactions, read and delivery receipts                                                                                                                                |
| `list-item`                     | Rendered as Messenger templates; a selection comes back to the agent as a message naming the item                                                                                               |
| `actions`                       | Quick replies                                                                                                                                                                                   |
| `images`, `payment`, `reaction` | Rendered; a `reaction` emoji outside Messenger's reaction set is skipped                                                                                                                        |
| `links`, `documents`            | Not rendered; see the [rendering matrix](/channels/formatting/overview)                                                                                                                         |
| Proactive sends                 | `Channels.send({ channel: 'messenger', to: { userId } })` to an end user who has already written to the agent; `user.send()` reaches an end user whose most recent conversation is on Messenger |

Note the two names: inbound, `Lua.request.channel` is `facebook`; outbound, `Channels.send` takes `messenger`.

## Limits

* Proactive sends are warm-only. There is no way to message someone who has never written to the Page.
* A Page routes to one agent at a time. Linking a Page that is already connected fails; disconnect it in the admin dashboard first.
* Meta's [Messenger Platform policies](https://developers.facebook.com/docs/messenger-platform/policy/policy-overview) apply to every reply the agent sends.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to retrieve Facebook page info">
    The token isn't valid for that Page ID. Generate the Page access token for the same Page in the Meta app and check the ID in the Page's settings.
  </Accordion>

  <Accordion title="Messages never arrive on the CLI path">
    The Page isn't subscribed to Lua's webhook. Check the callback URL, the verify token, and that both `messages` and `messaging_postbacks` are subscribed for that Page.
  </Accordion>

  <Accordion title="The dashboard can't confirm the webhook subscription">
    A Page token without `pages_manage_metadata` still sends and receives messages, but Lua can't inspect its subscription. Reconnect through the admin dashboard to get a token with the full permission set.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Connect Instagram" href="/channels/instagram">The same Meta account, connected with Instagram Login.</Card>
  <Card title="Send proactive messages" href="/build/send-proactive-messages">What warm-only means for follow-ups.</Card>
  <Card title="Channels reference" href="/reference/sdk/channels">`Channels.send` and delivery status.</Card>
  <Card title="About channels" href="/concepts/channels">The inbound and outbound channel vocabularies.</Card>
</Columns>