Create Your Own Bot

To create a functional bot, you need:

  • States to manage the conversation flow.

  • Functions associated with each state that perform actions based on user input.

  • Return next state key state function.

Registering a New State

To register a new state, you first need to create an async function that accepts two parameters: whatsapp.bot.WhatsappBot and whatsapp.messages.Incoming.

Note

You can define any hashable object as a state, but my personal preference is to use strings or integers.

The whatsapp.messages.Incoming class has many attributes, but for now, let’s focus on the message property, which contains the user’s message.

Here is the basic structure of a state function:

async def my_state(bot: WhatsappBot, incoming: Incoming) -> str | int:
    """My state function"""

To register a new state, use the whatsapp.bot.WhatsappBot.add_new_state() method. This method links the current state to the previous state, specifies what type of message or structure triggers this state, and defines the next state that the bot should wait for after processing. Let’s create an example that echoes the user’s message:

START = range(1)

async def echo_msg(bot: WhatsappBot, incoming: Incoming) -> str | int:
    msg_obj = TextMessage.to_send(incoming.message.from_, incoming.message.message_value)

    await bot.send_message(echo_msg, incoming.metadata.phone_number_id)

    return START

bot = WhatsappBot(WHATSAPP_TOKEN, VERIFY_TOKEN)
bot.add_new_state(START, echo_msg, TextMessage)

And that’s it! You have successfully registered a bot state that echoes user messages whenever it receives a whatsapp.messages.MessageTypes.TEXT message. But we’re not done yet—you can enhance this bot further by using additional methods from the whatsapp module and following some best practices.

Automatic Message Reading

If you want to read user messages without having to recreate a whatsapp.messages.ReadMessage object in every state function, you can use the whatsapp.utils.read_message() decorator. This decorator will automatically read the message each time the state function is called.

Handling Different Types of Messages

Your bot can handle different types of messages using two methods:

Message Type as a Trigger

You can trigger a state based on a single message type or a tuple of types. For example, you could trigger on (MessageTypes.IMAGE, MessageTypes.VIDEO).

Regex Match as a Trigger

You can define a regex pattern to match the user’s message. For example, r'^[0-9]$' for numeric input or r'^/start$' for commands. If you use command-like patterns, it’s recommended to register the command in the bot profile using the whatsapp.config_account.ProfileComponents.add_command() method. See more at Components.

Handling Invalid States

If no state is triggered, you can add an invalid state handler using whatsapp.bot.WhatsappBot.add_invalid_state(). This handler can be used to reset the user’s state, provide help, or simply do nothing.