libie

Modern WhatsApp Bot Framework built on Baileys

Built on Baileys • Powered by Bun Runtime • Written in JavaScript

🚀 Overview

libie is an enterprise-ready WhatsApp bot framework designed for developers who demand performance, reliability, and scalability. Built with modern technologies and battle-tested architecture patterns.

🏗️ Architecture Overview

graph TD
    A[WhatsApp Messages<br/><sub>User Input Stream</sub>] -->|WebSocket Connection<br/>TLS 1.3| B[Baileys Client<br/><sub>Multi-Device Protocol</sub>]
    B --> C[Message Handler<br/><sub>Middleware Processor</sub>]
    C --> D{Command Parser<br/><sub>Pattern Matching</sub>}
    D -->|Valid Command| E[Plugin Manager<br/><sub>Registry & Loader</sub>]
    D -->|System Message| F[System Handler<br/><sub>Internal Processing</sub>]
    D -->|Media Content| G[Media Processor<br/><sub>Encoding/Decoding</sub>]

    E --> H((Plugin Executor<br/><sub>Runtime Sandbox</sub>))
    H --> I[Response Handler<br/><sub>Output Formatter</sub>]
    F --> I
    G --> I

    C --> J[Database Layer<br/><sub>Persistence Store</sub>]
    J --> K[(SQLite Auth<br/>Session Storage)]
    J --> L[(SQLite Data<br/>User Data)]
    J --> M[(SQLite Cache<br/>Temporary Store)]

    E --> N[Dynamic Plugin Loader<br/><sub>Hot Reload System</sub>]
    N --> O[Plugin Registry<br/><sub>Version Control</sub>]
    N --> P[Permission Manager<br/><sub>Access Control</sub>]

    I -->|Send Response| B

    style A fill:#e3f2fd,stroke:#2196f3,stroke-width:3px,color:#0d47a1
    style B fill:#e8f5e9,stroke:#4caf50,stroke-width:3px,color:#1b5e20
    style C fill:#fff3e0,stroke:#ff9800,stroke-width:3px,color:#e65100
    style D fill:#f5f5f5,stroke:#616161,stroke-width:2px,color:#424242
    style E fill:#f3e5f5,stroke:#9c27b0,stroke-width:3px,color:#4a148c
    style F fill:#e8eaf6,stroke:#3f51b5,stroke-width:3px,color:#1a237e
    style G fill:#e0f2f1,stroke:#00695c,stroke-width:3px,color:#004d40
    style H fill:#fff8e1,stroke:#ff8f00,stroke-width:3px,color:#ff6f00
    style I fill:#fce4ec,stroke:#e91e63,stroke-width:3px,color:#880e4f
    style J fill:#efebe9,stroke:#795548,stroke-width:3px,color:#3e2723
    style K fill:#d7ccc8,stroke:#5d4037,stroke-width:2px,color:#3e2723
    style L fill:#d7ccc8,stroke:#5d4037,stroke-width:2px,color:#3e2723
    style M fill:#d7ccc8,stroke:#5d4037,stroke-width:2px,color:#3e2723
    style N fill:#ffecb3,stroke:#ffa000,stroke-width:3px,color:#ff6f00
    style O fill:#ffecb3,stroke:#ffa000,stroke-width:2px,color:#ff6f00
    style P fill:#ffecb3,stroke:#ffa000,stroke-width:2px,color:#ff6f00

    linkStyle default stroke:#666,stroke-width:2px
    linkStyle 0 stroke:#2196f3,stroke-width:3px
    linkStyle 13 stroke:#e91e63,stroke-width:3px

Loading

✨ Key Features

⚡ Performance Ultra-fast Bun runtime 3x faster than Node.js Minimal dependencies	🎯 Architecture ESM-first design Plugin-based system Clean codebase	💾 Database Native bun:sqlite No external services Lightweight storage
🌐 Deployment Server ready Container support Pterodactyl compatible	🎨 Rich Media Interactive buttons Carousels & albums Stories support	🔐 Security Pairing code auth Owner-only commands Command blocking

Message Flow

sequenceDiagram
    participant U as User
    participant WA as WhatsApp Server
    participant B as Baileys Client
    participant H as Message Handler
    participant P as Plugin System
    participant DB as Database
    participant C as Cache

    U->>WA: Send Message
    WA->>B: WebSocket Event
    B->>H: Parse Message
    H->>C: Check Rate Limit
    C-->>H: Allow/Deny
    H->>DB: Validate Session
    DB-->>H: Session Data
    H->>DB: Check Permissions
    DB-->>H: Permission Level
    H->>H: Match Command
    H->>P: Execute Plugin
    P->>DB: Query Data
    DB-->>P: Result Set
    P->>P: Process Logic
    P->>H: Response Data
    H->>B: Format Message
    B->>WA: Send Response
    WA->>U: Deliver Message

Loading

⚡ Quick Start

For detailed installation instructions, see INSTALLATION.md

Automated Installation for Linux (Ubuntu/Debian)

curl -fsSL https://raw.githubusercontent.com/darrma23/libie/main/install.sh | bash

