⚡ Koja Project — Facebook Chat API

🚀 A faster, experimental fork of the main Facebook Chat API repo.
⚙️ Expect new features earlier — and possibly a few extra bugs.

🧩 Overview

Koja Project Facebook Chat API is an unofficial API that enables automation for Facebook Messenger by emulating browser behavior.
It performs the same GET and POST requests as the web client — allowing you to interact programmatically with Messenger.

🛑 Disclaimer:
This project is not affiliated with Facebook.
Use responsibly — spammy or automated behavior can result in account bans.
Avoid sending bulk messages, suspicious URLs, or excessive login attempts.

📖 For projects built on top of this API, see Projects Using This API.

📦 Installation

Stable Release

If you just want to use the latest stable version:

npm install github-bot-fca@latest

🧪 Bleeding Edge (GitHub)

Want the newest features (and bugs)? Install directly from GitHub:

npm install github-bot-fca@latest

🧠 Testing Bots Safely

To test bots without risking your main Facebook account, use
👉 Facebook Whitehat Accounts

💡 Example Usage

const login = require("github-bot-fca");

// Simple echo bot
login({ email: "FB_EMAIL", password: "FB_PASSWORD" }, (err, api) => {
  if (err) return console.error(err);

  api.listen((err, message) => {
    api.sendMessage(message.body, message.threadID);
  });
});

🖼️ Example Result:

📚 Documentation

Full documentation available in DOCS.md.

🔧 Main Functionality

✉️ Sending a Message

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

You can send:

• 💬 Regular messages → body: "Hello!"
• 😄 Sticker → sticker: "STICKER_ID"
• 📎 File/Image → attachment: fs.createReadStream("image.jpg")
• 🌐 URL → url: "https://example.com"
• ❤️ Emoji → emoji: "😀", emojiSize: "large"

💡 Tip:
To find your own userID, check your cookies — it’s under c_user.

Example: Basic Message

api.sendMessage("Hey!", "000000000000000");

Example: File Upload

const fs = require("fs");
api.sendMessage({
  body: "Hey!",
  attachment: fs.createReadStream(__dirname + "/image.jpg")
}, "000000000000000");

💾 Saving Sessions

Avoid logging in every time by saving your AppState (cookies, tokens, etc.):

const fs = require("fs");
const login = require("github-bot-fca");

login({ email: "FB_EMAIL", password: "FB_PASSWORD" }, (err, api) => {
  if (err) return console.error(err);
  fs.writeFileSync("appstate.json", JSON.stringify(api.getAppState()));
});

🔁 Or use c3c-fbstate to generate fbstate.json.

👂 Listening to Chats

api.listen(callback)

You can listen for new messages, events, and more.
Enable extra options like event listening or self messages via:

api.setOptions({ listenEvents: true, selfListen: true });

Example: Simple Echo Bot

const fs = require("fs");
const login = require("github-bot-fca");

login({ appState: JSON.parse(fs.readFileSync("appstate.json", "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, () => {});

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

❓ FAQs

1. How do I run tests?
Create test-config.json (like example-config.json) in /test and run:

npm test

2. Why doesn't sendMessage work for pages?
Pages can’t start new conversations — this is a Facebook restriction.

3. login doesn’t work?
Make sure you can log in via browser first.
If you have 2FA, read about handling approvals in login.

4. How do I avoid logging in every time?
Use api.getAppState() and store it in a file to reuse sessions.

5. Can I send messages as a Page?
Yes:

login(credentials, { pageID: "000000000000000" }, (err, api) => { ... });

6. Getting SyntaxError: Unexpected token [?
Update your Node.js — older versions don’t support new syntax.

7. Too much console logging?
Silence logs with:

api.setOptions({ logLevel: "silent" });

🧠 Projects Using This API

• 🧩 c3c — Customizable bot framework supporting Facebook & Discord.
• 🤖 KOJA-PROJECT-bot — A simple Facebook Messenger Bot made by Koja Jutt.

🪪 License & Credits

• 🧠 Original project inspired by the community at facebook-chat-api
• 🧑‍💻 Modified & maintained by the Koja Project Team

⭐ If this project helped you, give it a star on GitHub!

It helps others discover it and keeps the project alive. 💖