Messenger
The Messenger channel answers direct messages to a Facebook Page, through the Messenger Platform Send API.
Setup
-
At developers.facebook.com/apps, create an app with the use case Engage with customers on Messenger from Meta. Copy the App Secret from App settings > Basic.
-
You need a Facebook Page. People message the Page to reach the agent.
-
In the app, open Use cases > Messenger > Customize > Messenger API Settings. Under Generate access tokens, add your Page and generate a Page access token.
-
Pick a random verify token. You type it into Meta in step 7.
-
Store the values:
broods env set FACEBOOK_APP_SECRETbroods env set FACEBOOK_PAGE_ACCESS_TOKENbroods env set FACEBOOK_VERIFY_TOKEN -
Define the connection:
broods/index.tsimport { defineAgent, defineMessengerConnection, env } from "broods";export const messenger = defineMessengerConnection({appSecret: env("FACEBOOK_APP_SECRET"),pageAccessToken: env("FACEBOOK_PAGE_ACCESS_TOKEN"),verifyToken: env("FACEBOOK_VERIFY_TOKEN"),allowedChannelIds: ["*"],});export const myAgent = defineAgent({name: "my-agent",connections: [messenger],});Every Messenger conversation is one person, and their id does not exist until they write, so a Page that takes new customers needs
allowedChannelIds: ["*"]. -
Run
broods devorbroods deploy. Under Configure webhooks, click Add Callback URL, enter the printed URL,/v1/webhooks/{accountId}/messenger, and the verify token, then Verify and Save. Meta sends a GET handshake, and Broods answers it with the challenge once the verify token matches. -
Under the Page's webhook subscriptions, enable
messagesandmessaging_postbacks.
Meta keeps one callback URL per app. Pointing it at a stage URL moves all of that app's traffic to that stage.
Several Pages can share one app: each agent answers only the messages sent to the Page its access token belongs to.
Configuration
| Field | Required | Where it comes from |
|---|---|---|
appSecret | yes | App settings > Basic. Checks X-Hub-Signature-256 on every delivery |
pageAccessToken | yes | Messenger API Settings > Generate access tokens |
verifyToken | yes | a value you choose and type into the webhook settings |
apiVersion | no | Graph API version such as v21.0. Defaults to the SDK's |
userName | no | name the Chat SDK uses for the Page |
allowedChannelIds | no | people (PSIDs) to answer, or ["*"] for everyone |
allowedUserIds | no | PSIDs allowed to trigger the agent |
trace | no | "enabled" adds the dashboard trace link to replies |
partition | no | workspace folder split. See Workspaces |
A person's id on Messenger is page-scoped (a PSID). Give one person their own rules with a channel:
export const vip = defineMessengerChannel({
name: "vip",
connection: messenger,
psid: "6543210987654321",
instructions: "This is a key account. Offer a call.",
});
What works
- Text in and out. Replies go out in pieces of at most 1900 characters, under the 2000-character Send API limit, so a long one arrives as several messages.
- Buttons and the Get Started button. A tap arrives as the button title.
- Inbound pictures, video, audio and files. Meta hosts them and the agent reads the link.
- Typing indicators.
/new,/compactand the other chat commands.
What does not:
- No sending pictures or files.
send-filesposts links as text instead. - No reactions. A Page cannot react to a message.
- No streaming. The reply goes out whole when the turn ends.
- Echoes of the Page's own messages, reactions, reads and deliveries are ignored.
- Meta allows free-form replies only within 24 hours of the person's last message.
See Channels for commands, channel tools and attachment limits.