@chat-adapter/messenger

npm package: @chat-adapter/messenger

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/instagram instead. It connects through Instagram API with Instagram Login and does not require a Facebook Page.

Installation

pnpm add @chat-adapter/messenger

Scaffold with the CLI

To scaffold a new Messenger bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter messenger memory

Visit the adapters directory to see other available official and vendor-official adapters.

Usage

import { Chat } from "chat";
import { createMessengerAdapter } from "@chat-adapter/messenger";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    messenger: createMessengerAdapter(),
  },
});

bot.onDirectMessage(async (thread, message) => {
  await thread.post("Hello from Messenger!");
});

When using createMessengerAdapter() without arguments, credentials are auto-detected from environment variables.

Facebook Messenger setup

1. Create a Meta app

1. Go to developers.facebook.com/apps
2. Click Create App
3. Select the use case "Engage with customers on Messenger from Meta"
4. Enter your app name and contact email, then create the app
5. 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:

1. The easiest approach is to create a Facebook Business profile first
2. Then create a Page under that business profile
3. Note the Page name — users will message this Page to interact with your bot

3. Configure Messenger API

1. In your Meta app dashboard, go to Use Cases
2. Find "Engage with customers on Messenger from Meta" and click Customize
3. Then open Messenger API Settings

Configure webhooks

1. Under Configure webhooks, click Add Callback URL
2. Enter your webhook URL: https://your-domain.com/api/webhooks/messenger
3. Enter a Verify Token — this is a secret string you create (this becomes FACEBOOK_VERIFY_TOKEN)
4. Click Verify and Save
5. After verification, click Add Subscriptions and enable:
   • messages
   • messaging_postbacks
   • messaging_reactions
   • message_deliveries
   • message_reads

Generate a Page Access Token

1. Under Generate access tokens, click Add or remove Pages
2. Your Pages should populate — select the Page you created
3. Assign the standard permissions when prompted
4. Click Generate Token
5. Copy the token — this becomes FACEBOOK_PAGE_ACCESS_TOKEN

Environment variables

FACEBOOK_APP_SECRET=...              # App secret from App Settings > Basic
FACEBOOK_PAGE_ACCESS_TOKEN=...       # Generated Page access token
FACEBOOK_VERIFY_TOKEN=...            # User-defined webhook verification secret
FACEBOOK_BOT_USERNAME=...            # Optional, defaults to "messenger-bot"
FACEBOOK_API_URL=...                 # Optional, override the Meta Graph API base URL

Webhook setup

Messenger uses two webhook mechanisms:

1. Verification handshake (GET) — Meta sends a hub.verify_token challenge that must match your FACEBOOK_VERIFY_TOKEN.
2. Event delivery (POST) — incoming messages, reactions, and postbacks, verified via X-Hub-Signature-256.

// Next.js App Router example
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);
}

Features

Messaging

Rich content

Conversations

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

Interactive messages

Card elements are automatically converted to Messenger templates:

• Generic Template — Used when the card has a title or imageUrl. Supports up to 3 buttons.
• Button Template — Used when the card has text content and buttons but no title/image. Max 640 characters.
• Text Fallback — Used when the card contains unsupported elements (tables, select menus) or exceeds constraints.

Template constraints:

• Maximum 3 buttons per template
• Button titles limited to 20 characters (truncated with ellipsis)
• Subtitles limited to 80 characters
• Button Template text limited to 640 characters

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.

For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).

License

MIT