🤖 WA-Bot

A lightweight, production-ready WhatsApp bot built in Go

Dual AI engine · Smart media downloader · Anti view-once · Auto-reply guard · Full group management — compiled into a single static binary.

📦 Download Binary · 📖 Documentation · 🐛 Report Bug · ✨ Request Feature

📋 Table of Contents

About The Project
Architecture & Workflow
Features
System Requirements
Installation
- Ubuntu / Debian 24.04
- Alpine Linux 3.23
Build & Run
- Option A: Compile Binary
- Option B: Download Release
Command Reference
Configuration
CI/CD Auto Release
Contributing
License

🧩 About The Project

WA-Bot is an open-source, self-hosted WhatsApp automation bot written in Go, using the Whatsmeow library for a direct WebSocket connection to WhatsApp — no browser, no Selenium, no third-party bridge.

It is designed for personal use on a low-spec VPS (works on 512 MB RAM), compiles to a single binary with zero runtime dependencies, and ships with a broad feature set covering AI, media downloading, sticker tools, anti view-once, group management, and intelligent auto-reply.

Why WA-Bot over alternatives?

	WA-Bot	Browser-based bots	Paid APIs
No browser required	✅	❌	✅
Single static binary	✅	❌	❌
Self-hosted & private	✅	✅	❌
Open source	✅	varies	❌
RAM usage	~30 MB	~300–600 MB	—
Cross-platform binary	✅ Linux/ARM/Win	❌	—

🏗️ Architecture & Workflow

The diagram below shows the complete message flow — from the moment a user sends a WhatsApp message to when the bot responds.

How it works — step by step:

User sends a message via WhatsApp on their phone or desktop.
Whatsmeow WebSocket receives the raw encrypted protobuf packet from WhatsApp's servers.
EventHandler dispatches the event — either a Message event or a GroupInfo event (for member joins).
GroupInfo path → if a new member joins a group with a welcome config, the bot fires a mention reply after a 1-second delay.
HandleMessage parses the content type (Text, Image, Video, Sticker), runs AFK checks, logs the message, and checks if any mentioned user is AFK.
Decision gate — if the message starts with / or ., it is routed to RunCommand. Otherwise, two parallel async systems are evaluated:
- Auto-Reply System: waits 2 minutes, checks if the owner has already replied, checks the 15-minute cooldown, and if conditions pass, sends the configured auto-reply message.
- GF Mode Guard: if the sender matches the configured target JID and the owner has been inactive for over 3 minutes, the bot generates and sends an AI-powered persona response.
RunCommand Router parses the command string and dispatches to one of six handler groups.
All handlers call b.Reply() or b.Client.SendMessage(), which sends the response back through the WhatsApp WebSocket.

Internal package structure:

Package	Role
`internal/handler`	Core router, all command logic, event dispatch
`internal/config`	Persistent state: auto-reply, GF mode, AFK, favorites, groups
`internal/utils`	AI clients (Gemini/Groq), media converters, JID parser, logger
`cmd/main.go`	Entry point: device setup, QR auth, WebSocket connect

✨ Features

🧠 Dual AI Engine

Seamlessly uses Google Gemini as primary and Groq AI as fallback. If Gemini returns an error, the bot automatically retries with Groq — zero configuration needed. Responds conversationally in Bahasa Indonesia.

📥 Smart Media Downloader

Supports 4 platforms with both video and audio extraction modes. Carousel/gallery posts (multiple files) are fully supported.

Platform	Video	Audio (MP3)	Gallery/Carousel
TikTok	`.tt4`	`.tt3`	✅ Auto
YouTube	`.yt4`	`.yt3`	—
Instagram	`.ig4`	`.ig3`	✅ Auto
Facebook	`.fb4`	`.fb3`	—

TikTok uses the TikWM REST API — no yt-dlp required for TikTok, making it more reliable against rate limiting. YouTube, Instagram, and Facebook use a locally-installed yt-dlp binary, which supports bypass mechanisms and carousel auto-numbering (%(autonumber)s).

🖼️ Media Tools

