WWOLFBOT DOCS

Build, run, and understand WolfBot.

Clear documentation for configuration, WhatsApp connectivity, commands, integrations, deployment, and production troubleshooting.

Read the guides

WolfBot at a glance

WolfBot is a modular WhatsApp automation project. Its runtime starts a Baileys socket, loads commands recursively, connects persistence adapters, and exposes operational status through a built-in web server.

Command-firstFeatures live in focused modules instead of one giant handler.
Deployment-awareReconnects, health checks, hosting detection, and persistence are built in.
Service-readyAI, media, databases, panels, and external APIs are isolated behind helpers.

Start here

Configure the runtimeEnvironment variables, identity, prefixes, and persistence.Use and extend commandsDiscovery, authorization, patterns, and additions.Understand the architectureRuntime flow, libraries, storage, and deployment.Troubleshoot productionMemory, reconnects, logs, APIs, and recovery.

Configuration that survives deployment

Keep secrets in environment variables and treat local JSON files as runtime state. On ephemeral hosts, use PostgreSQL or another persistent store for settings that must survive restarts.

Essential variables

SESSION_ID=WOLF-BOT:your-session-value
BOT_NAME=WOLFBOT
BOT_PREFIX=.
BOT_MODE=public
OWNER_NUMBER=2547XXXXXXXX
APIX_API_KEY=your-api-key
DATABASE_URL=postgres://user:password@host:5432/db

APIX reads APIX_API_KEY first, then WOLVAREX_API_KEY, with a built-in fallback. Users can override it without editing source code.

Deployment checklist

  • Never commit .env, sessions, databases, or uploads.
  • Set production secrets in the host’s secret manager.
  • Use persistent storage for bot state.
  • Keep Node aligned with the project engine.

Command families

Commands are loaded recursively from commands/. Each module exports metadata and an execute function.

FamilyExamplesPurpose
AIgpt, gemini, deepseekText models through APIX with fallbacks.
Mediasong, play, ytmp3Search, resolve, download, and send media.
Groupsantispam, antigroupcallModeration and group automation.
Owneranticall, diskRuntime controls and maintenance.
Utilityplatform, healthDeployment and runtime visibility.

Adding a command

export default { name: 'example', category: 'utility', async execute(sock, message) { await sock.sendMessage(message.key.remoteJid, { text: 'Ready.' }); } };

Architecture

Startup→Config & storage→Baileys socket→Router→Handlers
index.js
Bootstraps the process, socket lifecycle, configuration, and message routing.
lib/
Shared databases, APIs, platform detection, media, menus, logging, and persistence.
commands/
Feature modules grouped by capability.
data/
Runtime settings, caches, and database files.

Troubleshooting production

Memory quota errors

An R14 error means process RSS exceeded the hosting quota. Native modules, buffers, media, caches, and the WhatsApp socket also consume memory. Reduce concurrency and cache retention or use a larger dyno.

AI endpoint failures

Check the key, endpoint status, response shape, and fallback logs. A success response with an empty result is an upstream provider failure.

Connections and sessions

Confirm the session prefix, inspect the first connection error, and avoid multiple processes sharing one session. On ephemeral hosts, restore state from a persistent database or platform secret.

node --check index.js
npm start
# inspect RSS and restart history
# never log secret query strings

Media and examples

Administrators can publish screenshots, recordings, diagrams, and YouTube references. Public visitors see only published items.

Loading media…