🚀 fca-sahil - Advanced Facebook Chat API

Disclaimer: Use responsibly. We are not liable for account bans due to spammy activities, such as sending excessive messages, rapid logins/logouts, or sharing suspicious URLs. Be a responsible Facebook user.

🤔 What is the purpose of this package?

fca-sahil (Sahil Facebook Chat API) is a powerful Node.js package for automating Facebook Messenger bot with enhanced features and reliability. Developed by Sahil.

📖 Table of Contents

• Features
• Installation
• Usage
• Main Functionality
  • Sending Messages
  • Saving Sessions
  • Listening to Chats
  • Group Management
  • Post Interactions
• Advanced Features
• API Reference
• FAQ
• Support
• License

✨ Features

• Automatic Re-login: Detects errors and automatically re-logs in using the cookie. If the cookie is logged out, it prompts for re-submission or refreshes automatically.
• Account Lock/Suspension Detection: Stops the login process and displays details if an account is locked or suspended.
• Token Refresh: Automatically refreshes fb_dtsg (Facebook's dynamic token) daily at 12:00 AM (GMT+8 PH time).
• Random User Agent: Experimental feature to reduce logouts (setOptions).
• Bypass Region: Choose regions like PRN, PNB, HKG, SYD, VLL, LLA, SIN (experimental).
• Optimized User Agent: For fewer account logouts.
• Enhanced Group Messaging: Fixed support for both 15-digit and 16-digit group UIDs.
• Comprehensive API: Full support for messages, stickers, attachments, mentions, reactions, and more.

🚀 Installation

Install the latest version of fca-sahil via npm:

npm install fca-sahil@latest

🛠 Usage

Below is an example of creating a simple echo bot that repeats messages sent to it:

const sahil = require("fca-sahil");

sahil.login('Provide your cookie here',
  { /* setOptions here */ },
  (err, api) => {
    if (err) return console.error(err);
    api.listenMqtt((err, event) => {
      if (err) return console.error(err);
      api.sendMessage(event.body, event.threadID);
    });
  }
);

💡 Fun fact: You can also use header string based cookie.

🤔 How to get it? Head over to FAQ section below.

🔧 Main Functionality

Sending Messages

api.sendMessage(message, threadID[, callback][, messageID][, isGroup])

Send various types of messages:

• Regular: Use body for text messages.
• Sticker: Set sticker to a sticker ID.
• File/Image: Set attachment to a readable stream or array of streams.
• URL: Set url to a link.
• Emoji: Set emoji to an emoji string and emojiSize (small, medium, large).

Note: The isGroup parameter helps distinguish between individual and group chats. Set to true for group chats, false for individual chats, or leave undefined for automatic detection.

Example (Basic Message):

const sahil = require("fca-sahil");

sahil.login('Provide your cookie here', (err, api) => {
  if (err) return console.error(err);
  const yourID = "000000000000000";
  const msg = "Hey!";
  api.sendMessage(msg, yourID);
});

Example (Group Message):

const sahil = require("fca-sahil");

sahil.login('Provide your cookie here', (err, api) => {
  if (err) return console.error(err);
  const groupID = "123456789012345"; // Works with both 15 and 16 digit UIDs
  const msg = "Hello Group!";
  api.sendMessage(msg, groupID, null, null, true); // isGroup = true
});

Example (File Upload):

const fs = require("fs");
const sahil = require("fca-sahil");

sahil.login('Provide your cookie here', (err, api) => {
  if (err) return console.error(err);
  const yourID = "000000000000000";
  const msg = {
    body: "Hey!",
    attachment: fs.createReadStream(__dirname + "/image.jpg"),
  };
  api.sendMessage(msg, yourID);
});

Saving Sessions

Save the cookie to avoid re-entering credentials:

const fs = require("fs");
const sahil = require("fca-sahil");
const cookie = 'Provide your cookie here';

sahil.login(cookie, (err, api) => {
  if (err) return console.error(err);
  fs.writeFileSync("cookie.txt", cookie, "utf-8");
});

Listening to Chats

api.listenMqtt(callback)

Listens for incoming messages. Enable events (e.g., join/leave, title changes) with api.setOptions({ listenEvents: true }). To include your own messages, use api.setOptions({ selfListen: true }).

Example (Echo Bot with Stop Command):

const fs = require("fs");
const sahil = require("fca-sahil");

sahil.login(fs.readFileSync("cookie.txt", "utf8"), (err, api) => {
  if (err) return console.error(err);
  api.setOptions({ listenEvents: true });

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

    api.markAsRead(event.threadID, (err) => {
      if (err) console.error(err);
    });

    switch (event.type) {
      case "message":
        if (event.body === "/stop") {
          api.sendMessage("Goodbye…", event.threadID);
          return stopListening();
        }
        api.sendMessage("TEST BOT: " + event.body, event.threadID);
        break;
      case "event":
        console.log(event);
        break;
    }
  });
});

