The Bot Instance

The Bot (or Whatsbotcord) instance is the absolute core of your application. It manages the underlying WhatsApp socket connection, orchestrates the middleware pipeline, handles incoming events, and serves as the registry for all your commands.

---

Minimal Initialization

To get your bot up and running, you only need to instantiate it and call .Start().

Note

Even though this code starts the bot and connects it to WhatsApp, it won’t actually do anything when users message it yet! The bot relies entirely on commands and event listeners to interact.

To learn how to create your first command, check out the Quick Start guide or explore the Guides & Tutorials section.

TypeScript

import Whatsbotcord, { BaileysAdapter } from "whatsbotcord";

const bot = new Whatsbotcord({
  commandPrefix: "!",
});

await bot.Start();

JavaScript

import Whatsbotcord, { BaileysAdapter } from "whatsbotcord";

const bot = new Whatsbotcord({
  commandPrefix: "!",
});

await bot.Start();

---

Core Components

The Bot instance exposes several powerful modules that you will use to shape your application.

• bot.Commands: The built-in command registry. Use bot.Commands.Add(myCommand) to register new commands.
• bot.Use(...): The middleware pipeline manager. You can seamlessly intercept messages before they reach commands or apply official plugins.
• bot.Events: The global event emitter. Subscribe to socket events or command lifecycle hooks.
• bot.Settings: Access or mutate the bot’s runtime settings dynamically.

Here is an example demonstrating how these core components fit together:

import Whatsbotcord, { BaileysAdapter, CommandType, OfficialPlugin_OneCommandPerUserAtATime } from "whatsbotcord";
import { PingCommand, SendPrivately } from "./commands";

const bot = new Whatsbotcord({
  commandPrefix: ["!", "/"],
});

// 1. Add Commands
bot.Commands.Add(new PingCommand(), CommandType.Normal);
bot.Commands.Add(new SendPrivately(), CommandType.Normal);

// 2. Use Middleware & Plugins
bot.Use(
  OfficialPlugin_OneCommandPerUserAtATime({
    msgToSend: (info, lastCommand, actualCommand) => {
      return `You ${info.pushName} have already started command !${lastCommand.name}, you can't use !${actualCommand.name} yet.`;
    },
    timeoutSecondsToForgetThem: 60 * 5,
  })
);

// 3. Mutate Runtime Settings dynamically
bot.Settings.defaultEmojiToSendReactionOnFailureCommand = "🦊";

// 4. Start the bot
await bot.Start();

---

Configuration Reference

The Bot constructor accepts an extensive set of configuration properties to fine-tune prefixes, connection throttling, error handling, interactive prompt defaults, and more.

Here is an example of a bot initialized with custom configuration values:

import Whatsbotcord, { BaileysAdapter } from "whatsbotcord";

const bot = new Whatsbotcord({
  commandPrefix: ["$", "!", "/", "."],
  tagPrefix: ["@"],
  delayMilisecondsBetweenMsgs: 1,
  cancelKeywords: ["cancelcustom"],
  defaultEmojiToSendReactionOnFailureCommand: "🦊",
}, new BaileysAdapter({
  credentialsFolder: process.env.NODE_ENV === "development" ? "auth_canary" : "./auth",
  loggerMode: "recommended",
}));

The adapter is optional, if you do not provide any, it will use BaileysAdapter by default. You would only use it if you need to custom, the credentialsFodler, loggermode etc…

Basic Options

The main options you should always set or at least be aware of.

Property	Type	Default	Description
commandPrefix	string | string[]	'!'	Character(s) used to prefix commands. Configure multiple prefixes with an array (e.g. ['!', '/']).
tagPrefix	string | string[]	'@'	Character(s) used to tag the bot in messages (especially useful in group contexts).
ignoreSelfMessage	boolean	true	If true, the bot ignores messages sent by its own account to prevent infinite loops.

Caution

The credentialsFolder and loggerMode options have been moved to the WhatsApp Adapter (such as BaileysAdapter). To customize them, pass a configured adapter as the second argument to the Whatsbotcord constructor:

import Whatsbotcord, { BaileysAdapter } from "whatsbotcord";

const bot = new Whatsbotcord({
  commandPrefix: "!",
}, new BaileysAdapter({
  credentialsFolder: "./auth",
  loggerMode: "recommended"
}));

Connection & Throttling Options

Tweak these options if you experience high concurrency messaging or encounter problems with WhatsApp rate-limiting your bot.

Property	Type	Default	Description
maxReconnectionRetries	number	5	Maximum number of reconnection attempts if the socket drops unexpectedly.
senderQueueMaxLimit	number	20	Maximum number of messages queued globally. Buffers pending output to avoid dropping messages.
delayMilisecondsBetweenMsgs	number	100	Delay between sending queued messages to prevent spamming/flooding the WhatsApp API.

Command Error Handling

Configure how the bot reacts when a command crashes or throws an unhandled exception.

Tip

Keeping enableCommandSafeNet enabled is highly recommended for production to prevent your entire script from fatally crashing if a single command errors out.

Property	Type	Default	Description
enableCommandSafeNet	boolean	true	Caught internal errors won’t crash the entire bot.
defaultEmojiToSendReactionOnFailureCommand	string | null	undefined	Emoji to react with on the triggering message if a command fails unexpectedly (e.g. "⚠️" or "❌").
sendErrorToChatOnFailureCommand_debug	boolean	false	Sends a JSON representation of the caught error to the chat. Excellent for real-time debugging!

Context & Interaction Defaults

These defaults define the behavior of ChatContext methods like WaitYesOrNoAnswer(). Setting them here saves you from configuring them manually on every command.

Property	Type	Default	Description
cancelKeywords	string[]	Varies	Words that correctly cancel a running command or interactive prompt.
positiveAnswerOptions	string[]	Varies	Keywords interpreted as an affirmative (“yes”) response in WaitYesOrNoAnswer (case-insensitive).
negativeAnswerOptions	string[]	Varies	Keywords interpreted as a negative (“no”) response in WaitYesOrNoAnswer (case-insensitive).
timeoutSeconds	number	30	Default time limit for awaiting user input during interactive commands.

Advanced Injection (Testing)

These options are primarily intended for maintainers or advanced users writing automated integration tests. Incorrect usage can break the bot’s standard behavior.

Property	Type	Description
ownWhatsSocketImplementation_Internal	IWhatsSocket	Replaces the built-in WhatsApp socket implementation.
ownChatContextCreationHook_Internal	() => IChatContext | null	Replaces the default ChatContext that is sent to all commands.