.s — Convert any image, video, or text into a WhatsApp sticker (WebP)
.brat — Generate a brat-style text sticker instantly
.v — Bypass view-once restriction: re-download and re-upload the media to your chat permanently
.toimg — Convert a replied sticker back to a JPEG image
.togif — Convert a sticker to GIF (sent as a document)
.tovid — Convert a sticker to an MP4 video

Media conversion pipeline: imagemagick handles image/text rendering; ffmpeg handles video encoding, audio extraction, and GIF conversion.

👁️ Anti View-Once

Reply to any view-once photo or video message, then use .v. The bot decrypts the media using Whatsmeow's Client.Download(), re-uploads it, and sends it back to the chat permanently. Works even after the original message has been viewed.

🤖 Smart Auto-Reply

When you have not replied to a private message for 2 minutes, the bot sends a custom message on your behalf. Built-in protections:

Skips if you replied after the message was sent
Per-contact 15-minute cooldown to prevent spam
Fully configurable message via .setrespon

🛡️ GF Mode (AI Persona Guard)

A dedicated surveillance mode for one specific contact. When you are inactive in that chat for over 3 minutes, the bot activates and replies using an AI-generated response with a custom persona name. Features:

10-minute per-reply cooldown
Customizable pet name (.setname)
Reads the incoming message and crafts a contextual reply
Uses Groq if available, falls back to Gemini

👮 Group Administration

Full group management suite — requires the bot account to be an admin:

Kick, promote, or demote members
Delete any message via reply (.del)
Tag all members with mentions (.tagall)
View the full admin/owner list (.role)
Per-group configurable welcome messages for new members (.setwelcome)

💤 AFK System

Set yourself as AFK with .afk [reason]. When anyone mentions you or sends you a message, they receive an automatic notification showing your reason and how long you have been away. Cleared automatically when you send a message.

💻 System Requirements

The bot uses go-sqlite3 for session storage which requires CGO (C compilation at build time). All tools below must be installed on the build host (for compiling) and the runtime host (VPS).

Tool	Purpose	Build	Runtime
Go 1.22+	Compilation	✅	—
gcc / g++	CGO for go-sqlite3	✅	—
libsqlite3-dev	SQLite headers	✅	—
ffmpeg	Video/audio processing, GIF	—	✅
imagemagick	Sticker and text rendering	—	✅
python3	Runtime engine for yt-dlp	—	✅
yt-dlp	YouTube / Instagram / Facebook downloader	—	✅
Fonts (DejaVu / Liberation)	Text sticker rendering	—	✅
tzdata	Timezone for auto-reply timing	—	✅

Pre-built binaries from Releases still require ffmpeg, imagemagick, yt-dlp, and fonts on the runtime server.

📦 Installation

🐧 Ubuntu / Debian (24.04 LTS)

# 1. Update system packages
sudo apt update && sudo apt upgrade -y

# 2. Install all required dependencies in one command
sudo apt install -y golang git gcc g++ libsqlite3-dev \
    ffmpeg imagemagick python3 curl tzdata fonts-dejavu

# 3. Install yt-dlp (always use the latest release binary)
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp \
    -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

# 4. Verify all tools are accessible
go version
ffmpeg -version | head -1
convert --version | head -1
yt-dlp --version

⛰️ Alpine Linux (3.23)

Recommended for Docker or lightweight VPS deployments.

# 1. Update and install all dependencies
apk update && apk upgrade
apk add go git gcc g++ musl-dev sqlite-dev ffmpeg imagemagick \
    python3 curl tzdata font-liberation ttf-dejavu font-noto

# 2. Install yt-dlp
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp \
    -o /usr/local/bin/yt-dlp
chmod a+rx /usr/local/bin/yt-dlp

# 3. Set timezone to WIB (critical for auto-reply 2-minute timer accuracy)
cp /usr/share/zoneinfo/Asia/Jakarta /etc/localtime
echo "Asia/Jakarta" > /etc/timezone

# 4. Verify
yt-dlp --version && ffmpeg -version | head -1

🚀 Build & Run

Option A: Compile Binary (Recommended)

