Messenger

Create a new bot

Scaffold a Next.js bot with the Messenger adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

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!");
});

The memory state adapter keeps subscriptions and locks in process memory, which suits local development. Use Redis or PostgreSQL in production.

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),
  });
}

Platform setup

Configuration

Environment variables

Webhooks

The route handles two kinds of request from Meta:

• GET verification handshake: Meta sends a hub.verify_token challenge that must match FACEBOOK_VERIFY_TOKEN.
• POST event delivery: incoming messages, reactions, and postbacks, signed with X-Hub-Signature-256 and verified against FACEBOOK_APP_SECRET.

Interactive messages

The adapter converts card elements to Messenger templates:

• Generic Template: used when the card has a title or imageUrl. Up to 3 buttons.
• Button Template: used when the card has text content and buttons but no title or image. Max 640 characters.
• Text fallback: used when the card contains unsupported elements (tables, select menus) or exceeds these constraints.

Constraints:

• Max 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.

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:

bot.onDirectMessage(async (thread) => {
  await thread.markAsRead();
  await thread.post("Thanks, I have seen your message.");
});

Messenger applies this action to the conversation's seen state rather than a single message, even when you pass a message or message ID.

Thread IDs

messenger:{recipientId}

Example: messenger:27161130920158013.

recipientId is the user's ID as Meta sends it in the webhook's sender.id. Each conversation between the Page and one user is one thread.

Feature support