# Connect Messenger

> How to link a Facebook Page to chat through Messenger.

## Requirements

- A **Facebook Page**.
- Being an admin of the Page (or having full control of it through the business portfolio), with a role that allows messaging (`MESSAGING` or `MANAGE`).

## Permissions

| Permission | What for |
|---|---|
| `pages_show_list` | List the Pages you manage, to choose which one to connect |
| `pages_manage_metadata` | Subscribe the app to the Page webhooks |
| `pages_messaging` | Receive and send Messenger messages |
| `pages_read_engagement` | Read basic data of the Page and its conversations |
| `business_management` | Access Pages that belong to a business portfolio |

Without `pages_messaging` or `pages_manage_metadata` the connection is not created ([`signup_scope_mismatch`](/en/errors#signup_scope_mismatch)).

## Step by step

1. Open **Connections → Connect Messenger**. The panel navigates to [Facebook Login for Business](https://developers.facebook.com/documentation/facebook-login/facebook-login-for-business) (no popup, works on mobile).
2. Sign in to Facebook, choose the Pages Messajo can access and accept the permissions.
3. Back in the panel, if more than one Page is available, tick in **Choose the Pages** which ones to connect and tap **Connect Pages**. Each chosen Page becomes a connection. A Page already connected in another organization, or without a messaging role, shows as disabled, with the reason.
4. Done: each Page shows as **Active**.

With no Page that can be connected, the attempt ends with [`messenger_no_pages`](/en/errors#messenger_no_pages). A failure on one Page does not undo the others.

To connect a customer's Page, send an [invite link](/en/connect/whatsapp/#invite-the-customer-by-link) with the Messenger channel: the person authorizes and chooses the Pages from the invite's public page.

## Page token

The Page token **does not expire**: there is no refresh. When connecting, Messajo subscribes the app to the Page (`subscribed_apps`) to receive the webhooks; every 15 min it checks the subscription and, if the app is gone from the list, subscribes again (`connection.updated` with `reason: "resubscribed"`). If someone removes the permissions, the connection moves to `needs_reconnect` (`token_invalid`) and the owner gets the reconnection link.

## Messages

Messenger uses the same engine and the same [type matrix](/en/connect/instagram/#message-types) as Instagram, with these differences:

- `to` is the contact's PSID (or Messajo's `ctc_…`);
- text up to 2,000 characters; attachments up to 25 MB;
- one image per message (no `images`), no `like` and no `share`;
- Meta's read receipt (`watermark`) becomes `message.status` with `read` for every message up to that moment.

## Windows

| Window | When it applies |
|---|---|
| 24 hours | Any reply, counted from the contact's last message |
| 7 days | After the contact replies to an ad |
| 7 days | With `tag: "human_agent"` |

`tag: "human_agent"` is only for replies written by a person, never for automation, and requires the **Human Agent** feature approved in App Review (without it: `403` [`human_agent_not_approved`](/en/errors#human_agent_not_approved)). The other Messenger tags were discontinued by Meta and are not accepted. Outside the window: `422` [`outside_service_window`](/en/errors#outside_service_window).

See [Meta's Messenger policy](https://developers.facebook.com/documentation/business-messaging/messenger-platform/policy).

## Messaging profile

In **Connections → (Page) → Messaging profile**, or with `GET`/`PUT /v1/connections/{id}/messaging-profile`:

- **Ice breakers**: up to 4 per language;
- **Persistent menu**: up to 20 items, with the option to disable the composer;
- **Greeting**: up to 160 characters, accepts `{{user_first_name}}`;
- **Get started**: the "Get started" button and the `payload` it sends. Messajo saves "Get started" before the menu (Meta requires it) and does not let you delete it while there is a menu.

![Messaging profile screen of a Page, with a persistent menu and a greeting](../../../../assets/screenshots/messenger-profile-en-US.png)

## Mirror layer

`/v1/messenger/{page_id}/...` forwards to the Graph API with the Page token, with Meta's body and response untouched; standalone nodes at `/v1/messenger/{page_id}/nodes/{node_id}`. `POST …/messages` records the message in the logs; `subscribed_apps` and the token routes are blocked (`403` [`mirror_path_blocked`](/en/errors#mirror_path_blocked)), and `pass_thread_control`/`take_thread_control` require a key with `admin` permission.