Compiling produces a single binary file. This avoids /tmp memory pressure on constrained servers that can occur when running go run directly.

# 1. Clone the repository
git clone https://github.com/risqinf/wa-bot.git
cd wa-bot

# 2. Download and tidy Go module dependencies
go mod tidy

# 3. Build with CGO enabled (required for go-sqlite3)
CGO_ENABLED=1 go build -ldflags="-s -w" -o wa-bot cmd/main.go

# 4. (Recommended) Run inside a screen session so it persists after SSH disconnect
screen -S wabot
./wa-bot --author "Your Name"

# To reattach later: screen -r wabot
# To detach without stopping: Ctrl+A then D

On first run, a QR code will appear in the terminal. Open WhatsApp on your phone → Linked Devices → Link a device → scan the QR. The authenticated session is saved to session.db (SQLite) and will survive restarts.

Available flags:

Flag	Description	Example
`--author "Name"`	Sets the owner name displayed in `.menu`	`--author "Budi Santoso"`

Option B: Download Pre-Built Release

Download a ready-to-run binary from the Releases page. No Go installation needed.

# Make the binary executable
chmod +x wa-bot-linux-amd64

# Run (with your name)
./wa-bot-linux-amd64 --author "Your Name"

Available targets:

Binary	Architecture	Use case
`wa-bot-linux-amd64`	x86_64	Ubuntu/Debian VPS, most cloud providers
`wa-bot-linux-arm64`	AArch64	Oracle ARM A1, AWS Graviton, Raspberry Pi 4
`wa-bot-windows-amd64.exe`	x86_64	Windows 10/11 64-bit

⚠️ Reminder: even with a pre-built binary, ffmpeg, imagemagick, and yt-dlp must still be installed on the machine for media features to work.

📟 Command Reference

All commands work with either / or . as the prefix (e.g. /ask or .ask).

🧠 AI

Command	Description
`.ask [question]`	Ask Gemini or Groq AI — auto-fallback between engines
`.ai [question]`	Alias for `.ask`

🖼️ Media Tools

Command	Description
`.s`	Send/reply with image, video, or text to create a sticker
`.brat [text]`	Generate a brat-style text sticker
`.v`	Open and re-send a view-once photo or video
`.toimg`	Reply a sticker → convert to JPEG image
`.togif`	Reply a sticker → convert to GIF document
`.tovid`	Reply a sticker → convert to MP4 video

📥 Media Downloader

Command	Description
`.tt4 [url]`	Download TikTok video (no watermark)
`.tt3 [url]`	Download TikTok audio as MP3
`.yt4 [url]`	Download YouTube video (best quality)
`.yt3 [url]`	Download YouTube audio as MP3
`.ig4 [url]`	Download Instagram post, reel, or full carousel
`.ig3 [url]`	Download Instagram audio
`.fb4 [url]`	Download Facebook video
`.fb3 [url]`	Download Facebook audio

⚙️ System

Command	Description
`.ping`	Check bot response speed (ms)
`.info`	Display server specs — CPU, RAM, uptime, Go version
`.afk [reason]`	Set AFK status; cleared automatically when you next message
`.menu` / `.help`	Show the full command dashboard

👮 Group Admin (Requires bot + sender to be group admin)

Command	Description
`.del`	Delete the replied-to message
`.kick @user`	Remove a member from the group
`.promote @user`	Promote a member to admin
`.demote @user`	Demote an admin back to member
`.admin @user`	Alias for `.promote`
`.tagall`	Mention every member in the group
`.role`	List all group admins and the owner
`.setwelcome [message]`	Set a welcome message (use `{user}` for a mention)
`.setwelcome on`	Enable the welcome message
`.setwelcome off`	Disable the welcome message

🔐 Owner Only (Message must originate from your own device)