Group Management

api.addUserToGroup(userID, threadID, callback)

Add users to a group chat.

api.addUserToGroup("100012345678901", "123456789012345", (err) => {
  if (err) return console.error(err);
  console.log("User added successfully!");
});

api.changeNickname(nickname, threadID, participantID, callback)

Change a user's nickname in a thread.

api.changeNickname("NewNickname", "123456789012345", "100012345678901", (err) => {
  if (err) return console.error(err);
  console.log("Nickname changed!");
});

api.setTitle(newTitle, threadID, callback)

Change the title of a group chat.

api.setTitle("New Group Name", "123456789012345", (err) => {
  if (err) return console.error(err);
  console.log("Group name changed!");
});

Post Interactions

api.createCommentPost(message, postID, callback, replyCommentID)

Comment on a Facebook post.

const msg = {
  body: "Great post!",
  mentions: [{ tag: "@John", id: "100012345678901" }],
  attachments: [fs.createReadStream("image.jpg")]
};

api.createCommentPost(msg, "123456789_987654321", (err, info) => {
  if (err) return console.error(err);
  console.log("Comment created:", info);
});

🌟 Advanced Features

Message Reactions

api.setMessageReaction("❤️", messageID, (err) => {
  if (err) return console.error(err);
  console.log("Reaction added!");
});

Typing Indicator

api.sendTypingIndicator(threadID, (err) => {
  if (err) return console.error(err);
});

Thread Management

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

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

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

📚 API Reference

Core Functions

• login(cookie, options, callback) - Login to Facebook
• setOptions(options) - Configure bot behavior
• getAppState() - Get current session state

Messaging

• sendMessage(message, threadID, callback, messageID, isGroup) - Send messages
• sendMessageMqtt(message, threadID, callback, messageID) - Send via MQTT
• editMessage(text, messageID, callback) - Edit sent messages
• unsendMessage(messageID, callback) - Unsend messages
• forwardAttachment(attachmentID, userOrGroupIDs, callback) - Forward attachments

Group Management

• addUserToGroup(userID, threadID, callback) - Add members
• removeUserFromGroup(userID, threadID, callback) - Remove members
• changeNickname(nickname, threadID, participantID, callback) - Change nicknames
• setTitle(title, threadID, callback) - Change group name
• changeGroupImage(attachment, threadID, callback) - Change group image

User Information

• getUserInfo(userID, callback) - Get user details
• getUserID(name, callback) - Get user ID by name
• getFriendsList(callback) - Get friends list
• getThreadInfo(threadID, callback) - Get thread details
• getThreadHistory(threadID, amount, timestamp, callback) - Get message history

Reactions & Interactions

• setMessageReaction(reaction, messageID, callback) - React to messages
• setPostReaction(reaction, postID, callback) - React to posts
• createCommentPost(message, postID, callback, replyCommentID) - Comment on posts

Thread Customization

• changeThreadColor(color, threadID, callback) - Change thread color
• changeThreadEmoji(emoji, threadID, callback) - Change thread emoji
• muteThread(threadID, muteSeconds, callback) - Mute notifications

Status & Presence

• sendTypingIndicator(threadID, callback) - Show typing indicator
• markAsRead(threadID, callback) - Mark as read
• markAsDelivered(messageID, threadID, callback) - Mark as delivered

❓ FAQ

Q: How do I handle Promise rejection errors?
Add this code to your index.js to log unhandled rejections:

process.on("unhandledRejection", (reason, promise) => {
  console.error("Unhandled Rejection at:", promise, "reason:", reason);
});

Q: How do I get a cookie?
Use a cookie editor extension on browsers like Firefox, Kiwi, Edge, or Chrome. Export your Facebook cookies in JSON format or as a header string.

Q: Why is my bot not sending messages to groups with 15-digit UIDs?
fca-sahil has fixed this issue! The package now properly handles both 15-digit and 16-digit group UIDs. Make sure to pass isGroup: true as the last parameter when sending to groups.

Q: What if I encounter errors?
Check the error message for details. Common issues include:

• Invalid cookie (re-login required)
• Account checkpoint (verify in browser)
• Not a member of the group
• Invalid thread ID

Q: How do I use mentions in messages?

const msg = {
  body: "Hello @User, how are you?",
  mentions: [{
    tag: "@User",
    id: "100012345678901",
    fromIndex: 0
  }]
};
api.sendMessage(msg, threadID);

📞 Support

For issues or questions, please open an issue on GitHub or contact the developer.

📝 License

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

Made with ❤️ by Sahil