@chat-adapter/messenger weekly downloads statistics

@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

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

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	Text fallback
Images in cards	Yes (Generic Template)
Modals	No

Conversations

Feature	Supported
Reactions	Receive only
Typing indicator	Yes
DMs	Yes (DM-only platform)
Postbacks	Yes

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:…