Sonic

Sonic WhatsApp bot streamlines group management, enhances user engagement and delivers instant responses at lightning speed. This professional grade bot transforms WhatsApp into a powerful platform for community management and user interaction.

Disclaimer

IMPORTANT: Sonic is provided for educational and personal use purposes only. Please ensure you:

Use responsibly: Do not spam, harass or send unwanted messages to users
Respect privacy: Handle user data with care and respect their privacy
No commercial use: Sonic is not intended for commercial purposes without proper authorization
Legal compliance: Ensure your use complies with local laws and regulations

The developers are not responsible for any misuse of sonic or any consequences arising from its use. Users are solely responsible for their actions and must ensure they have proper consent before adding sonic to groups or sending messages.

Caution

WhatsApp may suspend or ban accounts that violate their terms of service. Use sonic at your own risk.

Why Sonic?

Sonic combines several capabilities into one bot experience:

Group and community management tools for admins
An economy system with balances, work, daily rewards, inventory and leaderboards
Chat utilities such as labels, presence, quick replies and status handling
A modular command architecture that makes it straightforward to add new features

Features

Technical Features

Lightning Fast: Optimized for speed and performance
Modular Design: Easy to extend with new commands
Permission System: Admin-only commands with proper checks
Auto-Save Configuration: Persistent authentication and environment settings
Emoji-Rich Interface: Beautiful, colorful responses

Core capabilities

Group management: add, kick, promote, demote, mute, unmute, invite links, tag-all, group info and admin tools
Newsletter management: follow, unfollow, mute and unmute newsletter, react, admincount and change owner
Economy system: balance, work, beg, daily rewards, deposit, withdraw, pay, inventory, fish, hunt, mine, shop, rob, stats and leaderboards
Gambling and risk games: coinflip, dice, roulette, slots, crash and blackjack for fast mini-game action
Tools and maker features: sticker generation, weather, wiki, search, calculator, image tools, encoding/decoding and utility commands
Owner controls: participant toggles, welcome/goodbye controls, promote/demote toggles and maintenance actions. Owner message toggles currently apply until the bot restarts; persistent toggle configuration is planned.

Prerequisites

Install the following before running Sonic locally:

Windows

Node.js & npm (Download the installer)
Git
Terminal app (built-in)

macOS

Node.js & npm (Download the installer or use Homebrew: brew install node)
Git (or install via Homebrew: brew install git)
Terminal app (built-in)

Linux

Node.js & npm (Follow the official instructions)
Git (Follow the official instructions for your distribution)
Terminal app (built-in)

Verify installation:

node --version
npm --version
git --version

Once these are installed, you can proceed to clone the repository and follow the installation steps below.

Quick Start

1. Clone the repository

git clone https://github.com/xodo2fast4u/sonic-bot.git
cd sonic-bot

2. Install dependencies

npm install

3. Configure environment

# Sonic doesn't create a .env file automatically
# You must create one manually with:
# For Linux And Mac OS
touch .env

# For Windows
> .env

Example:

SONIC_PREFIX=!
OWNER_NUMBER=

4. Run sonic

npm start

5. Connect WhatsApp

Sonic will prompt for your phone number
Enter your number with country code and without the + sign (e.g., 27724913058)
Check your phone for WhatsApp notification to enter pairing code displayed in terminal
You have successfully connected sonic

Configuration

Sonic reads configuration from .env and a built-in config module.

Variable	Description	Default
`SONIC_PREFIX`	Command prefix for bot commands	`!`
`OWNER_NUMBER`	Owner number used for owner-only features	(empty, auto-filled upon successful pairing)

Project structure

The main code lives under src and the folders are organized like this:

Path	Purpose
src/core	Message handling, routing, socket lifecycle, dependency injection and shared state
src/commands	Command implementations grouped by category
src/services	Business logic for user and economy features
src/database	SQLite access, repositories and migrations
src/config	Bot configuration and environment helpers
src/utils	Logging, cooldowns, formatting and shared utilities
src/cache	Session and cache management
src/monitoring	Health checks and metrics collection
src/security	Audit logging and security-related utilities
src/validation	Input validation
src/data	Where Economy Database gets created and lives
types	TypeScript declarations for project dependencies and modules

Command overview

The command registry automatically loads command modules from the category folders in src/commands. The currently implemented command families are:

General: !ping, !info, !menu, !about, !profile, !runtime, !server, !speed, !owner
Economy: !balance, !daily, !work, !beg, !deposit, !withdraw, !pay, !inventory, !transactions, !leaderboard, !shop, !fish, !hunt, !mine, !rob, !stats
Gambling: !coinflip, !dice, !roulette, !slots, !crash, !blackjack, !higherlower
Group: !ginfo, !groupcreate, !grouplist, !tagall, !mute, !unmute, !promote, !demote, !kick, !leave, !link, !groupmode, !join, !admins, !setname, !setdesc, !lock, !unlock, !add, !ephemeral, !revoke, !groupinvite, !grouprequest, !groupv4
Tools: !bible, !calculate, !decode, !define, !directions, !encode, !image, !name, !search, !songrecommendation, !wallpaper, !weather, !wiki
Maker: !sticker, !brat, !hd
Newsletter: !newslettermanage, !newsletteractions
Owner: !participantson, !participantsoff, !promoterdemoteon, !promoterdemoteoff, !welcomegoodbyeon, !welcomegoodbyeoff, !additem, !removeitem, !setbalance, !resetcooldown

