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

# Set up Messenger

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect a Facebook Page to your agent so people reach it through Messenger. You prepare one Meta app and one Page, enter four values in Artemis, then register a signed webhook that Meta verifies.

The setup requires:

1. [Meta setup](#meta-setup): prepare the app and Page, and collect four values.
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
3. [Webhook configuration in Meta](#webhook-configuration-in-meta): verify the callback and subscribe the Page.
4. [Verify the connection](#verify-the-connection) with a real two-way conversation.

After setup, Meta posts signed Page events to Artemis. Artemis matches the Page ID in each event to the connection, and the agent replies in the same Messenger conversation.

**Important considerations**

* **The Facebook Page ID selects the connection**: Artemis reads `entry[0].id` from each webhook and matches it to the saved Page ID. The Page ID, Page Access Token, App Secret, Verify Token, and webhook subscription must all belong to the same Meta app and Page.
* **One Page routes to one active connection**: To reuse a Page, deactivate the old connection first.
* **Verification and subscription are separate steps**: Meta verifies the callback whether or not you subscribe to anything, so a verified webhook with no subscription delivers nothing.
* **Development success doesn't prove public access**: A role-based tester can reach the Page while ordinary visitors can't. Test again with a non-role account after Meta approves the app and you switch it to Live.

## Prerequisites

Confirm these before you start.

* A Meta developer account and the Facebook Page customers will message.
* Page access that covers the messaging and moderate tasks. An editor or viewer role can't generate a working Page token.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Messenger events

Meta sends every Page event to one generic URL, so Artemis identifies the connection from the signed payload.

| Piece | Owner | What it does |
| - | - | - |
| **Facebook Page ID** | Meta | Routes inbound events by matching `entry[0].id`. |
| **Page Access Token** | Meta | Authorizes replies through the Messenger Send API, as a Bearer token. It's scoped to one Page. |
| **App Secret** | Meta | Validates `X-Hub-Signature-256` over the unchanged request body. |
| **Verify Token** | You | Answers Meta's one-time verification challenge. |
| **Webhook URL** | Artemis | Receives events at `/api/v1/channels/messenger/webhook`, with no Page ID in the path. |

***

## Meta setup

Do this in Meta before you open Artemis. Select **Open Meta apps** in the setup guide to jump straight there. Meta covers the same ground in its [Messenger Platform quick start](https://developers.facebook.com/docs/messenger-platform/getting-started/quick-start/).

**1. Create or open a business app**

1. In [My Apps](https://developers.facebook.com/apps/), create an app suitable for your business integration, or open the one that will own this connection.
2. Use separate apps or Pages for development and production.

**2. Add the Messenger product**

Add **Messenger** to the app and open **Messenger API Settings**. Labels vary by app type, but the screen must show a Page connection, token generation, and webhook controls.

**3. Connect the Facebook Page**

Add or select the Page customers will message, and authorize the app on it. Confirm your account has enough Page and app permissions before you generate credentials.

**4. Generate the Page Access Token**

Select the Page in the token generation area and copy the token. Meta doesn't store it on this screen, and each new selection generates another token while earlier tokens keep working.

A user token or a token for another Page authenticates but can't send replies.

**5. Copy the numeric Facebook Page ID**

Copy the Page ID shown for the Page connected under **Messenger API Settings**. You can also find it under the Page's **About** information or in [Meta Business Suite](https://business.facebook.com/).

Don't use the Meta App ID, Business ID, Page username, or a customer's PSID.

**6. Copy the App Secret**

1. Go to **App settings** > **Basic**.
2. Select **Show** beside **App secret**, re-enter your password, and copy the value.

**7. Choose a Verify Token**

Create a high-entropy secret string. Artemis saves a connection without it, but Meta verification fails until the same non-empty value exists in Artemis and Meta.

**8. Plan development and production access**

In development mode, only people with an app or Page role can test. Before public traffic, complete app review, business verification, permissions, and the Live-mode requirements Meta shows for your app.

***

## Artemis channel configuration

Create the connection before you configure the callback in Meta. Artemis resolves Meta's challenge from the stored Verify Token.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Messenger** > **+ New**. The **New Messenger Connection** dialog opens, with the setup guide on the left and the fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see. Name it for the Page and environment. Routing ignores it. |
   | **Facebook Page ID** | **Messenger API Settings** | The routing key, matched to `entry[0].id`. |
   | **Page Access Token** | The token generation area | Authorizes replies through the Send API. Generate it for this exact Page. |
   | **App Secret** | **App settings** > **Basic** | Validates `X-Hub-Signature-256` over the unchanged body. |
   | **Verify Token** | You create it | Answers Meta's verification challenge. |
   | **Environment** | Your published environments | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Meta's identity assertion when it links a person to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | Keep it **Active**. Meta's challenge resolves only for an active connection. |

4. Select **Create**.

5. Copy the **Webhook URL** from the connection's summary panel.

***

## Webhook configuration in Meta

Registration has two halves. Complete both in the same Meta app.

1. Confirm the Artemis connection is **Active**. Meta sends the verification request as soon as you save the callback.
2. Open **Messenger API Settings** or **Webhooks**, and add a callback for the **Page** object. Don't configure it under an unrelated Meta product.
3. Paste the Artemis **Webhook URL** and the same **Verify Token**. Don't append a Page ID, connection ID, query string, or trailing segment.
4. Save. Meta sends `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`, and Artemis returns the challenge only when the token matches an active Messenger connection.
5. Subscribe the Page webhook to `messages` for text, attachments, and quick replies, and `messaging_postbacks` for button actions.
6. Confirm this app and webhook list the intended Page as subscribed, and save the app changes. Complete any permissions review or Page task access Meta requires for your app mode.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Complete Meta setup | Business app, Messenger product, connected Page, and a Page Access Token. |
| Create the Artemis connection | Saved as **Active** with all four values from the same app and Page. |
| Register the callback | Meta completes the verification challenge. |
| Subscribe the events | The Page subscribes to `messages` and `messaging_postbacks`. |
| Send a live message | One real conversation produces exactly one agent reply. |
| Retest after Live | An account with no app or Page role reaches the agent. |

***

## Verify the connection

Artemis doesn't synthesize Meta events, so a real Messenger conversation is the only end-to-end proof.

1. While the app is in development mode, use a Facebook account with an app or Page role.
2. Open the Page in Messenger and send a unique message. Confirm Meta reports a successful delivery and Artemis creates one session.
3. Confirm one reply appears in the same conversation. A send failure usually means a token for the wrong Page, a missing permission, expired or revoked access, or an app-mode restriction.
4. Trigger a quick reply and a button postback. Artemis normalizes both into action events, so the authored action ID and value must still exist in the agent.
5. Test each message type the Page uses. After review and Live mode, repeat the test with a non-role account.

| Input | What to confirm |
| - | - |
| `text` | The agent receives and answers it. |
| `image`, `video`, `audio`, `file` | Artemis downloads the attachment before the agent processes it. |
| `quick replies`, `postbacks` | The action returns to the same session. |
| Location, sticker, fallback | These arrive as events, not files, so the agent gets no download. |

***

## Messenger limits

Artemis applies these limits before it calls the Send API.

| Area | Limit |
| - | - |
| Buttons | Up to 3 per button template, with titles up to 20 characters. |
| Quick replies | Up to 13 choices, with titles up to 20 characters. |
| Carousels | Up to 10 generic-template cards, with up to 3 buttons per card. |
| Policy | Meta messaging windows, message tags, and platform policies still apply. A valid Page Access Token doesn't bypass recipient or timing rules. |
| Media | Remote media must stay reachable from Artemis, and within download size, content-type, and network-safety policies. |

***

## Security and secret boundaries

Meta signs what it sends. Your Verify Token only protects the one-time challenge.

* **Signatures**: Every Messenger POST must include `X-Hub-Signature-256`. Artemis computes HMAC-SHA256 with the saved App Secret and rejects a missing or mismatched signature.
* **Raw bytes**: Proxies and middleware must preserve the exact request bytes. Reformatting JSON changes the digest.
* **Verify Token**: A user-generated shared secret, separate from the App Secret and the Page Access Token.
* **Page Access Token**: Authorizes outbound Send API calls. Store it only in Artemis, and rotate it without changing the Page ID.
* **Replay protection**: Artemis rejects Messenger events older than five minutes.
* **Environments**: Use separate Meta apps or Pages, credentials, callbacks, and connections for development and production.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Messenger** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its environment badge, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Messenger** and **Channel Connection**. |
| **Identifier** | The Facebook Page ID this connection routes on. Check it first when messages arrive and no session appears. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The callback URL for Meta, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile in place of the fields below. |
> | **Page Access Token** | Replace it when you generate a new token in Meta. |
> | **App Secret** | Replace it if the Messenger product moves to another Meta app. |
> | **Verify Token** | Changing it breaks the Meta webhook until you enter the same value in Meta. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Messenger Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Meta's identity assertion. |
> | **Facebook Page ID** | Read-only, with a copy control. To serve another Page, create a new connection. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select **Show more** for the full list, and select **Show preview** to check it. |
> | **Webhook URL** | The callback URL, with a copy control. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers Messenger.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Most failures trace to mismatched values or a missing subscription.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Callback verification fails | No active connection, mismatched token, or unreachable endpoint | Create the connection first, enter the same non-empty Verify Token in both systems, use the generic Messenger route, and expose public HTTPS. |
| POST requests return `401` | Wrong App Secret or altered request | Copy the App Secret from the app that sends the webhook, and confirm every proxy preserves the body and `X-Hub-Signature-256`. |
| No connection found | Wrong identifier saved | Compare `entry[0].id` with the saved numeric Page ID, and confirm the connection is **Active**. |
| Verified but no messages arrive | Missing subscription or app-mode restriction | Subscribe `messages` and `messaging_postbacks`, subscribe the Page to the app, and check app mode, tester roles, and permissions. |
| Messages arrive but replies fail | Wrong token or no runnable deployment | Regenerate a Page Access Token for the same Page, verify messaging permission and policy eligibility, and confirm the environment can run. |
| Text works but buttons fail | Content outside Messenger limits | Keep button and quick-reply counts and label lengths within limits, and confirm the authored action exists. |
| Text works but attachments fail | Media outside policy | Confirm the attachment URL is reachable, policy allows its host and content type, its size is within policy, and the agent handles the file. |
| Artemis ignores old retries | Replay protection | Expected behavior for events older than five minutes. Send a new live message instead of replaying a payload. |

***

## Meta reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Messenger Platform quick start](https://developers.facebook.com/docs/messenger-platform/getting-started/quick-start/) | App setup, Page tokens, and the first webhook. |
| [Send API reference](https://developers.facebook.com/docs/messenger-platform/reference/send-api/) | Outbound message types, message tags, and messaging window rules. |
| [My Apps](https://developers.facebook.com/apps/) | Returning to an app or checking which app owns a Page subscription. |
| [Meta Business Suite](https://business.facebook.com/) | Page settings, roles, and business verification. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Instagram](https://koreai.mintlify.site/agent-platform/channels/instagram)
* [Set up WhatsApp](https://koreai.mintlify.site/agent-platform/channels/whatsapp)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.