Command	Description
`.setrespon [message]`	Set and activate the auto-reply message
`.setrespon on`	Enable auto-reply without changing the message
`.setrespon off`	Disable auto-reply
`.setstatus on`	Activate GF Mode surveillance
`.setstatus off`	Deactivate GF Mode
`.setgf`	Set the GF Mode target contact (reply the person's message or tag them)
`.setname [name]`	Set the pet name used in GF Mode AI responses
`.debug`	Toggle raw protobuf logging to the VPS terminal

⚙️ Configuration

All configuration is stored as plain JSON files in the working directory, created automatically on first run. You can edit them directly or use the bot commands.

File	Contents
`config.json`	Bot name, Gemini API key, Groq API key
`autorespon.json`	Auto-reply message text and enabled state
`status.json`	GF Mode: target JID, pet name, last-reply timestamps
`favorites.json`	Per-user waifu/husbu name lists
`group.json`	Per-group welcome message and enabled flag
`session.db`	WhatsApp session (SQLite). Do not delete — requires re-scanning QR.

config.json example:

{
  "name": "MyBot",
  "gemini_token": "AIzaSy...",
  "groq_token": "gsk_..."
}

Where to get API keys:

Service	URL
Google Gemini	https://aistudio.google.com/app/apikey
Groq	https://console.groq.com/keys

Both keys are optional — the bot works with just one. If both are configured, Gemini is used first and Groq serves as the automatic fallback.

🔄 CI/CD & Auto Release

This repository includes a fully automated GitHub Actions pipeline at .github/workflows/release.yml. Every push of a tag starting with v triggers:

Cross-compilation for linux/amd64, linux/arm64, and windows/amd64
Binary size optimization with -ldflags="-s -w" (strips debug symbols)
Automatic creation of a GitHub Release with all three binaries attached and auto-generated release notes

Triggering a release:

# 1. Commit and push your latest changes
git add .
git commit -m "feat: describe your changes"
git push origin main

# 2. Create a semantic version tag (must start with 'v')
git tag v1.0.1

# 3. Push the tag — this triggers the GitHub Actions workflow
git push origin v1.0.1

After a few minutes, visit the Releases tab to find the compiled binaries ready to download.

🤝 Contributing

Contributions, bug reports, and feature suggestions are always welcome.

To contribute code:

# 1. Fork the repository on GitHub

# 2. Create a descriptively named feature branch
git checkout -b feat/my-new-feature

# 3. Make your changes, then verify the build is clean
go build ./...

# 4. Commit with a clear message
git commit -m "feat: add my new feature"

# 5. Push and open a Pull Request
git push origin feat/my-new-feature

Code guidelines:

All Go source files must use straight quotes " — never curly/smart quotes (" "), which break the Go compiler
Run go build ./... before submitting to confirm there are no errors
Follow the existing package structure: handler, config, utils
Keep command handlers in RunCommand's switch/case block

To report a bug, please open an Issue and include:

Your OS and architecture
The exact command that failed
The error message or unexpected behavior

📄 License

Distributed under the MIT License — you are free to use, modify, and distribute this project with attribution.

See LICENSE for the full license text.

Made with ❤️ by risqinf

If this project helped you, consider giving it a ⭐ star on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.md.0		README.md.0
go.mod		go.mod

Folders and files

Latest commit

History

Repository files navigation

🤖 WA-Bot

A lightweight, production-ready WhatsApp bot built in Go

📋 Table of Contents

🧩 About The Project

🏗️ Architecture & Workflow

✨ Features

🧠 Dual AI Engine

📥 Smart Media Downloader

🖼️ Media Tools

👁️ Anti View-Once

🤖 Smart Auto-Reply

🛡️ GF Mode (AI Persona Guard)

👮 Group Administration

💤 AFK System

💻 System Requirements

📦 Installation

🐧 Ubuntu / Debian (24.04 LTS)

⛰️ Alpine Linux (3.23)

🚀 Build & Run

Option A: Compile Binary (Recommended)

Option B: Download Pre-Built Release

📟 Command Reference

🧠 AI

🖼️ Media Tools

📥 Media Downloader

⚙️ System

👮 Group Admin (Requires bot + sender to be group admin)

🔐 Owner Only (Message must originate from your own device)

⚙️ Configuration

🔄 CI/CD & Auto Release

🤝 Contributing

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages