update documentation and remove systemd support

This commit is contained in:
synt-xerror
2026-04-21 11:18:19 -03:00
parent f683496318
commit c12374f86c
18 changed files with 3441 additions and 248 deletions

267
man/man1/manybot-plugin.1 Normal file
View File

@@ -0,0 +1,267 @@
.TH MANYBOT-PLUGIN 1 "April 2026" "ManyBot 2.4.3" "User Commands"
.SH NAME
manybot-plugin \- ManyBot plugin development guide
.SH SYNOPSIS
.B manyplug.json
.I manifest file
.br
.I src/plugins/
.B plugin directory
.SH DESCRIPTION
ManyBot plugins extend the bot's functionality without modifying the core
kernel. The kernel connects to WhatsApp and distributes messages to plugins,
which decide how to respond.
.PP
Each plugin lives in its own folder under
.I src/plugins/
with a
.B manyplug.json
manifest file and an
.B index.js
entry point.
.SH PLUGIN STRUCTURE
.nf
src/plugins/
\(do__ my-plugin/
\(bu__ manyplug.json # Plugin manifest
\(bu__ index.js # Main entry point
\(bu__ locale/ # Translations (optional)
\(bu__ en.json
\(bu__ pt.json
\(bu__ es.json
.fi
.SH MANIFEST (manyplug.json)
Every plugin must include a manifest describing its metadata:
.PP
.nf
{
"name": "my-plugin",
"version": "1.0.0",
"category": "utility",
"service": false,
"dependencies": {
"axios": "^1.6.0"
}
}
.fi
.TP
.B name
Plugin identifier. Must match the folder name.
.TP
.B version
Semantic version (e.g., "1.0.0").
.TP
.B category
Plugin type: \fButility\fR, \fBmedia\fR, \fBgame\fR, \fBhumor\fR, or \fBinfo\fR.
.TP
.B service
\fBtrue\fR for background plugins (schedulers, listeners).
\fBfalse\fR for command/event-triggered plugins.
.TP
.B dependencies
Extra npm packages required. Install with \fBnpm install\fR from project root.
.SH PLUGIN ENTRY POINT
The
.I index.js
file must export a default async function:
.PP
.nf
.B "export default async function ({ msg, api }) {"
// Plugin logic here
.B "}"
.fi
.SS Parameters
.TP
.B msg
Message object containing:
.RS
.IP \(bu 2
\fBbody\fR - Full message text
.IP \(bu 2
\fBargs\fR - Array of message tokens
.IP \(bu 2
\fBtype\fR - Message type: chat, image, video, audio, sticker, ptt, document, location
.IP \(bu 2
\fBsender\fR - Sender ID (NUMBER@c.us or NUMBER@g.us)
.IP \(bu 2
\fBsenderName\fR - Display name
.IP \(bu 2
\fBfromMe\fR - True if bot sent the message
.IP \(bu 2
\fBhasMedia\fR - True if contains media
.IP \(bu 2
\fBhasReply\fR - True if it's a reply
.IP \(bu 2
\fBisGif\fR - True if media is GIF
.IP \(bu 2
\fBtimestamp\fR - Unix timestamp
.IP \(bu 2
\fBis(cmd)\fR - Check if message starts with command
.IP \(bu 2
\fBreply(text)\fR - Reply with quote
.IP \(bu 2
\fBdownloadMedia()\fR - Download media (returns {mimetype, data})
.IP \(bu 2
\fBgetReply()\fR - Get quoted message object
.RE
.TP
.B api
API object containing:
.RS
.IP \(bu 2
\fBsend(text)\fR - Send text message
.IP \(bu 2
\fBsendVideo(path)\fR - Send video file
.IP \(bu 2
\fBsendAudio(path)\fR - Send audio as voice message
.IP \(bu 2
\fBsendImage(path, caption?)\fR - Send image with optional caption
.IP \(bu 2
\fBsendSticker(bufferOrPath)\fR - Send sticker from buffer or file
.IP \(bu 2
\fBgetPlugin(name)\fR - Access another plugin's public API
.IP \(bu 2
\fBchat\fR - Chat info: \fBid\fR, \fBname\fR, \fBisGroup\fR
.IP \(bu 2
\fBlog.info(...), log.warn(...), log.error(...)\fR - Logging methods
.RE
.SH EXAMPLES
.SS Simple Command
.nf
import { CMD_PREFIX } from "../../config.js";
export default async function ({ msg, api }) {
if (!msg.is(CMD_PREFIX + "hi")) return;
await msg.reply("Hello! 👋");
}
.fi
.SS Command with Arguments
.nf
import { CMD_PREFIX } from "../../config.js";
export default async function ({ msg, api }) {
if (!msg.is(CMD_PREFIX + "calc")) return;
const [, a, op, b] = msg.args;
let result;
switch (op) {
case "+": result = Number(a) + Number(b); break;
case "-": result = Number(a) - Number(b); break;
default: return msg.reply("Invalid operator!");
}
await msg.reply(`Result: ${result}`);
}
.fi
.SS Processing Media
.nf
import { CMD_PREFIX } from "../../config.js";
export default async function ({ msg, api }) {
if (!msg.is(CMD_PREFIX + "echo")) return;
if (!msg.hasMedia) {
return msg.reply("Send media with the command!");
}
const media = await msg.downloadMedia();
await api.sendSticker(media.data);
}
.fi
.SS Exposing API to Other Plugins
.nf
// Public API for other plugins
export const api = {
formatDate: (d) => d.toLocaleDateString("en-US"),
wait: (ms) => new Promise(r => setTimeout(r, ms))
};
// Normal plugin logic
export default async function ({ msg }) {
if (msg.is("!ping")) await msg.reply("pong!");
}
.fi
.PP
Used by another plugin:
.nf
export default async function ({ msg, api }) {
const utils = api.getPlugin("utilities");
const date = utils.formatDate(new Date());
await msg.reply(`Today is ${date}`);
}
.fi
.SH TRANSLATIONS
Plugins can include their own translations:
.PP
.nf
import { createPluginI18n } from "../../utils/pluginI18n.js";
const { t } = createPluginI18n(import.meta.url);
export default async function ({ msg }) {
if (!msg.is(CMD_PREFIX + "hello")) return;
await msg.reply(t("greeting", { name: msg.senderName }));
}
.fi
.PP
Locale file (\fIlocale/en.json\fR):
.nf
{
"greeting": "Hello, {{name}}! 👋"
}
.fi
.PP
If the configured locale has no translation file, falls back to \fBen.json\fR.
Use \fB{{variable}}\fR syntax for interpolation.
.SH ENABLING A PLUGIN
Add the plugin folder name to
.I manybot.conf R:
.PP
.nf
PLUGINS=[
many,
figurinha,
my-plugin
]
.fi
.PP
Restart ManyBot to load the plugin.
.SH ERROR HANDLING
If a plugin throws an error, the kernel automatically disables it.
Use try/catch for graceful error handling:
.PP
.nf
export default async function ({ msg, api }) {
try {
const result = await riskyOperation();
await msg.reply(result);
} catch (error) {
api.log.error("Plugin error:", error);
await msg.reply("Oops! Something went wrong.");
}
}
.fi
.SH CONFIGURATION ACCESS
Import settings from the main config:
.PP
.nf
import { CMD_PREFIX, CLIENT_ID, CHATS, PLUGINS } from "../../config.js";
// Custom config values also work
import { MY_API_KEY } from "../../config.js";
.fi
.PP
Add custom values to
.I manybot.conf R:
.nf
MY_API_KEY=secret_key_here
.fi
.SH SEE ALSO
.BR manybot (1),
.BR manyplug (1),
.BR manybot.conf (5)
.SH AUTHOR
Written by synt-xerror.
.SH REPORTING BUGS
Report bugs at: https://github.com/synt-xerror/manybot/issues

171
man/man1/manybot.1 Normal file
View File

@@ -0,0 +1,171 @@
.TH MANYBOT 1 "April 2026" "ManyBot 2.4.3" "User Commands"
.SH NAME
manybot \- local WhatsApp bot with plugin system
.SH SYNOPSIS
.B node
.I ./src/main.js
.br
.B node
.I src/utils/get_id.js
.br
.B bash
.I ./setup
.br
.B bash
.I ./update
.SH DESCRIPTION
ManyBot is a 100%% local WhatsApp bot that operates without relying on the
official WhatsApp API. It uses whatsapp-web.js to connect as a regular
WhatsApp client and provides a modular plugin system for extending functionality.
.PP
The bot supports multiple chats in a single session, runs headless (without
a GUI), and can be configured through a simple configuration file.
.SH COMMANDS
.TP
.B !many
List all available commands from loaded plugins.
.TP
.B !figurinha
Convert images, GIFs, and videos to stickers.
.TP
.B !video \fIURL\fR
Download videos from supported platforms.
.TP
.B !audio \fIURL\fR
Download audio from videos and send as voice message.
.TP
.B !adivinhacao comecar
Start a guessing game (1-100).
.TP
.B !forca comecar
Start a hangman game.
.TP
.B !obrigado
Bot responds with a thank-you message.
.PP
Command prefix can be configured via
.B CMD_PREFIX
in
.IR manybot.conf .
Default is
.BR ! .
.SH CONFIGURATION
ManyBot uses a configuration file
.I manybot.conf
in the project root. Key options:
.TP
.B CLIENT_ID=\fIname\fR
Unique identifier for the bot session. Creates a session/\fIname\fR folder
for authentication data. Default: \fIbot_permanente\fR.
.TP
.B CMD_PREFIX=\fIchar\fR
Character prefixing all commands. Default: \fI!\fR.
.TP
.B LANGUAGE=\fIcode\fR
Bot interface language: \fBen\fR (English), \fBpt\fR (Portuguese), or \fBes\fR (Spanish).
Default: \fBen\fR.
.TP
.B CHATS=[\fIid1\fR, \fIid2\fR, ...]
List of allowed chat IDs. Empty array allows all chats.
Format: \fBnumber@c.us\fR for private chats, \fBnumber@g.us\fR for groups.
.TP
.B PLUGINS=[\fIname1\fR, \fIname2\fR, ...]
List of plugins to load at startup. Each name corresponds to a folder in
.IR src/plugins/ .
.PP
See
.BR manybot.conf (5)
for complete configuration reference.
.SH PLUGINS
Plugins extend ManyBot functionality without modifying the kernel. Each plugin
is a folder under
.I src/plugins/
containing:
.TP
.I index.js
Main plugin file exporting a default async function receiving \fB{ msg, api }\fR.
.TP
.I manyplug.json
Plugin manifest describing name, version, category, service status, and dependencies.
.TP
.I locale/
Optional translation files (\fBen.json\fR, \fBpt.json\fR, \fBes.json\fR).
.PP
Plugins receive two objects:
.TP
.B msg
Message information including \fBbody\fR, \fBargs\fR, \fBtype\fR, \fBsender\fR,
\fBhasMedia\fR, methods \fBis()\fR, \fBreply()\fR, \fBdownloadMedia()\fR.
.TP
.B api
Interaction methods including \fBsend()\fR, \fBsendVideo()\fR, \fBsendAudio()\fR,
\fBsendImage()\fR, \fBsendSticker()\fR, \fBgetPlugin()\fR, and \fBlog\fR methods.
.SH FILES
.TP
.I manybot.conf
Main configuration file. See \fBmanybot.conf(5)\fR.
.TP
.I session/
Authentication data and WhatsApp session storage.
.TP
.I src/plugins/
Plugin directory containing all installed plugins.
.TP
.I src/main.js
Bot entry point.
.TP
.I logs/
Log files directory.
.TP
.I update.log
Update script log output.
.SH ENVIRONMENT
.TP
.B NODE_ENV
Set to \fBproduction\fR to disable development features.
.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
General error
.TP
.B 130
Interrupted by user (Ctrl+C)
.SH EXAMPLES
.SS First run
.nf
$ node ./src/main.js
# Scan QR code with WhatsApp:
# Menu \-> Linked Devices \-> Link a Device
.fi
.SS Get chat IDs
.nf
$ node src/utils/get_id.js
# Send a message in the target chat to see the ID
.fi
.SS Update to latest version
.nf
$ bash ./update
.fi
.SH SECURITY
\(bu Bot runs with same privileges as the user running it
.br
\(bu Session data stored in \fIsession/\fR should be protected (chmod 700)
.br
\(bu CHATS whitelist recommended to limit bot exposure
.br
\(bu No official WhatsApp API keys required or used
.SH SEE ALSO
.BR manybot.conf (5),
.BR manybot-plugin (1),
.BR manyplug (1)
.SH AUTHOR
Written by synt-xerror.
.SH COPYRIGHT
Licensed under GPLv3. See LICENSE file for details.
.br
https://github.com/synt-xerror/manybot
.SH BUGS
Report bugs at: https://github.com/synt-xerror/manybot/issues

225
man/man5/manybot.conf.5 Normal file
View File

@@ -0,0 +1,225 @@
.TH MANYBOT.CONF 5 "April 2026" "ManyBot 2.4.3" "File Formats"
.SH NAME
manybot.conf \- ManyBot configuration file
.SH SYNOPSIS
.I manybot.conf
.SH DESCRIPTION
The
.I manybot.conf
file configures the ManyBot WhatsApp bot. It uses a simple key-value format
with support for multiline lists. Comments start with \fB#\fR.
.PP
The file must be located in the project root directory, alongside
.IR package.json .
.SH FORMAT
.nf
# Comments start with '#'
KEY=value
KEY=[item1, item2, item3]
.fi
.SS Key-Value Pairs
Simple configuration values:
.PP
.nf
CLIENT_ID=my_bot
CMD_PREFIX=!
LANGUAGE=en
.fi
.SS Multiline Lists
Arrays spanning multiple lines:
.PP
.nf
CHATS=[
123456789@c.us,
123456789@g.us
]
PLUGINS=[
many,
figurinha,
audio,
video
]
.fi
.SH OPTIONS
.SS Core Settings
.TP
.B CLIENT_ID=\fIstring\fR
Unique identifier for the bot session.
.RS
.IP \(bu 2
Default: \fBbot_permanente\fR
.IP \(bu 2
Creates a \fIsession/CLIENT_ID/\fR folder for authentication data
.IP \(bu 2
Changing this starts a new session (requires QR code rescan)
.RE
.TP
.B CMD_PREFIX=\fIcharacter\fR
Character that prefixes all bot commands.
.RS
.IP \(bu 2
Default: \fB!\fR
.IP \(bu 2
Example: \fB!\fR makes commands like \fB!video\fR, \fB!audio\fR
.IP \(bu 2
Changing to \fB.\fR would make commands \fB.video\fR, \fB.audio\fR
.RE
.TP
.B LANGUAGE=\fIcode\fR
Bot interface language.
.RS
.IP \(bu 2
Default: \fBen\fR (English)
.IP \(bu 2
Options: \fBen\fR, \fBpt\fR (Portuguese), \fBes\fR (Spanish)
.IP \(bu 2
Fallback to English if selected language not found
.RE
.SS Chat Settings
.TP
.B CHATS=[\fIid1\fR, \fIid2\fR, ...]
Whitelist of chat IDs where the bot responds.
.RS
.IP \(bu 2
Default: \fB[]\fR (empty = respond to all chats)
.IP \(bu 2
Private chat format: \fBnumber@c.us\fR
.IP \(bu 2
Group format: \fBnumber@g.us\fR or \fBnumber-number@g.us\fR
.IP \(bu 2
Use \fBnode src/utils/get_id.js\fR to discover chat IDs
.RE
.SS Plugin Settings
.TP
.B PLUGINS=[\fIname1\fR, \fIname2\fR, ...]
List of plugins to load at startup.
.RS
.IP \(bu 2
Default: \fB[]\fR (no plugins loaded)
.IP \(bu 2
Each name must match a folder in \fIsrc/plugins/\fR
.IP \(bu 2
Order matters: plugins load in listed order
.IP \(bu 2
Comment out or remove to disable without deleting files
.RE
.SS Built-in Plugins
.TP
.B many
Lists all available commands. Required for \fB!many\fR to work.
.TP
.B figurinha
Converts images/GIFs/videos to WhatsApp stickers.
.TP
.B video
Downloads videos from URLs.
.TP
.B audio
Downloads audio from videos as voice messages.
.TP
.B adivinha\(,c\(oao
Guessing game (1-100).
.TP
.B forca
Hangman game.
.TP
.B obrigado
Responds to thank-you messages.
.SH CUSTOM SETTINGS
You can add any custom key-value pairs for use by plugins:
.PP
.nf
# In manybot.conf
ADMIN_NUMBER=5511999999999@c.us
API_KEY=your_secret_key
MAX_DOWNLOAD_SIZE=50MB
.fi
.PP
Access in plugins:
.nf
import { ADMIN_NUMBER, API_KEY, MAX_DOWNLOAD_SIZE } from "../../config.js";
.fi
.SH EXAMPLES
.SS Minimal Configuration
.nf
# Basic bot setup
CLIENT_ID=my_bot
CMD_PREFIX=!
LANGUAGE=en
PLUGINS=[
many
]
.fi
.SS Production Configuration
.nf
# Production bot with whitelist
CLIENT_ID=bot_prod
CMD_PREFIX=/
LANGUAGE=pt
CHATS=[
5511999999999@c.us,
5511888888888-123456789@g.us
]
PLUGINS=[
many,
figurinha,
video,
audio,
obrigado
]
# Custom settings
ADMIN_NUMBER=5511999999999@c.us
LOG_LEVEL=info
.fi
.SS Development Configuration
.nf
# Debug/development setup
CLIENT_ID=bot_dev
CMD_PREFIX=!
LANGUAGE=en
# Respond to all chats
CHATS=[]
# All plugins for testing
PLUGINS=[
many,
figurinha,
video,
audio,
adivinha\(,c\(oao,
forca,
obrigado
]
.fi
.SH FILES
.TP
.I manybot.conf
Main configuration file (must be created by user)
.TP
.I manybot.conf.example
Example configuration with documentation comments
.SH NOTES
\(bu Keys are case-sensitive
.br
\(bu Values are read as strings unless they're list syntax
.br
\(bu Inline comments supported: \fBKEY=value # comment\fR
.br
\(bu Multiline lists must end with \fB]\fR on its own line or last item line
.br
\(bu Whitespace in values is trimmed
.br
\(u Missing optional values use built-in defaults
.SH SEE ALSO
.BR manybot (1),
.BR manybot-plugin (1),
.BR manyplug (1)
.SH AUTHOR
Written by synt-xerror.