🤖 Whatskel

A fast, modular WhatsApp bot built with Go and Lua plugins.

Whatskel is a WhatsApp bot framework that separates its core (Go) from its command logic (Lua), enabling you to create, modify, and deploy new commands without recompiling the binary.

---

✨ Features

Feature	Description
🔌 Dynamic Lua Plugins	Write commands in Lua — no recompilation needed
🔄 Auto-Reconnect	Automatically reconnects on disconnect with exponential backoff
📵 Auto-Reject Calls	Incoming voice/video calls are instantly declined
💬 Reply with Quote	Reply to messages while quoting the original message
😀 Message Reactions	React to messages with emoji
🗑️ Delete Messages	Revoke/delete command messages programmatically
👤 Sender Name Access	Access sender's display name for personalized responses
🏘️ Group Detection	Distinguish between group and private messages
🖼️ Send Image/Sticker	Upload and send images or .webp stickers
📩 Private Messaging	Send messages to arbitrary users by phone number
📥 Media Download Bridge	Download encrypted media (image/video/audio/sticker/document) from messages
🔁 Quoted Media Download	Download media from quoted/replied-to messages
📝 Caption Commands	Trigger commands via image/video/document captions
💾 SQLite Persistence	Session and device data stored locally

📖 Documentation

📚 Read the full Wiki →

The Wiki contains the complete API reference, architecture guide, plugin creation tutorial with examples, configuration details, and troubleshooting FAQ.

🧠 Skills Reference →

A quick cheat-sheet of every ctx property and method with one-liner descriptions.

🚀 Quick Start

Requirements

• Go 1.26.4 or newer

Build from Source

git clone https://github.com/COXKPER/Whatskel.git
cd Whatskel
go build -o whatskel .

Run

./whatskel -config config.toml

On first run, a QR code will be displayed in the terminal. Scan it using your WhatsApp app (Linked Devices) to authenticate the bot.

Using Make

make build   # Build the binary
make run     # Build and run
make clean   # Remove binary and database files

⚙️ Configuration

Edit config.toml to customize the bot:

[bot]
prefix = "."                         # Command prefix
session_path = "whatsapp-session.db"  # Session storage
db_path = "whatsapp-store.db"        # Device store

[plugins]
directory = "plugins"                # Lua plugins directory

🔌 Creating Plugins

Create a .lua file inside the plugins/ directory:

-- plugins/Hello.lua
export("hello", function(ctx)
    ctx:React("👋")
    ctx:ReplyQuote("Hello, " .. ctx.SenderName .. "! 🌍")
end)

That's it! The bot loads all .lua files automatically on startup.

Available Context API:

Properties	Methods
ctx.Message	ctx:Reply(text)
ctx.Sender	ctx:ReplyQuote(text)
ctx.SenderName	ctx:React(emoji)
ctx.Chat	ctx:DeleteMessage()
ctx.Args	ctx:ReplyImage(path, caption)
ctx.Prefix	ctx:ReplySticker(path)
ctx.IsGroup	ctx:SendPrivateMessage(target, text)
ctx.HasMedia	ctx:DownloadMedia()
ctx.HasQuotedMedia	ctx:DownloadQuotedMedia()
ctx.MediaType
ctx.QuotedMediaType

See the Wiki for the full API reference and the Skills for a quick cheat-sheet.

📁 Project Structure

Whatskel/
├── main.go              # Entry point
├── bot/
│   └── bot.go           # WhatsApp client, event handling, context building
├── plugins/
│   ├── loader.go        # Lua VM, UserData metatables, command dispatch
│   └── Menu.lua         # Default commands (menu, ping, echo, greet, info)
├── config/
│   └── config.go        # TOML config parser
├── config.toml          # Bot configuration
├── WIKI.md              # Full API documentation & architecture guide
├── SKILLS.md            # Quick API cheat-sheet
├── LICENSE              # GPLv3
└── .github/
    └── workflows/
        └── release.yml  # Automated cross-platform release builds

📦 Releases

Pre-built binaries for Linux and Windows are available on the Releases page. Each tagged version automatically triggers a GitHub Actions workflow that compiles and publishes the binaries.

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.