@chat-adapter/messenger

Facebook Messenger adapter for Chat SDK, using the Messenger Platform API.

Installation

pnpm add @chat-adapter/messenger

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 |

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 |

Message history

| Feature | Supported | |---------|-----------| | Fetch messages | Cached sent messages only | | Fetch thread info | Yes |

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

License

MIT