Post-installation:

bot config  # Configure settings
bot start   # Start the bot
bot log     # View logs
bot status  # Check status

Manual Installation

See INSTALLATION.md for comprehensive manual installation guide.

⚙️ Configuration

Environment Setup

Edit .env with your configuration:

# Staff Configuration (WhatsApp LIDs)
OWNERS=["1234567890","1234567890"]

# Pairing Configuration
PAIRING_NUMBER=1234567890
PAIRING_CODE=LIBIEBOT

# Bot Metadata
WATERMARK=libie
AUTHOR=Himejima
THUMBNAIL_URL=https://files.catbox.moe/kn1jtb.jpg

# Logger Configuration
LOG_LEVEL=info
LOG_PRETTY=true
BAILEYS_LOG_LEVEL=silent

Important Notes:

• Use WhatsApp LIDs (Local IDs), not phone numbers for OWNERS
• PAIRING_NUMBER must be in international format without + or spaces
• PAIRING_CODE should be 8 alphanumeric characters (auto-generated if empty)

Pairing Your Device

1. Run the bot: bun start
2. Open WhatsApp on your phone
3. Go to Linked Devices > Link a Device
4. Enter the pairing code displayed in console
5. Done! Your bot is now connected

🎮 Usage

Command Prefixes

libie supports multiple prefixes:

.menu    # Dot prefix
!menu    # Exclamation
/menu    # Slash

Built-in Commands

Command	Description	Example
.menu / .help	Display command menu	.menu
.ping	Check bot latency	.ping

Interacting with the Bot

• Main Menu: Send .menu or .help
• Category Menu: Select category from button menu
• Direct Command: Use prefix + command name

🔌 Plugin System

Plugin Structure

src/plugins/
├── info/              # Information commands
│   └── info-ping.js
├── owner/             # Owner-only commands
│   ├── owner-sf.js    # Save file
│   ├── owner-df.js    # Delete file
│   ├── owner-gf.js    # Get file
│   └── owner-reload.js
├── group/             # Group management
├── downloader/        # Media downloaders
├── ai/                # AI features
└── tool/              # Utility tools

Creating a Basic Plugin

Create a file in /src/plugins/[category]/[name].js:

/**
 * @file Ping command handler
 * @module plugins/info/ping
 * @license Apache-2.0
 * @author Himejima
 */

let handler = async (m, { conn }) => {
    const start = Bun.nanoseconds();
    const msg = await conn.sendMessage(m.chat, { text: "⏱️ Checking..." });
    const ns = Bun.nanoseconds() - start;
    const ms = (ns / 1_000_000).toFixed(0);

    await conn.sendMessage(m.chat, {
        text: `🏓 Pong! ${ms} ms`,
        edit: msg.key,
    });
};

handler.help = ["ping"];
handler.tags = ["info"];
handler.command = /^(ping)$/i;

export default handler;

Plugin Properties

• handler.help - Command names for help menu
• handler.tags - Category tags
• handler.command - RegExp pattern for command matching
• handler.owner - Owner-only command (optional)
• handler.premium - Premium-only command (optional)
• handler.group - Group-only command (optional)
• handler.admin - Admin-only command (optional)

Learn More

• PLUGINS.md - Complete plugin development guide
• BUTTONS.md - Interactive buttons & rich media
• API.md - API integration & utilities

🚀 Production Deployment

Using PM2

# Install PM2
npm install -g pm2

# Start bot
pm2 start ecosystem.config.js

# Save configuration
pm2 save

# Enable startup
pm2 startup

# Monitor
pm2 monit

Using Systemd

Service file auto-created by installer at /etc/systemd/system/libie.service

sudo systemctl start libie
sudo systemctl enable libie
sudo systemctl status libie

📚 Documentation

• INSTALLATION.md - Detailed installation guide
• PLUGINS.md - Plugin development guide
• BUTTONS.md - Interactive buttons & carousels
• API.md - API utilities & helpers
• Contributing Guidelines - How to contribute
• Security Policy - Report vulnerabilities
• Code of Conduct - Community standards

🤝 Contributing

Contributions are welcome! 💖

See CONTRIBUTING.md for details.

💬 Community

Join our growing community!

💭 WhatsApp Group Ask questions, share ideas, and get help from community

📡 Baileys Community Official Baileys developer hub on Discord

🔒 Security

Report vulnerabilities to: libie.bot.official@gmail.com

Warning

DO NOT report security issues through public GitHub issues.

See SECURITY.md for our security policy.

📄 License

Licensed under the Apache License 2.0. See LICENSE for full details.

Caution

Removing copyright notices or claiming original authorship violates the license and may result in legal action.

💖 Acknowledgments

Built with passion by developers, for developers

Core Technologies

Development Tools

Community & Contributors

• 💚 All contributors who made this possible
• 🌍 The amazing open-source community
• ⭐ Everyone who starred this repository
• 🐛 Bug reporters and feature requesters

📊 RepoBeats Analytics

🌟 Star History

---

Maintained by the libie community || © 2024 - 2026 Himejima