ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

Create Your First Bot

Tip

When to read this: Your bot is already running, and you want to write your first /hello command handler and understand what sdk.run and command decorators do. If you haven't installed ErisPulse, initialized a project, or run the project yet, complete the "Install", "Initialize Project", and "Run Project" steps in 5-Minute Quick Start first; otherwise, skip this section.

Running through the quick start is just the first step—this guide walks you through writing your first command handler and explains what each line of code does within the framework.

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:

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.

What's Next

  • Continue along the learning path: Read Basic Concepts to understand what the framework behind command handlers does.
  • Want to handle more message types: Event Handling Introduction, how to write handlers for messages / notifications / requests / meta-events.
  • Want to add practical features: Common Tasks Examples, ready-to-use code for persistence, scheduled tasks, and permission control.