Create Your First Bot

This guide builds on the 5-Minute Quick Start to walk you through writing your first command handler and understanding the underlying mechanics.

If you haven't installed ErisPulse or initialized your project yet, please complete the "Install," "Initialize Project," and "Run Project" steps in the Quick Start first.

Step 1: Write Your First Command

Open main.py and write a simple command handler:

from ErisPulse import sdk
from ErisPulse.Core.Event import command

@command("hello", help="Send a greeting message")
async def hello_handler(event):
    """Handle the hello command"""
    user_name = event.get_user_nickname() or "friend"
    await event.reply(f"Hello, {user_name}! I am the ErisPulse bot.")

@command("ping", help="Test if the bot is online")
async def ping_handler(event):
    """Handle the ping command"""
    await event.reply("Pong! The bot is running normally.")

async def main():
    """Main entry function"""
    print("Starting ErisPulse...")
    
    # keep_running=True (default): The framework blocks and stays running until a shutdown signal is received (e.g., Ctrl+C)
    await sdk.run(keep_running=True)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

keep_running Parameter

sdk.run(keep_running) controls whether the framework blocks and remains running:

• keep_running=True (default): run() will block indefinitely until a shutdown signal (e.g., Ctrl+C) is received, suitable for pure bot applications.
• keep_running=False: run() returns immediately after initialization. The framework is not unloaded—active adapters/modules continue processing message events as background tasks. You can then proceed with your own logic until the event loop ends and the framework shuts down. For example:

async def main():
    await sdk.run(keep_running=False)   # Returns immediately after initialization
    # The framework is running in the background, here you can continue doing other things
    while True:
        await asyncio.sleep(3600)
        print("Check every hour")

Besides the two modes of run(), there are also more granular ways to manually control the lifecycle, such as init()/uninit() and individually starting/stopping adapters/routes. See Startup Process and Manual Control.

Step 2: Run the Robot

# Run normally
epsdk run main.py

# Development mode (supports hot reload)
epsdk run main.py --reload

Step 3: Test the Bot

Send the following command in your chat platform:

/hello

You should receive a reply from the bot.

Code Explanation

Command Decorator

@command("hello", help="Send a greeting message")

• hello: The command name, which users invoke via /hello
• help: The help description, displayed in the /help command

Event Parameters

async def hello_handler(event):

The event parameter is an Event object, containing:

• Message content: event.get_text()
• Sender information: event.get_user_id(), event.get_user_nickname()
• Platform information: event.get_platform()
• Group information: event.get_group_id()
• Raw data: event.get_raw()

For a complete list of Event object methods, refer to Event Wrapper Class Details.

Sending a Reply

await event.reply("Reply content")

event.reply() is a convenient method for sending messages back to the sender.

Extensions: Adding More Features

ErisPulse provides rich event handling and data processing capabilities:

• Message Listening: Use @message.on_message() to listen to various types of messages → Event Handling Introduction
• Notification Listening: Use @notice.on_friend_add() and others to listen to system notifications → Event Handling Introduction
• Data Storage: Use sdk.storage.get/set to persist data → Common Tasks Examples

FAQ

No response from command?

1. Check if the adapter is correctly configured, and confirm that the status of the adapter in config/config.toml is set to true.
2. Check the terminal log output to confirm if there are any error messages (especially those with ERROR level).
3. Confirm that the command prefix is correct (the default is /), and check the [ErisPulse.event.command] section in the configuration file.
4. Confirm that the command name is spelled correctly, and pay attention to case sensitivity settings.

How to change the command prefix?

Add the following to config.toml:

[ErisPulse.event.command]
prefix = "!"
case_sensitive = false

How to support multiple platforms?

ErisPulse uses the OneBot12 standard to unify the event formats of different platforms. Handlers registered with @command and @message will automatically receive events from all platforms. You can distinguish the source platform using event.get_platform():

@command("hello")
async def hello_handler(event):
    platform = event.get_platform()
    
    if platform == "yunhu":
        await event.reply("你好！来自云湖")
    elif platform == "telegram":
        await event.reply("Hello! From Telegram")
    else:
        await event.reply("你好！")

For more multi-platform adaptation techniques, please refer to Common Tasks Examples.

Next Steps

• Basic Concepts - Dive deeper into the core concepts of ErisPulse
• Getting Started with Event Handling - Learn how to handle various events
• Common Tasks Examples - Master more practical features