Package Exports

@haonguyendevgroup/httpfca

Readme

💬 @haonguyendevgroup/httpfca

Unofficial Facebook Chat API for Node.js - Interact with Facebook Messenger programmatically

Features • Installation • Quick Start • Documentation • Support

📋 Table of Contents

⚠️ Important Disclaimer
✨ Features
🔍 Introduction
📦 Installation
🚀 Quick Start
📝 Message Types
💾 AppState Management
👂 Listening for Messages
🎯 API Quick Reference
📚 Documentation
🛠️ Projects Using This API
🤝 Contributing
📄 License
👨‍💻 Author & Support

⚠️ Important Disclaimer

⚠️ Use at your own risk! We are not responsible for account bans.

We are not responsible if your account gets banned for spammy activities such as:

❌ Sending lots of messages to people you don't know
❌ Sending messages very quickly
❌ Sending spammy looking URLs
❌ Logging in and out very quickly

💡 Recommendations:

Use Firefox browser or visit fca.haonguyendevgroup.id.vn to reduce logout issues (especially for iOS users)
Use AppState instead of credentials when possible
Implement rate limiting in your bots
Follow Facebook's Terms of Service

🆘 Support: If you encounter errors, contact us here

✨ Features

✅ Full Messenger API - Send messages, files, stickers, and more
✅ Real-time Events - Listen to messages, reactions, and thread events
✅ User Account Support - Works with personal Facebook accounts (not just Pages)
✅ AppState Support - Save login state to avoid re-authentication
✅ MQTT Protocol - Real-time messaging via MQTT
✅ TypeScript Support - Includes TypeScript definitions
✅ Active Development - Regularly updated and maintained

🔍 Introduction

Facebook provides an official API for chat bots, but it's only available for Facebook Pages.

@haonguyendevgroup/httpfca is the only API that allows you to automate chat functionalities on a user account by emulating the browser. This means:

🔄 Making the exact same GET/POST requests as a browser
🔐 Does not work with auth tokens
📝 Requires Facebook account credentials (email/password) or AppState

Perfect for:

🤖 Building chatbots
📱 Automating message responses
🔔 Creating notification systems
🎮 Building interactive games
📊 Analytics and monitoring

📦 Installation

npm install @haonguyendevgroup/httpfca@latest

Requirements:

Node.js >= 12.0.0
Active Facebook account

🚀 Quick Start

const login = require("@haonguyendevgroup/httpfca");

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("@haonguyendevgroup/httpfca");

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

    const yourID = "000000000000000"; // Replace with actual Facebook ID
    const 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("@haonguyendevgroup/httpfca");
const fs = require("fs");

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

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

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

    const msg = {
        body: "Check out this image! 📷",
        attachment: fs.createReadStream(imagePath)
    };

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

📝 Message Types

