Bituin-FCA

Advanced Facebook Chat API library for Node.js/TypeScript. A modern, feature-rich alternative to facebook-chat-api with enhanced security, anti-ban measures, and comprehensive Messenger functionality.

Core Features

• Multiple Authentication Methods - Email/password, session import, and account.txt support
• Real-time Messaging - MQTT WebSocket for instant message delivery
• GraphQL API - Full Facebook GraphQL integration
• File Uploads - Images, videos, audio, files, and stickers
• Anti-Ban System - Intelligent rate limiting, fingerprint rotation, human-like behavior
• Custom Command System - Build your own bot commands with cooldowns and permissions
• Plugin System - Extensible plugin architecture

Advanced Features

• Sticker & Custom Emoji - Send stickers and custom emojis
• Thread Themes - Customize thread colors and themes
• Message Translation - Translate messages to 30+ languages
• Analytics Dashboard - Real-time bot analytics
• Cross-Platform Notifications - Discord, Telegram, Slack webhooks
• Email Digests - Daily/weekly message summaries
• AI Features - Smart replies, sentiment analysis, spam detection
• Call Integration - Voice/video call detection and management
• Location Sharing - Share and receive locations
• Polls - Create and manage polls
• Stories - View and interact with stories
• E2E Encryption - End-to-end message encryption

Anti-Detection Suite

• FingerprintManager - Session fingerprint management with 6hr auto-rotation
• RequestObfuscator - Multi-layer request obfuscation with entropy injection
• PatternDiffuser - Adaptive delays to prevent detectable patterns
• TrafficAnalysisResistance - Timing jitter and traffic variability
• SmartRateLimiter - Intelligent message pacing with anti-ban integration
• MQTTProtection - Obfuscated MQTT traffic with keep-alive
• DeviceIDGenerator - Realistic device IDs from system hardware
• UserAgentRotator - Latest Chrome/Edge configurations with rotation
• AutoCookieRefresh - Fresh cookies every 20min + MQTT keep-alive every 30s

Social Interaction Features

• MessageEditor - Edit bot's messages in-place
• PostInteractionManager - Comment and reply to public Facebook posts
• FollowManager - Follow/unfollow users automation
• ProxyManager - Full proxy support with testing utilities

Group & Private Message Management

• GroupChatManager - Welcome/leave messages, announcements, moderation, warnings, muting
• PrivateMessageManager - Quick replies, templates, auto-responses, conversation tracking
• MessengerBotManager - Multi-prefix commands, permissions, scheduled messages, anti-spam

Bot Utility Suite

• MessageScheduler - Schedule messages for future delivery (one-time or recurring)
• AutoModerator - Automatic moderation with word filters, spam detection, warnings, muting
• ConversationLogger - Log and analyze conversations with search, stats, and export
• BotStatistics - Comprehensive analytics (messages, commands, users, uptime, leaderboards)
• ResponseTemplateManager - Reusable response templates with variable substitution
• WebhookNotifier - Send notifications to Discord, Slack, Telegram webhooks
• CommandCooldownManager - Advanced cooldown system per user/thread with bypass options
• UserPermissionSystem - Role-based permissions with inheritance and granular control

Installation

npm install bituin-fca

or

yarn add bituin-fca

Quick Start

Using account.txt (Recommended)

import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA({
  appStatePath: 'account.txt',
  commandPrefix: '!',
  enableAntiBan: true
});

// Login with account.txt
await bot.loginWithAppState();

// Listen for messages
bot.on('message', (msg) => {
  console.log(`${msg.senderID}: ${msg.body}`);
});

// Send a message
await bot.sendMessage({
  threadID: '123456789',
  message: 'Hello from Bituin-FCA!'
});

Using Email/Password

import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA();

// Login with credentials
const success = await bot.loginWithEmail('[email protected]', 'password');

if (success) {
  // Save session as account.txt for future use
  await bot.saveAppState();
}

Using Session Import

import { BituinFCA } from 'bituin-fca';

const bot = new BituinFCA();

// Import base64-encoded session
await bot.loginWithSession(base64SessionData);

account.txt Format

The account.txt file uses a clean, minimal cookie format:

[
  {
    "key": "dbln",
    "value": "",
    "domain": ".facebook.com",
    "path": "/login/device-based/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "datr",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "sb",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "c_user",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "xs",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "vpd",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "ps_l",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "ps_n",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "pas",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "wl_cbv",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "fbl_st",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "wd",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "fr",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  },
  {
    "key": "presence",
    "value": "",
    "domain": ".facebook.com",
    "path": "/",
    "hostOnly": false,
    "expires": "",
    "creation": "",
    "lastAccessed": ""
  }
]

Essential Cookies

Only these cookies are required for authentication:

• c_user - Your Facebook user ID
• xs - Session token

Recommended Cookies

For better functionality, include:

• datr - Browser tracking cookie
• sb - Session cookie

Optional Cookies

Additional cookies like fr, locale, wd, presence, vpd, fbl_st, wl_cbv, pas, ps_l, ps_n may improve stability.

Creating Custom Commands

Bituin-FCA provides a flexible command system. Create your own custom commands by adding files to your src/commands directory:

// src/commands/hello.ts
import { Command } from 'bituin-fca';

export const command: Command = {
  name: 'hello',
  description: 'Say hello to the user',
  usage: '!hello [name]',
  cooldown: 3000, // 3 seconds cooldown
  
  async execute(ctx, args) {
    const name = args[0] || 'there';
    await ctx.sendMessage({
      threadID: ctx.message.threadID,
      message: `Hello, ${name}!`
    });
  }
};

Configuration

interface BituinFCAConfig {
  sessionPath?: string;      // Path to account file (default: 'account.txt')
  appStatePath?: string;     // Path to account file (default: 'account.txt')
  encryptionKey?: string;    // Key for encrypting session/appstate
  commandPrefix?: string;    // Command prefix (default: '!')
  enableAntiBan?: boolean;   // Enable anti-ban measures (default: true)
  enablePlugins?: boolean;   // Enable plugin system (default: true)
  enableCommands?: boolean;  // Enable command system (default: true)
}

Documentation

• Full API Documentation
• Examples
• Migration Guide
• Plugin Development
• Command Creation
• Changelog

Anti-Ban Features

Bituin-FCA includes comprehensive anti-ban measures:

• Request Throttling - Intelligent delays between requests
• User-Agent Rotation - Realistic browser fingerprints
• Human Simulation - Random delays and patterns
• Checkpoint Detection - Automatic handling of security checks
• Health Monitoring - Track account health score
• Automatic Cooldown - Reduce activity when suspicious

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

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

Disclaimer

This is NOT an official Facebook API. Using unofficial APIs may violate Facebook's Terms of Service. Use at your own risk. This library is for educational purposes only.

Salamat / Thank You / Acknowledgments

Maraming salamat sa lahat ng nag-contribute at gumamit ng Bituin-FCA!

• Inspired by facebook-chat-api and fca-unofficial
• Salamat sa mga early adopters at testers ng library
• Salamat sa Filipino developer community para sa support
• Built with TypeScript for type safety
• Uses modern Node.js features

Special thanks to:

• Schmavery - Original facebook-chat-api creator
• lequanglam - fca-unofficial maintainer
• @dongdev - fca-unofficial inspiration
• Filipino Bot Developers Community - Continuous feedback and support
• All Contributors - Everyone who submitted issues, PRs, and suggestions

Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Changelog
• Security Policy

Support

• GitHub Issues
• GitHub Discussions

Made with love by Nazzel Development