Set up Messenger

Back to 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:

Meta setup: prepare the app and Page, and collect four values.
Artemis channel configuration: create the connection, then copy its Webhook URL.
Webhook configuration in Meta: verify the callback and subscribe the Page.
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.

Create or open a business app

In My Apps, create an app suitable for your business integration, or open the one that will own this connection.
Use separate apps or Pages for development and production.

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.

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.

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.

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.Don’t use the Meta App ID, Business ID, Page username, or a customer’s PSID.

Copy the App Secret

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

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.

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.

Open Artemis and select the project.
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.

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.

Select Create.
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.

Confirm the Artemis connection is Active. Meta sends the verification request as soon as you save the callback.
Open Messenger API Settings or Webhooks, and add a callback for the Page object. Don’t configure it under an unrelated Meta product.
Paste the Artemis Webhook URL and the same Verify Token. Don’t append a Page ID, connection ID, query string, or trailing segment.
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.
Subscribe the Page webhook to messages for text, attachments, and quick replies, and messaging_postbacks for button actions.
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.

While the app is in development mode, use a Facebook account with an app or Page role.
Open the Page in Messenger and send a unique message. Confirm Meta reports a successful delivery and Artemis creates one session.
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.
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.
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.

Credentials
Configuration
Deployment

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.

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.

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	App setup, Page tokens, and the first webhook.
Send API reference	Outbound message types, message tags, and messaging window rules.
My Apps	Returning to an app or checking which app owns a Page subscription.
Meta Business Suite	Page settings, roles, and business verification.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Messenger events

Meta setup

Artemis channel configuration

Webhook configuration in Meta

Validation checklist

Verify the connection

Messenger limits

Security and secret boundaries

Manage the channel connection

Troubleshoot connection issues

Meta reference

​Prerequisites

​How Artemis routes Messenger events

​Meta setup

​Artemis channel configuration

​Webhook configuration in Meta

​Validation checklist

​Verify the connection

​Messenger limits

​Security and secret boundaries

​Manage the channel connection

​Troubleshoot connection issues

​Meta reference

Prerequisites

How Artemis routes Messenger events

Meta setup

Artemis channel configuration

Webhook configuration in Meta

Validation checklist

Verify the connection

Messenger limits

Security and secret boundaries

Manage the channel connection

Troubleshoot connection issues

Meta reference