Unofficial Facebook Chat API for Node.js - Interact with Facebook Messenger programmatically
npm install @dongdev/fca-unofficial@dongdev/fca-unofficial is the only API that allows you to automate chat functionalities on a user account by emulating the browser. This means:
bash
npm install @dongdev/fca-unofficial@latest
`
Requirements:
- Node.js >= 12.0.0
- Active Facebook account
---
🚀 Quick Start
$3
`javascript
const login = require("@dongdev/fca-unofficial");
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);
});
});
`
$3
`javascript
const login = require("@dongdev/fca-unofficial");
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
`javascript
const login = require("@dongdev/fca-unofficial");
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
$3
Save your login session to avoid re-authentication:
`javascript
const fs = require("fs");
const login = require("@dongdev/fca-unofficial");
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);
}
});
`
$3
Load your saved AppState for faster login:
`javascript
const fs = require("fs");
const login = require("@dongdev/fca-unofficial");
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
$3
`javascript
const fs = require("fs");
const login = require("@dongdev/fca-unofficial");
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;
}
});
}
);
`
$3
Configure listening behavior:
`javascript
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
$3
`javascript
// 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, threadID, callback, forceCustomReaction);
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// 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);
`
$3
`javascript
// Share contact
api.shareContact(contactID, threadID, callback);
`
$3
`javascript
// 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);
`
$3
`javascript
// Logout
api.logout(callback);
// Get app state
api.getAppState();
// Set options
api.setOptions(options);
`
$3
`javascript
// Listen to MQTT events
api.listenMqtt(callback);
`
$3
- 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
---
🛠️ Projects Using This API
Here are some awesome projects built with @dongdev/fca-unofficial:
| Project | Description |
|---------|-------------|
| c3c | Customizable bot with plugins, supports Facebook & Discord |
| Miraiv2 | Simple Facebook Messenger Bot |
| Messer | Command-line messaging for Facebook Messenger |
| messen | Rapidly build Facebook Messenger apps in Node.js |
| Concierge | Highly modular chat bot with built-in package manager |
| Marc Zuckerbot | Facebook chat bot |
| Botyo | Modular bot for group chat rooms |
| matrix-puppet-facebook | Facebook bridge for Matrix |
| Miscord | Easy-to-use Facebook bridge for Discord |
| chat-bridge | Messenger, Telegram and IRC chat bridge |
| Botium | The Selenium for Chatbots |
| Messenger-CLI | Command-line interface for Facebook Messenger |
| BotCore | Tools for writing and managing Facebook Messenger bots |
See more projects...
---
🤝 Contributing
Contributions are welcome! We love your input 💙
How to contribute:
1. 🍴 Fork the repository
2. 🌿 Create a new branch (git checkout -b feature/AmazingFeature)
3. 💾 Commit your changes (git commit -m 'Add some AmazingFeature')
4. 📤 Push to the branch (git push origin feature/AmazingFeature`)