💬 fca-ultimate-edition

Unofficial Facebook Chat API for Node.js - The Ultimate Edition

📋 Table of Contents

• ⚠️ Disclaimer & Support Policy
• ✨ Features
• 🚀 Quick Start
• 📚 API Reference
• 💾 AppState Management
• 🔄 Auto Login
• 🔐 Security & Anti-Ban
• 🤝 Contributing
• 📄 License
• 👨‍💻 Author

⚠️ Disclaimer & Support Policy

READ THIS BEFORE USING OR OPENING AN ISSUE.

This repository is provided "AS IS" and is entirely open-source. By using this project, you explicitly agree to the following terms:

1. Use at your own risk: We are NOT responsible if your account gets banned for spammy activities (sending messages too fast, unsolicited mass messaging, suspicious URLs, or rapid login/logout).
2. No Spoon-Feeding: This is a tool for developers. If you cannot read source code, navigate directories, or use basic search tools (Ctrl + Shift + F), you should not be using this library.
3. No Free Programming Lessons: The maintainers provide core updates and security patches for the community for free. We do not provide free JavaScript/TypeScript tutorials, nor will we tell you exactly which line of code to edit for your specific bot.
4. Custom Features = Paid Service: Brainpower and time are not free. If you need custom logic, reverse-engineer specific endpoints, or 1-on-1 support for your personal project, that is a paid service.

If you do not agree with this policy, you are free to fork the repository and maintain it yourself.

Recommendations to minimize ban risks:

• Utilize AppState over direct email/password authentication whenever possible.
• Implement strict rate limiting within your bot's operations.
• Ensure your application adheres to Facebook's platform policies.

✨ Features

This fca-ultimate-edition extends the base functionality with advanced features for a more robust and versatile Facebook automation experience:

| Category | Feature | Description | | :--- | :--- | :--- | | Core Messenger | 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. | | Story Interaction | getStories, reactStory, viewStory | Friends' stories can be viewed, reacted to, and marked as 'Seen'. | | Group Management | getGroupJoinRequests, handleGroupJoinRequest | View and manage pending group join requests. | | Feed Interaction | getPostInfo, commentOnPost | Retrieve detailed information about a specific post and comment on it. | | Advanced Messaging | sendVoiceMessage | Send audio files as native voice notes. | | Reels Interaction | getReels, reactReel | Fetch and react to Facebook Reels. | | Professional Mode | getProfessionalInfo, toggleProfessionalMode | View professional profile information and toggle Professional Mode. | | Security & Anti-Ban | Request Throttling | Configurable delay between requests to avoid detection. | | | User-Agent Rotation | Automatic rotation of User-Agents for each request. |

🚀 Quick Start

Installation

To install fca-ultimate-edition, ensure you have Node.js (version 12.0.0 or higher) installed. Then, use npm:

npm install fca-ultimate-edition

Basic Usage (Echo Bot)

Here's a simple example to get started with an echo bot:

const login = require("fca-ultimate-edition");

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

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

    if (event.type === "message") {
      api.sendMessage(event.body, event.threadID);
    }
  });
});

Sending a Text Message

const login = require("fca-ultimate-edition");

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

  const yourID = "000000000000000"; // Replace with actual Facebook ID
  const msg = "Hello from FCA Ultimate Edition! 👋";

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

📚 API Reference

Detailed documentation for each API endpoint, including parameters and return types, can be found within the src/api directory of this repository. Key modules include action, messaging, threads, users, stories, groups, feed, reels, and professional.

💾 AppState Management

AppState is crucial for maintaining login sessions without re-authenticating with email/password. It helps prevent frequent logouts and reduces the risk of account flags.

Saving AppState

const fs = require("fs");
const login = require("fca-ultimate-edition");

login({ email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }, (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);
  }
});

Using Saved AppState

const fs = require("fs");
const login = require("fca-ultimate-edition");

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

    console.log("✅ Logged in successfully using AppState!");
    // Your bot logic here
  },
);

🔄 Auto Login

This library supports automatic re-login if your session expires, ensuring continuous operation of your bot. Configure fca-config.json in your project root:

{
  "autoLogin": true,
  "credentials": {
    "email": "YOUR_EMAIL_OR_PHONE",
    "password": "YOUR_PASSWORD",
    "twofactor": "" // Base32 secret for 2FA, leave empty if not used
  }
}

If autoLogin is true and credentials are provided, the library will attempt to re-authenticate if the current session becomes invalid.

🔐 Security & Anti-Ban

To enhance the longevity and stability of your bot, fca-ultimate-edition includes built-in anti-ban measures:

• Request Throttling: A default delay of 500ms is introduced between API requests. This can be configured in src/utils/request/config.js via requestThrottlingMs.
• User-Agent Rotation: The library automatically rotates through a list of up-to-date browser User-Agents (as of March 2026) to mimic legitimate browser traffic, reducing the likelihood of detection and blocking by Facebook.

🤝 Contributing

Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please feel free to open an issue or submit a pull request to the repository.

📄 License

This project is open-source and available under the MIT License.

👨‍💻 Author

Developed and maintained by IRFAN.