Usage Guide

This guide explains the core concepts of WBOT, including its reply logic, how to send different types of messages, and how to control its behavior.

The Reply Logic

WBOT processes incoming messages by checking them against the list of rules defined in the bot array of your bot.json file. The logic follows a clear priority:

Exact Match: The bot first checks if the incoming message perfectly matches any string in the exact array of a rule.
Contains Match: If no exact match is found, it checks if the message contains any of the substrings in the contains array of a rule.
No Match: If neither an exact nor a contains match is found, the bot sends the default response defined in the noMatch key.

This flow is illustrated below:

graph TD
    A[Incoming Message] --> B{Is it an exact match?};
    B -- Yes --> C[Send Response from Rule];
    B -- No --> D{Does it contain a keyword?};
    D -- Yes --> C;
    D -- No --> E[Send `noMatch` Response];

Crafting Responses

Basic Text Responses

The simplest rule involves a trigger and a text response.

{
    "contains": [],
    "exact": ["hello"],
    "response": "hi"
}

Dynamic Responses with Spintax

You can make your bot's replies less repetitive using Spintax. Enclose words or phrases in curly braces {} and separate them with pipes |. The bot will randomly select one of the options.

{
    "contains": [],
    "exact": ["hi"],
    "response": "{Hello|Howdy|Hi there}!"
}

Using Variables in Responses

WBOT supports variables to personalize messages. These are automatically replaced with the sender's information.

[#name]: The sender's WhatsApp display name.
[#phoneNumber]: The sender's phone number.
[#greetings]: A time-appropriate greeting (e.g., "Good Morning").

Example:

{
    "contains": [],
    "exact": ["variables"],
    "response": "Hey [#name] 👋, [#greetings]. This is your phone number, [#phoneNumber]"
}

Sending Media Files

To send a file, add a file key to your rule object. The value should be an array of strings, where each string is the path to a file relative to the WBOT executable.

{
    "contains": ["github"],
    "exact": [],
    "response": "Sending images",
    "file": [
        "./mediaToBeSent/github.png",
        "./mediaToBeSent/github-two.png"
    ]
}

Media with Captions

By default, the response text is sent as a separate message after the file. To send the response as the file's caption, add "responseAsCaption": true to your rule.

Delayed Responses

To make the bot feel more natural, you can add a delay before it sends a reply using the afterSeconds key.

{
    "contains": [],
    "exact": ["hello"],
    "response": "hi",
    "afterSeconds": 3
}

Controlling Bot Scope

You can control who the bot replies to and in what context.

Group Replies: Set "isGroupReply": true in the appconfig section to allow the bot to respond in group chats. By default, it is false.
Blocking Contacts: Add phone numbers (with country code, without +) to the blocked array to prevent the bot from ever replying to them.
```
"blocked": ["1234567890"]
```
Allowing Contacts: If the allowed array is not empty, the bot will only reply to numbers in this list, acting as a whitelist.
```
"allowed": ["1234567890", "0987654321"]
```