plugin

Plugin Development Guide

This guide explains how to create your own plugins for the Levanter WhatsApp Bot.

Basic Template

To create a new plugin, create a .js file in the gist.

const { bot, lang } = require('../lib/');

bot(
  {
    pattern: 'mycommand ?(.*)', // Command pattern (RegEx support)
    desc: 'Description of what this command does',
    type: 'misc', // Category for help menu
    onlyGroup: false, // If true, can only be used in groups
  },
  async (message, match, ctx) => {
    // 'message' is an instance of the Message class
    // 'match' is the text after the command
    // 'ctx' (context) contains session data like env, commands, etc.
    
    await message.send('Hello from my new plugin!');
  }
);

The Callback Parameters

• message: An instance of the Message class, used for interacting with the current chat.
• match: The text captured after the command (e.g., for reminder dinner, match is dinner).
• ctx: The session context object. Useful for accessing env (session-specific variables).

Use Cases for ctx

The ctx object provides deep access to the bot's current state and session.

1. Accessing Session-Specific Environment Variables

Even if a variable isn't in config.js, if it exists in your .env or session environment, you can access it.

bot({ pattern: 'myenv' }, async (message, match, ctx) => {
    const myVar = ctx.env.MY_CUSTOM_VAR || 'Not Set';
    await message.send(`Value: ${myVar}`);
});

2. Retrieving Bot Information

You can access the bot's prefix, command list, or other session metadata.

bot({ pattern: 'botinfo' }, async (message, match, ctx) => {
    const prefix = ctx.PREFIX;
    const totalCommands = ctx.commands.length;
    await message.send(`Prefix: ${prefix}\nTotal Commands: ${totalCommands}`);
});

The Message Object

The message object is the primary interface for interacting with WhatsApp. Below is a comprehensive list of its properties and methods.

Properties

Property	Description
message.jid	The JID of the current chat (user or group).
message.id	The bot session id.
message.participant	The JID of the user who sent the message.
message.text	The full text of the incoming message.
message.pushName	The sender's WhatsApp push name.
message.fromMe	true if the message was sent by the bot itself.
message.isGroup	true if the current chat is a group.
message.sudo	true if the sender is a recognized SUDO user.
message.type	The type of message (e.g., imageMessage, conversation).
message.quoted	Data about the message this one is replying to (if any).
message.mention	An array of JIDs mentioned in the message.
message.reply_message	An instance of ReplyMessage for interacting with the quoted message.

---

Methods: Sending & Interactions

• message.send(content, [options], [type]) General method to send any content.
  • content: Text string, Buffer, or Stream.
  • type: 'text', 'image', 'video', 'audio', 'sticker', 'document'.
• message.send(text) Shorthand to send a text reply to the current chat.
• message.sendFromUrl(url, [options]) Downloads and sends a file from a URL.

---

Methods: Group Management

• message.Add(jid, [groupJid]) Adds a user to a group. Returns an error code if invitation is required.
• message.Kick(jid, [groupJid]) Removes a user from a group.
• message.Promote(jid, [groupJid]) Makes a user a group admin.
• message.Demote(jid, [groupJid]) Removes admin privileges from a user.
• message.groupMetadata(jid, [full]) Fetches group details (participants, description, name).
• message.inviteCode(jid) Retrieves the group invitation link.
• message.revokeInvite(jid) Resets the group invitation link.
• message.acceptInvite(code) Joins a group using an invitation code.
• message.leftFromGroup(jid) Makes the bot leave a group.
• message.groupRequestList(jid) Lists pending join requests for a group.
• message.groupRequestAction(participants, action, jid) Approves or rejects join requests (action: 'approve' or 'reject').

---

Methods: User & Privacy

• message.Block(jid) Blocks a user.
• message.Unblock(jid) Unblocks a user.
• message.onWhatsapp(jid) Checks if a JID (or list of JIDs) exists on WhatsApp.
• message.fetchStatus(jid) Fetches a user's WhatsApp status/bio.
• message.updateProfilePicture(buffer, [jid]) Updates the bot's or a group's profile picture.
• message.profilePictureUrl(jid) Gets the URL of a user's or group's profile picture.

The ReplyMessage Object

When a message is a reply to another message, message.reply_message is an instance of ReplyMessage. This allows you to interact with the quoted message.

Properties

Property	Description
reply.id	The ID of the quoted message.
reply.jid	The JID of the person who sent the quoted message.
reply.text	Text content or caption of the quoted message.
reply.mimetype	Mimetype of the media (if any).
reply.type	Original message type (e.g., imageMessage).
reply.image	true if the quoted message is an image.
reply.video	true if the quoted message is a video.
reply.sticker	true if the quoted message is a sticker.
reply.audio	true if the quoted message is audio.
reply.pdf	true if the quoted message is a PDF document.
reply.seconds	Duration of audio or video in seconds.
reply.width	Width of image or video.
reply.height	Height of image or video.

---

Methods: Media Handling

• message.reply_message.downloadMediaMessage() Downloads the media from the quoted message and returns it as a Buffer.

• message.reply_message.downloadAndSaveMediaMessage(filename)

  • filename: Desired name (without extension).
  • Returns: Absolute path to the saved file.

---

Example: Media Plugin

bot({ pattern: 'getimg', desc: 'Saves quoted image' }, async (message, match) => {
    if (!message.reply_message || !message.reply_message.image) 
        return await message.send("Reply to an image!");

    const path = await message.reply_message.downloadAndSaveMediaMessage("my_download");
    await message.send(`Image saved at: ${path}`);
});