package
Facebook Messenger adapter for Chat SDK — Send API webhooks, templates, and postbacks
npm install @chat-adapter/messengerGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
Facebook Messenger adapter for Chat SDK, using the Messenger Platform API.
Documentation: chat-sdk.dev/adapters/official/messenger · Guides: vercel.com/kb/chat-sdk
Building for Instagram Direct Messages? Use
@chat-adapter/instagraminstead. It connects through Instagram API with Instagram Login and does not require a Facebook Page.
pnpm add @chat-adapter/messenger @chat-adapter/state-memoryTo scaffold a new Messenger bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter messenger memoryVisit the adapters directory to see other available official and vendor-official adapters.
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.
FACEBOOK_APP_SECRETYour Messenger bot needs a Facebook Page to send and receive messages. If you don't have one:
https://your-domain.com/api/webhooks/messengerFACEBOOK_VERIFY_TOKEN)messagesmessaging_postbacksmessaging_reactionsmessage_deliveriesmessage_readsFACEBOOK_PAGE_ACCESS_TOKENYou 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.
FACEBOOK_APP_SECRET=... # App secret from App Settings > Basic
FACEBOOK_PAGE_ACCESS_TOKEN=... # Generated Page access token
FACEBOOK_VERIFY_TOKEN=... # Webhook verify token that you chooseAll three are required unless you pass the matching option to createMessengerAdapter().
Messenger uses two webhook mechanisms:
hub.mode=subscribe and a hub.verify_token that must match your FACEBOOK_VERIFY_TOKEN. A mismatch gets a 403 response.X-Hub-Signature-256 header. A missing or wrong signature gets a 403 response.// Next.js App Router example
import { 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.
| 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.
| 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 |
| 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 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.
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.
| 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.
The adapter converts a card to one Messenger template when it can:
title or imageUrl.The adapter trims content to Messenger's limits and doesn't fall back to text for them:
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.
messenger:{recipientId}Example: messenger:27161130920158013
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/chatThe 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-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 24 packages.
2.4 MB
Includes dependencies.