Type	Usage	Example
Regular text	`{ body: "message text" }`	`{ body: "Hello!" }`
Sticker	`{ sticker: "sticker_id" }`	`{ sticker: "369239263222822" }`
File/Image	`{ attachment: fs.createReadStream(path) }`	`{ attachment: fs.createReadStream("image.jpg") }`
URL	`{ url: "https://example.com" }`	`{ url: "https://github.com" }`
Large emoji	`{ emoji: "👍", emojiSize: "large" }`	`{ emoji: "👍", emojiSize: "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.

Emoji sizes: small | medium | large

💾 AppState Management

Save AppState

Save your login session to avoid re-authentication:

const fs = require("fs");
const login = require("@haonguyendevgroup/httpfca");

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

Load your saved AppState for faster login:

const fs = require("fs");
const login = require("@haonguyendevgroup/httpfca");

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("@haonguyendevgroup/httpfca");

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(`🤖 BOT: ${event.body}`, event.threadID);
                    break;

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

Listen Options

Configure listening behavior:

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

Default values:

listenEvents: false - won't receive events like joining/leaving chat, title changes
selfListen: false - will ignore messages sent by the current account
logLevel: "info" - default logging level

🎯 API Quick Reference

📨 Messaging Methods

// Send message
api.sendMessage(message, threadID, callback);

// Send typing indicator
api.sendTypingIndicator(threadID, callback);

// Get message
api.getMessage(threadID, limit, callback);

// Edit message
api.editMessage(message, messageID, callback);

// Delete message
api.deleteMessage(messageID, callback);

// Unsend message
api.unsendMessage(messageID, callback);

// Set message reaction
api.setMessageReaction(reaction, messageID, callback);

// Forward attachment
api.forwardAttachment(attachmentID, threadID, callback);

// Upload attachment
api.uploadAttachment(attachment, callback);

// Create poll
api.createPoll(question, options, threadID, callback);

// Create theme AI
api.createThemeAI(threadID, callback);

// Get theme pictures
api.getThemePictures(threadID, callback);

// Get emoji URL
api.getEmojiUrl(emoji, size, callback);

// Resolve photo URL
api.resolvePhotoUrl(photoID, callback);

📬 Read Receipt & Delivery

// Mark as read
api.markAsRead(threadID, callback);

// Mark as read all
api.markAsReadAll(callback);

// Mark as delivered
api.markAsDelivered(threadID, callback);

// Mark as seen
api.markAsSeen(threadID, callback);

👥 Thread Management

// Get thread info
api.getThreadInfo(threadID, callback);

// Get thread list
api.getThreadList(limit, timestamp, callback);

// Get thread history
api.getThreadHistory(threadID, amount, timestamp, callback);

// Get thread pictures
api.getThreadPictures(threadID, limit, callback);

// Search for thread
api.searchForThread(name, callback);

// Delete thread
api.deleteThread(threadID, callback);

🎨 Thread Customization

// Change thread color
api.changeThreadColor(color, threadID, callback);

// Change thread emoji
api.changeThreadEmoji(emoji, threadID, callback);

// Change group image
api.changeGroupImage(image, threadID, callback);

// Set title
api.setTitle(title, threadID, callback);

// Change nickname
api.changeNickname(nickname, userID, threadID, callback);

👤 User Management

// Get user info
api.getUserInfo(userID, callback);

// Get user info V2
api.getUserInfoV2(userID, callback);

// Get user ID
api.getUserID(username, callback);

// Get friends list
api.getFriendsList(callback);

// Get current user ID
api.getCurrentUserID(callback);

👥 Group Management

// Create new group
api.createNewGroup(participantIDs, groupTitle, callback);

// Add user to group
api.addUserToGroup(userID, threadID, callback);

// Remove user from group
api.removeUserFromGroup(userID, threadID, callback);

// Change admin status
api.changeAdminStatus(userID, threadID, admin, callback);

⚙️ Thread Settings

// Mute thread
api.muteThread(threadID, muteSeconds, callback);

// Change archived status
api.changeArchivedStatus(threadID, archived, callback);

// Change blocked status
api.changeBlockedStatus(userID, block, callback);

// Handle message request
api.handleMessageRequest(threadID, accept, callback);

// Share contact
api.shareContact(contactID, threadID, callback);

// Change avatar
api.changeAvatar(image, callback);

// Change bio
api.changeBio(bio, callback);

// Handle friend request
api.handleFriendRequest(userID, accept, callback);

// Unfriend
api.unfriend(userID, callback);

// Set post reaction
api.setPostReaction(postID, reaction, callback);

// Refresh fb_dtsg
api.refreshFb_dtsg(callback);

🔐 Authentication

// Logout
api.logout(callback);

// Get app state
api.getAppState();

// Set options
api.setOptions(options);

📡 Listening

// Listen to MQTT events
api.listenMqtt(callback);

Event Types

message - New message received
event - Thread events (join, leave, title change, etc.)
typ - Typing indicator
read_receipt - Read receipt
presence - User presence (online/offline)
read - Message read status
delivery_receipt - Message delivery receipt

📚 Documentation

For detailed API documentation, see DOCS.md

Includes:

📖 All available API methods
🔧 Parameters and options
📨 Event types and structures
⚠️ Error handling
💡 Advanced usage examples

📄 License

This project is licensed under the MIT License - see the LICENSE-MIT file for details.

👨‍💻 Author & Support

Tran Hao Nguyenn Devoloper

JSPM