Additional API

Every command in WhatsBotCord receives three main arguments in its run method: ctx, api, and args (which you can learn more about in the Command Arguments page). While your ctx (our robust Chat Context wrapper) focuses on interacting effortlessly with the exact chat the command was triggered from, the api (AdditionalAPI) provides access to lower-level bot mechanics and global cross-chat capabilities.

export default class MyCommand implements ICommand {
  name = "example";

  // The second argument `api` injected here is the `AdditionalAPI` object
  public async run(ctx: IChatContext, api: AdditionalAPI, args: CommandArgs): Promise<void> {
    // ...
  }
}

Structure of AdditionalAPI

The api object provides powerful submodules:

1. Myself.Status

Allows the bot to post status updates (WhatsApp Stories) directly to its broadcast list.

// Upload a text status visible to the provided specific contacts
await api.Myself.Status.UploadText(
  "Bot is online ✅",
  ["1234567890@s.whatsapp.net"] // WhatsApp IDs that can view your story
);

2. Myself.Bot

Provides read-only access to the minimal bot info. Useful if your command needs to read the current runtime configurations (like api.Myself.Bot.Settings.commandPrefix) or dynamically search other commands in the system.

// Example: Outputting the bot's configured prefixes
const prefixes = api.Myself.Bot.Settings.commandPrefix;
await ctx.SendText(`My configured prefixes are: ${prefixes.join(", ")}`);

// Example: Iterating over all registered commands
const allCommands = api.Myself.Bot.Commands.NormalCommands;
await ctx.SendText(`I have ${allCommands.length} normal commands registered!`);

3. InternalSocket

Direct access to the underlying WhatsApp socket implementation (the Vendor Adapter). Use it to send messages manually or tap into raw events.

⚠️ Caution: Bypassing ChatContext means you are responsible for handling errors, message formatting, and safe sending.

// Example: Send a raw message directly to another group using InternalSocket
const targetGroupId = "123456789@g.us";
await api.InternalSocket.Send.Text(targetGroupId, "Hello from the raw socket!");

---

Global Cross-Chat Actions

Inside a command, your ChatContext is heavily bound to the chat the command was typed in. But what if you want to react to external system events and broadcast messages globally across multiple groups?

The main Bot instance itself exposes direct dispatch components that can be used outside the command flow safely:

• bot.SendMsg
• bot.ReceiveMsg
• bot.InternalSocket

Simple Example: Background Timer

You can use the bot instance globally to send messages when a setTimeout triggers, outside of any command.

import Whatsbotcord, { BaileysAdapter, MsgType } from "whatsbotcord";
import type { AdditionalAPI, IChatContext, ICommand } from "whatsbotcord/types";

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

// Start the bot as usual
await bot.Start();

// Send a message 10 seconds after starting
setTimeout(async () => {
  const targetId = "1234567890@s.whatsapp.net";
  await bot.SendMsg.Text(targetId, "10 seconds have passed since the bot started!");
}, 10000);

With express backend

Imagine you have an external web server (like Express) running alongside your bot. Whenever a specific HTTP endpoint is hit, you want your WhatsApp Bot to automatically alert a specific group.

Because this endpoint is triggered by a web request and is not bound to a user’s ChatContext, you can utilize the Bot instance globally and use bot.SendMsg.

import express from "express";
import type { AdditionalAPI, CommandArgs, IChatContext, ICommand } from "whatsbotcord/types";

export function StartWebhookServer(bot: Bot) {
  const app = express();
  app.use(express.json());

  app.post("/alert", async (req, res) => {
    // Send message to a specific group using the global Bot instance
    await bot.SendMsg.Text("123456789@g.us", `🚨 Alert triggered: ${req.body.message}`);
    res.send("Alert sent to WhatsApp!");
  });

  app.listen(8080, () => console.log("Server listening on port 8080"));
}

When to use bot.SendMsg vs ChatContext?

• Formulating command replies, waiting for a user input, or quoting user messages 👉 Always use ChatContext.
• Broadcasting announcements, triggering cross-chat actions based on external database hooks, WebSockets, or file events 👉 Pass the Bot framework and use bot.SendMsg.