Receiving User Input

One of the most powerful features of WhatsBotCord is the ability to halt command execution and wait for the user to reply. This allows you to build highly interactive, multi-step flows without managing complex external states.

Instead of splitting the code into fragmented pieces, here is a complete, production-ready example of how to wait for user input robustly.

The Production Pattern: Validation Loops

When receiving input, users might send invalid data, the wrong media type, or simply take too long. The best practice is to wrap the wait logic inside a while (true) loop. This allows you to reject bad input and ask again without cancelling the entire command.

TypeScript

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

export class AskNameCommand implements ICommand {
  public name: string = "askname";

  public async run(ctx: IChatContext, api: AdditionalAPI, args: CommandArgs): Promise<void> {
    await ctx.Loading();
    await ctx.SendText("🤖 Hello! Please tell me your first name:");

    let validName: string;

    // The Validation Loop
    while (true) {
      // 1. Wait for a text response for up to 60 seconds
      const result: string | null = await ctx.WaitText({ timeoutSeconds: 60 });

      // 2. Handle Timeouts
      if (result === null) {
        await ctx.SendText("⏳ You took too long to respond. Please send your name:");
        continue; // Ask again!
      }

      // 3. Handle Validation
      const trimmedName = result.trim();
      if (trimmedName.length < 2) {
        await ctx.SendText("⚠️ That name is too short. Try again:");
        continue; // Ask again!
      }

      // 4. Success! Break the loop
      validName = trimmedName;
      break;
    }

    // 5. Continue execution
    await ctx.SendText(`✅ Nice to meet you, ${validName}!`);
    await ctx.Ok();
  }
}

Breaking Down the Logic

1. ctx.WaitText(...) This is a built-in helper that halts the function’s execution until the user replies. By default, it filters out images, audios, or videos, returning only the text content.

2. Handling Timeouts (null) If the user does not reply within the timeoutSeconds window, the function resolves to null. In our loop, we simply catch this null, inform the user, and use continue to start waiting again.

3. Validation and continue Since we are inside a while (true) loop, if the user sends text but it doesn’t meet our criteria (e.g., too short, invalid format), we send a warning and use continue to jump back to WaitText().

4. Breaking the Loop Once the input passes all validations, we save the result into our validName variable and use break to exit the loop and finish the command.

Waiting for Multimedia (Images, Audio, Video)

Sometimes you don’t want text, you want a file. Instead of WaitText, you can use WaitMultimedia. It works exactly the same way but returns a binary Buffer containing the downloaded media.

import { MsgType } from "whatsbotcord";

// ... inside your run method ...

await ctx.SendText("🖼️ Please send me an image:");

while(true) {
    // Specify what type of media you are waiting for
    const imgBuffer: Buffer | null = await ctx.WaitMultimedia(MsgType.Image, {
        timeoutSeconds: 60
    });

    if (imgBuffer === null) {
        await ctx.SendText("❌ I didn't receive an image in time. Try again:");
        continue;
    }

    // You now have the binary data! You can save it, manipulate it, or send it back.
    await ctx.SendText("✅ Image received! Size: " + imgBuffer.length + " bytes.");
    break;
}

Note: Just like WaitText, WaitMultimedia automatically ignores messages that don’t match the requested MsgType. If you ask for an Image and the user sends text or an audio note, it will gracefully ignore it until they send an actual image or the timeout is reached.