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

``bash
npm install messagix-js
`

Quick Start

$3

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.

$3

`typescript
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:
`env
FB_COOKIES="sb=...; datr=...; c_user=...; xs=...;"
E2EE_PIN="123456"
`

2. Run an example:
`bash
# 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

$3

The main client class for interacting with Messenger.

#### Constructor

`typescript
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

`bash

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