Building for Instagram Direct Messages? Use @chat-adapter/instagram instead. It connects through Instagram API with Instagram Login and does not require a Facebook Page.
Visit the adapters directory to see other available official and vendor-official adapters.
Usage
import { Chat } from "chat";import { createMessengerAdapter } from "@chat-adapter/messenger";import { createMemoryState } from "@chat-adapter/state-memory";const bot = new Chat({ userName: "mybot", adapters: { messenger: createMessengerAdapter(), }, state: createMemoryState(),});bot.onDirectMessage(async (thread, message) => { await thread.post("Hello from Messenger!");});
When using createMessengerAdapter() without arguments, credentials are auto-detected from environment variables.
The memory state adapter keeps subscriptions and locks in process memory, which suits local development. Use a Redis or PostgreSQL state adapter in production.
Select the use case "Engage with customers on Messenger from Meta"
Enter your app name and contact email, then create the app
Go to App > App Settings > Basic and copy your App Secret — this becomes FACEBOOK_APP_SECRET
2. Create a Facebook Page
Your Messenger bot needs a Facebook Page to send and receive messages. If you don't have one:
The easiest approach is to create a Facebook Business profile first
Then create a Page under that business profile
Note the Page name — users will message this Page to interact with your bot
3. Configure Messenger API
In your Meta app dashboard, go to Use Cases
Find "Engage with customers on Messenger from Meta" and click Customize
Then open Messenger API Settings
Configure webhooks
Under Configure webhooks, click Add Callback URL
Enter your webhook URL: https://your-domain.com/api/webhooks/messenger
Enter a Verify Token — this is a secret string you create (this becomes FACEBOOK_VERIFY_TOKEN)
Click Verify and Save
After verification, click Add Subscriptions and enable:
messages
messaging_postbacks
messaging_reactions
message_deliveries
message_reads
Generate a Page Access Token
Under Generate access tokens, click Add or remove Pages
Your Pages should populate — select the Page you created
Assign the standard permissions when prompted
Click Generate Token
Copy the token — this becomes FACEBOOK_PAGE_ACCESS_TOKEN
Configuration
You can call createMessengerAdapter() with no arguments when the environment variables are set.
Option
Required
Description
appSecret
No*
App secret for webhook signature verification. Auto-detected from FACEBOOK_APP_SECRET
pageAccessToken
No*
Page access token. Auto-detected from FACEBOOK_PAGE_ACCESS_TOKEN
verifyToken
No*
Webhook verify token. Auto-detected from FACEBOOK_VERIFY_TOKEN
apiVersion
No
Graph API version (defaults to v21.0)
userName
No
Bot username. Defaults to the Page name, or to the userName passed to Chat when the Page lookup fails
logger
No
Logger instance (defaults to ConsoleLogger("info"))
*Required at runtime, either in config or as an environment variable.
Environment variables
FACEBOOK_APP_SECRET=... # App secret from App Settings > BasicFACEBOOK_PAGE_ACCESS_TOKEN=... # Generated Page access tokenFACEBOOK_VERIFY_TOKEN=... # Webhook verify token that you choose
All three are required unless you pass the matching option to createMessengerAdapter().
Webhook setup
Messenger uses two webhook mechanisms:
Verification handshake (GET). Meta sends hub.mode=subscribe and a hub.verify_token that must match your FACEBOOK_VERIFY_TOKEN. A mismatch gets a 403 response.
Event delivery (POST). Incoming messages, reactions, and postbacks are verified with the X-Hub-Signature-256 header. A missing or wrong signature gets a 403 response.
// Next.js App Router exampleimport { after } from "next/server";import { bot } from "@/lib/bot";export async function GET(request: Request) { return bot.webhooks.messenger(request);}export async function POST(request: Request) { return bot.webhooks.messenger(request, { waitUntil: (task) => after(() => task), });}
The adapter responds before your handlers finish, so pass waitUntil on serverless platforms to keep the function alive until they do.
Features
Messaging
Feature
Supported
Post message
Yes
Edit message
No (Messenger limitation)
Delete message
No (Messenger limitation)
Streaming
Buffered (accumulates then sends)
Typing indicator
Yes
Mark as read
Yes
File uploads
No
Text is limited to 2000 characters. Longer text is cut to 1997 characters followed by ..., and isn't split across messages.
Rich content
Feature
Supported
Card format
Generic/Button Templates
Buttons
Yes (max 3 per message)
Link buttons
Yes (web_url)
Select menus
No
Tables
Text fallback
Fields
Rendered as Label: Value text lines
Images in cards
Card imageUrl only (Generic Template)
Modals
No
Conversations
Feature
Supported
Reactions
Receive only
DMs
Yes (DM-only platform)
Postbacks
Yes
Every inbound message is treated as a mention, because each conversation is a direct message with your Page. Button taps arrive through onAction. A quick-reply tap arrives as an ordinary text message.
Inbound attachments
Inbound attachment URLs remain available as attachment.url. The adapter's
fetchData function downloads media only from Meta's fbsbx.com and
fbcdn.net hosts, refuses private and internal addresses (including after
redirects), limits responses to 25 MB, and times out after 30 seconds.
External fallback and link-share URLs are preserved but rejected before any
network request.
Read receipts
Use thread.markAsRead() in a message handler to send Messenger's mark_seen sender action:
await thread.markAsRead();
Messenger applies this action to the conversation's seen state rather than a single message, even when you pass a message or message ID.
Message history
Feature
Supported
Fetch messages
In-memory cache only
Fetch thread info
Yes
Messenger has no API for listing past messages, so fetchMessages reads from an in-memory cache of the messages this process has received and sent. The cache is empty after a restart and isn't shared between instances.
Interactive messages
The adapter converts a card to one Messenger template when it can:
Generic Template: the card has at least one button and a title or imageUrl.
Button Template: the card has at least one button and body text, but no title or image.
Text: the card has no buttons, or contains a table, select menu, or radio select.
The adapter trims content to Messenger's limits and doesn't fall back to text for them:
Only the first 3 buttons are sent. Extra buttons are dropped.
Button labels longer than 20 characters are truncated with an ellipsis.
Titles and subtitles longer than 80 characters are truncated.
Button Template text longer than 640 characters is truncated.
API errors
Failed Graph API calls throw the error classes from @chat-adapter/shared:
Response
Error
HTTP 429, or Meta codes 4, 32, 613
AdapterRateLimitError, with retryAfter in seconds when Meta sends a Retry-After header
HTTP 401, or Meta code 190
AuthenticationError
HTTP 403, or Meta codes 10, 200
ValidationError
HTTP 404
ResourceNotFoundError
Anything else, and network failures
NetworkError
The adapter sends every message as a standard response and doesn't track Messenger's 24-hour messaging window. A send outside the window fails with the error the Graph API returns.
Thread ID format
messenger:{recipientId}
Example: messenger:27161130920158013
AI Coding Agents
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chat
The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.