Development

Test and lint

Run the full test suite and lint checks locally:

npm test
npm run lint

For the Jest coverage report and configured coverage thresholds run:

npm run test:coverage

Adding a new command

Create a new file in the appropriate folder inside src/commands, such as src/commands/general or src/commands/economy.
Export a command object with cmd, desc, and run.
Keep the logic focused and use the shared helpers for text replies, mentions, reactions, edits, and images.

Example:

import { emoji as e } from '../../config/config.js';

export default {
  cmd: ['hello'],
  desc: 'Greet the bot',
  run: async ({ text }) => {
    await text(`${e.sonic} Hello! I'm Sonic!`);
  },
};

The command loader scans each folder and picks up new files automatically, so adding a new module usually only requires creating the file.

Useful helpers

text(message) sends a plain text reply.
mention(text, mentions) sends a reply with mentions.
react(emoji, key) reacts to a message.
edit(key, text) edits an existing outgoing message.
image(source, caption, mimetype) sends an image message from a URL or buffer. The MIME type is optional.
sticker(buffer) sends a sticker buffer as a quoted sticker message.

Security & Privacy

No Message Storage: Messages are not stored permanently
Owner-Only Commands: Sensitive commands restricted to bot owner
Permission Checks: Proper permission validation for group commands

Important

Phone Number: Use your personal for fun WhatsApp number (not business)
Internet Connection: Stable internet required
Session Persistence: Auth session saved in sonic_session.db file
Rate Limiting: WhatsApp may rate-limit if commands are spammed
Privacy: Bot respects WhatsApp's privacy settings

Deployment Options

Termux (Android)

Run Sonic on your Android device using Termux:

Install Termux from F-Droid or Google Play Store

Update and install dependencies

pkg update && pkg upgrade
pkg install nodejs-lts git clang make python pkg-config

Clone and setup Sonic

git clone https://github.com/xodo2fast4u/sonic-bot.git
cd sonic-bot
npm install
#or
npm i

Build the native SQLite module for Android ARM64 better-sqlite3 uses a native Node addon and must be compiled for Android ARM64 inside Termux:
```
cd node_modules/better-sqlite3
npm run build-release
cd ../..
```
You can verify the native module was created with:
```
ls node_modules/better-sqlite3/build/Release
```
You should see:

better_sqlite3.node

Create and setup .env file

touch .env
printf 'SONIC_PREFIX=!\nOWNER_NUMBER=\n' > .env

Keep Termux active

Before starting Sonic, acquire a wake lock so Android is less likely to suspend the Termux process while you switch to other apps or turn the screen off:
```
termux-wake-lock
```
This helps keep Sonic active while it is running.
Run Sonic
```
npm start
```
Pair WhatsApp as usual

When you no longer need Sonic running, release the wake lock:
```
termux-wake-unlock
```

Recommended:

termux-wake-lock will show a pop-up to disable Android battery optimization for Termux if you intend to keep Sonic running for long periods if the pop-up does not show up, manually disable Android battery optimization for Termux. Android may otherwise suspend or terminate Termux independently of the wake lock.

Cloud hosting

Sonic can also be deployed on services such as Optiklink or similar Node.js hosts. Make sure to:

Upload the repository contents.
Install dependencies with npm install.
Set the required environment variable SONIC_PREFIX.
Start the bot with npm start.

Troubleshooting

Common Issues

Bot doesn't respond

Check if bot is connected (!ping command)
Verify prefix is correct
Ensure bot is in the group (for group commands)

Authentication fails

Delete sonic_session.db and other files named sonic_session
Restart bot and re-authenticate
Check phone number format (include country code)

Commands not working

Verify bot has necessary permissions
Check group admin status for admin commands
Ensure proper command syntax

Performance issues

Check system resources
Restart bot if running for extended periods
Monitor internet connection stability

Contributing

We welcome contributions! Please read our CONTRIBUTING.md guide for detailed information on:

Code style and formatting standards
File organization and naming conventions
How to write tests
Git workflow and commit message guidelines
Security best practices
Performance considerations

Quick start:

Fork the repository
Install dependencies: npm install
Create a feature branch: git checkout -b feature/your-feature
Make your changes and test: npm test
Format and type-check: npm run format && npm run type-check
Submit a pull request

For detailed guidance, see CONTRIBUTING.md.

Support

For issues, questions or contributions:

Create an issue in the repository
Check existing documentation
Review code examples

License

This project is under the MIT License

Made with ❤️ by Xodobyte

Gotta go fast! 🦔💨

FilesExpand file tree

README.md

Latest commit

History