🚀 JOY-FCA: Unofficial Facebook Chat API

A lightweight, fast, and unofficial API to interact with Facebook Chat programmatically — ideal for building bots, automation systems, and custom messaging tools.

This project is customized and enhanced for improved performance and stability.

🌟 What's New in JOY-FCA

• ✨ Enhanced MQTT connection logging
• 🔄 Auto-reconnect with configurable intervals
• 📊 Better connection status indicators
• 🎨 Improved console output with colors
• 🔐 Enhanced security and stability
• 🚀 Automatic update checking and installation
• 💡 Better error handling and debugging

📦 Installation

npm install joy-fca@latest

Or

npm install joy-fca

🚀 Basic Usage

1. Login and Simple Echo Bot

const login = require("joy-fca");

login({ appState: [] }, (err, api) => {
    if (err) return console.error(err);

    api.listenMqtt((err, event) => {
        if (err) return console.error(err);

        // Echo back the received message
        api.sendMessage(event.body, event.threadID);
    });
});

2. Send Text Message

const login = require("joy-fca");

login({ appState: [] }, (err, api) => {
    if (err) {
        console.error("Login Error:", err);
        return;
    }

    let yourID = "000000000000000"; // Replace with actual Facebook ID
    let msg = "Hey!";

    api.sendMessage(msg, yourID, err => {
        if (err) console.error("Message Sending Error:", err);
        else console.log("Message sent successfully!");
    });
});

Tip: To find your Facebook ID, look inside the cookies under the name c_user

3. Send File/Image

const login = require("joy-fca");
const fs = require("fs");

login({ appState: [] }, (err, api) => {
    if (err) {
        console.error("Login Error:", err);
        return;
    }

    let yourID = "000000000000000";
    let imagePath = __dirname + "/image.jpg";

    // Check if file exists
    if (!fs.existsSync(imagePath)) {
        console.error("Error: Image file not found!");
        return;
    }

    let msg = {
        body: "Hey!",
        attachment: fs.createReadStream(imagePath)
    };

    api.sendMessage(msg, yourID, err => {
        if (err) console.error("Message Sending Error:", err);
        else console.log("Message sent successfully!");
    });
});

📝 Message Types

| Type | Usage | | ---------------------- | ----------------------------------------------------------------- | | Regular text | { body: "message text" } | | Sticker | { sticker: "sticker_id" } | | File/Image | { attachment: fs.createReadStream(path) } or array of streams | | URL | { url: "https://example.com" } | | Large emoji | { emoji: "👍", emojiSize: "large" } (small/medium/large) |

Note: A message can only be a regular message (which can be empty) and optionally one of the following: a sticker, an attachment, or a URL.

💾 Saving AppState to Avoid Re-login

Save AppState

const fs = require("fs");
const login = require("joy-fca");

const credentials = { appState: [] };

login(credentials, (err, api) => {
    if (err) {
        console.error("Login Error:", err);
        return;
    }

    try {
        const appState = JSON.stringify(api.getAppState(), null, 2);
        fs.writeFileSync("appstate.json", appState);
        console.log("✅ AppState saved successfully!");
    } catch (error) {
        console.error("Error saving AppState:", error);
    }
});

Use Saved AppState

const fs = require("fs");
const login = require("joy-fca");

login(
    { appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) },
    (err, api) => {
        if (err) {
            console.error("Login Error:", err);
            return;
        }

        console.log("✅ Logged in successfully!");
        // Your code here
    }
);

Alternative: Use c3c-fbstate to get fbstate.json

👂 Listening for Messages

Echo Bot with Stop Command

const fs = require("fs");
const login = require("joy-fca");

login(
    { appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) },
    (err, api) => {
        if (err) {
            console.error("Login Error:", err);
            return;
        }

        // Enable listening to events (join/leave, title change, etc.)
        api.setOptions({ listenEvents: true });

        const stopListening = api.listenMqtt((err, event) => {
            if (err) {
                console.error("Listen Error:", err);
                return;
            }

            // Mark as read
            api.markAsRead(event.threadID, err => {
                if (err) console.error("Mark as read error:", err);
            });

            // Handle different event types
            switch (event.type) {
                case "message":
                    if (event.body && event.body.trim().toLowerCase() === "/stop") {
                        api.sendMessage("Goodbye…", event.threadID);
                        stopListening();
                        return;
                    }
                    api.sendMessage(`TEST BOT: ${event.body}`, event.threadID);
                    break;

                case "event":
                    console.log("Event Received:", event);
                    break;
            }
        });
    }
);

Listen Options

api.setOptions({
    listenEvents: true,  // Receive events (join/leave, rename, etc.)
    selfListen: true,    // Receive messages from yourself
    logLevel: "silent"   // Disable logs (silent/error/warn/info/verbose)
});

By default:

• listenEvents is false - won't receive events like joining/leaving chat, title changes
• selfListen is false - will ignore messages sent by the current account

⚠️ Disclaime

Note: This is an unofficial Facebook API. Use at your own risk. This project is not affiliated with or endorsed by Meta / Facebook in any way.

🚀 DEVELOPMENT APPROACH

• 💻 Copy-paste techniques with customizations
• 🤝 Collaborative development with friends
• 🤖 AI-powered using ChatGPT and other advanced tools

Thanks for using FCA