Unofficial Facebook Messenger API

[!TIP] The project has been moved here. The original repository will be archived.

Facebook now has an official API for chat bots here.

This API is one of the ways to automate chat functions on user accounts. Using the mautrix-meta library (Go) through FFI binding, this library supports (almost) all features that the original library has implemented through a high-level JavaScript API.

[!CAUTION] Using this feature on user accounts is prohibited under Meta's Terms of Service and may result in account suspension. I am not responsible for any Meta accounts that are suspended due to using this library.

Installation

npm install meta-messenger.js

Requirements

• Node.js >= 22
• Cookies from a logged-in Facebook/Messenger account

Usage Example

import { Client, Utils } from 'meta-messenger.js'
import { readFileSync } from 'fs'

// Read cookies from file (supports multiple formats)
const cookies = Utils.parseCookies(readFileSync('cookies.json', 'utf-8'))

// Create a new client
const client = new Client(cookies)

// Listen to events
client.on('message', async (message) => {
    console.log(`Message from ${message.senderId}: ${message.text}`)
    
    // Simple echo bot
    if (message.text === 'ping') {
        await client.sendMessage(message.threadId, 'pong')
    }
})

// Connect
await client.connect()
console.log(`Logged in as: ${client.user?.name}`)

Documentation

Main Features

Send Messages

// Simple message
await client.sendMessage(threadId, 'Hello!')

// Message with reply
await client.sendMessage(threadId, {
    text: 'This is a reply',
    replyToId: 'mid.xxx'
})

// Message with mention
await client.sendMessage(threadId, {
    text: 'Hello @friend!',
    mentions: [{ userId: 123456, offset: 6, length: 7 }]
})

Send Media

import { readFileSync } from 'fs'

// Send image
const image = readFileSync('photo.jpg')
await client.sendImage(threadId, image, 'photo.jpg', 'Caption here')

// Send video
const video = readFileSync('video.mp4')
await client.sendVideo(threadId, video, 'video.mp4')

// Send sticker
await client.sendSticker(threadId, 369239263222822) // thumbs up

Save E2EE State

To persist the E2EE state for later use, you should save the device data to a file:

import { writeFileSync, readFileSync } from 'fs'

// Save device data when it changes
client.on('deviceDataChanged', ({ deviceData }) => {
    writeFileSync('device.json', deviceData)
})

// Load device data on startup
const deviceData = readFileSync('device.json', 'utf-8')
const client = new Client(cookies, { deviceData })

Listen to Messages

client.on('message', (message) => {
    console.log(`[${message.threadId}] ${message.senderId}: ${message.text}`)
    
    // Handle attachments
    for (const att of message.attachments || []) {
        if (att.type === 'image') {
            console.log(`  Image: ${att.url}`)
        } else if (att.type === 'sticker') {
            console.log(`  Sticker: ${att.stickerId}`)
        }
    }
})

// E2EE messages
client.on('e2eeMessage', (message) => {
    console.log(`[E2EE] ${message.senderJid}: ${message.text}`)
})

Supported Cookie Formats

The API supports multiple cookie formats through Utils.parseCookies():

1. C3C UFC Utility / EditThisCookie
2. Simple object
3. Cookie header string
4. Netscape cookie file format
5. Base64 encoded (any of the above formats)

Required cookies: c_user, xs (others like datr, fr are optional)

FAQs

1. How do I get cookies?

Log in to Facebook in your browser, open DevTools (F12), go to Application > Cookies tab, and copy the values for c_user, xs (and optionally datr, fr).

2. Why am I not receiving E2EE messages?

Make sure you have enabled E2EE with enableE2EE: true and wait for the fullyReady event before processing messages.

3. What's the difference between message and e2eeMessage events?

• message: Regular messages, metadata visible to Facebook
• e2eeMessage: End-to-end encrypted messages, only sender and receiver can read

4. Why do I need to wait for fullyReady?

The fullyReady event is emitted when both socket and E2EE (if enabled) are ready. If you process messages before this, you may miss some E2EE messages.

License

GNU Affero General Public License v3.0

According to mautrix-meta License

Credits

• Claude Opus 4.5 - Supports understanding and developing this library
• mautrix-meta - A Matrix-Facebook Messenger and Instagram DM puppeting bridge.
• whatsmeow - Go library for the WhatsApp web multidevice API
• facebook-chat-api - Inspired the API Style
• whatsmeow-node - Reference for writing NodeJS library with FFI.
• koffi - Fast and easy-to-use C FFI module for Node.js
• imhiendev/LoginFacebookAppKatanaAPI - Source code for logging into a Facebook account

Disclaimer

All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
"Facebook", "Messenger", "Meta", "Instagram" is a registered trademark of Meta, Inc., used under license agreement.