messagix-js

A TypeScript library for interacting with Facebook Messenger, inspired by the mautrix-meta Go implementation.

⚠️ Warning: This library uses unofficial APIs and may break at any time. Use at your own risk. This library is not affiliated with or endorsed by Meta/Facebook.

Features

• 🔌 Real-time messaging via MQTT WebSocket (Lightspeed protocol)
• 📨 Send & receive messages including text (replies, mentions) and reactions
• 🔒 End-to-End Encryption (E2EE) support (requires PIN)
• 😀 Reactions - add and remove reactions
• ✏️ Edit & delete messages
• 👀 Typing indicators and read receipts
• 🔐 Cookie-based authentication (session persistence)
• 🌐 Cross-platform - Works in Node.js and Browser environments
• 📱 Platform support - Facebook, Messenger, Instagram (partial)

Installation

npm install messagix-js

Quick Start

1. Prerequisite: Cookies & E2EE

You'll need your browser cookies to authenticate. If you want to access E2EE conversations (most new chats), you also need your 6-digit PIN.

1. Log into messenger.com in your browser.
2. Open Developer Tools (F12) -> Network tab.
3. Refresh the page and look for a request to messenger.com.
4. Copy the Cookie header value.
5. (Optional) Find your 6-digit PIN code in Messenger settings if E2EE is enabled.

2. Basic Usage

import { MessengerClient, Platform, CookieManager } from 'messagix-js';

// Parse cookies from string (e.g., from process.env)
const cookieManager = CookieManager.fromString(Platform.Messenger, process.env.FB_COOKIES);

const client = new MessengerClient({
    platform: Platform.Messenger,
    cookies: cookieManager.getAll(),
    // Enable E2EE if you have your PIN
    enableE2EE: true,
    e2eePin: process.env.E2EE_PIN, 
});

// Listen for messages
client.on('message', async (event) => {
    console.log(`Message from ${event.senderId}: ${event.text}`);
    
    // Ignore own messages
    if (event.senderId === client.getUserId()) return;

    // Reply to the message
    await client.sendMessage(event.threadId, 'Hello!', {
        replyToMessageId: event.messageId
    });
});

// Connect
await client.loadMessagesPage();
await client.connect();

Running Examples

This repository includes several examples using dotenv for configuration.

1. Create a .env file in the root directory:

   FB_COOKIES="sb=...; datr=...; c_user=...; xs=...;"
   E2EE_PIN="123456"

2. Run an example:

   # Send a test message
   npx tsx examples/send-message.ts
   
   # Fetch inbox and listen for updates
   npx tsx examples/get-inbox.ts
   
   # Basic echo bot
   npx tsx examples/basic-usage.ts

API Reference

MessengerClient

The main client class for interacting with Messenger.

Constructor

new MessengerClient(config: ClientConfig)

ClientConfig:

• platform: Platform.Messenger, Platform.Facebook, or Platform.Instagram
• cookies: Object containing cookie key-values
• enableE2EE: Boolean to enable E2EE support
• e2eePin: Your 6-digit PIN string
• logger: Optional custom logger

Methods

All IDs (user IDs, thread IDs, message IDs) are strings to prevent precision loss.

| Method | Description | |--------|-------------| | loadMessagesPage() | Initial handshake to extract tokens & config | | connect() | Connect to Messenger via MQTT | | disconnect() | Disconnect from Messenger | | getThreads(options?) | Fetch list of chat threads (inbox) | | getMessages(threadId, options?) | Fetch message history from a thread | | sendMessage(threadId, text, options?) | Send a text message (supports replies) | | sendReaction(threadId, messageId, emoji) | Add a reaction to a message | | removeReaction(threadId, messageId) | Remove your reaction from a message | | editMessage(messageId, text) | Edit a message | | deleteMessage(messageId) | Delete (unsend) a message | | markThreadRead(threadId, timestamp?) | Mark a thread as read | | isConnected() | Check if connected | | getUserId() | Get the current user's ID (string) |

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | - | Connected and ready | | message | MessageEvent | New message received | | reaction | ReactionEvent | Reaction added | | typing | {threadId, senderId, isTyping} | Typing indicator | | readReceipt | {threadId, senderId, watermark} | Read receipt | | threadsUpdated | ThreadInfo[] | Thread list updated (from sync) | | connected | - | Successfully connected | | disconnected | Error? | Disconnected | | error | Error | Error occurred |

Architecture

This library implements the Facebook Lightspeed protocol, which uses MQTT for transport and a custom binary protocol for data syncing.

src/
├── auth/           # Cookie management
├── e2ee/           # E2EE (End-to-End Encryption) implementation
├── protocol/
│   ├── packets/    # MQTT packet encoding/decoding
│   ├── lightspeed/ # Facebook's Lightspeed protocol decoder
│   └── tasks/      # Task payloads for messaging operations
├── transport/      # HTTP, WebSocket, MQTT clients
├── types/          # TypeScript type definitions
└── client.ts       # Main MessengerClient class

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

Acknowledgments

This project is based on the mautrix-meta Go implementation. Special thanks to the mautrix team for their reverse-engineering efforts.

License

AGPL-3.0-or-later