examples

BotRS Examples

This directory contains complete examples for developing QQ Guild bots using the BotRS framework. These examples are Rust implementations equivalent to the Python botpy examples.

Directory Structure

examples/
├── README.md                    # This file
├── config.example.toml          # Example configuration file
├── common/                      # Common utilities for examples
│   ├── mod.rs                   # Common module exports
│   └── config.rs                # Configuration loading utilities
├── simple_bot.rs                # Basic bot with simple message handling
├── demo_at_reply.rs             # Bot @ reply example
├── demo_at_reply_command.rs     # Bot @ reply with command system
├── demo_at_reply_embed.rs       # Bot @ reply with embed messages
├── demo_at_reply_markdown.rs    # Bot @ reply with markdown messages
├── demo_at_reply_keyboard.rs    # Bot @ reply with keyboard messages
├── demo_at_reply_file_data.rs   # Bot @ reply with file uploads
├── demo_at_reply_reference.rs   # Bot @ reply with message references
├── demo_group_reply_text.rs     # Bot group message reply example
├── demo_c2c_reply_text.rs       # Bot C2C (private) message reply example
├── demo_dms_reply.rs            # Bot direct message reply example
└── demo_recall.rs               # Bot message recall (delete) example

Setup

1. Install Dependencies

Make sure you have Rust installed, then build the project:

cargo build --features examples

2. Configuration

Copy the example configuration file and fill in your bot credentials:

cp config.example.toml config.toml

Edit config.toml and provide your bot's App ID and Secret:

[bot]
app_id = "your_bot_app_id"
secret = "your_bot_secret"

3. Alternative Configuration Methods

You can also configure the bot using:

Environment Variables:

export QQ_BOT_APP_ID="your_bot_app_id"
export QQ_BOT_SECRET="your_bot_secret"

Command Line Arguments:

cargo run --example demo_at_reply --features examples your_bot_app_id your_bot_secret

Running Examples

Basic AT Reply Bot

cargo run --example demo_at_reply --features examples

Command-based AT Reply Bot

cargo run --example demo_at_reply_command --features examples

Embed Message Bot

cargo run --example demo_at_reply_embed --features examples

Markdown Message Bot

cargo run --example demo_at_reply_markdown --features examples

Keyboard Message Bot

cargo run --example demo_at_reply_keyboard --features examples

Group Message Bot

cargo run --example demo_group_reply_text --features examples

C2C (Private) Message Bot

cargo run --example demo_c2c_reply_text --features examples

File Upload Bot

cargo run --example demo_at_reply_file_data --features examples

Message Recall Bot

cargo run --example demo_recall --features examples

Direct Message Bot

cargo run --example demo_dms_reply --features examples

Message Reference Bot

cargo run --example demo_at_reply_reference --features examples

Simple Bot (Original)

cargo run --example simple_bot --features examples

Example Descriptions

demo_at_reply.rs

• Python equivalent: demo_at_reply.py
• Features: Basic @ mention handling, async message processing, sleep command
• Intents: public_guild_messages

demo_at_reply_command.rs

• Python equivalent: demo_at_reply_command.py
• Features: Command system with aliases, parameter parsing, dual sending methods
• Commands: 你好/hello, 晚安
• Intents: public_guild_messages

demo_at_reply_embed.rs

• Python equivalent: demo_at_reply_embed.py
• Features: Rich embed messages with fields, colors, and formatting
• Intents: public_guild_messages

demo_at_reply_markdown.rs

• Python equivalent: demo_at_reply_markdown.py
• Features: Markdown messages with templates and custom content
• Methods: Template-based and content-based markdown
• Intents: public_guild_messages

demo_at_reply_keyboard.rs

• Python equivalent: demo_at_reply_keyboard.py
• Features: Interactive keyboard messages with buttons and actions
• Methods: Template keyboards and custom-defined keyboards
• Intents: public_guild_messages

demo_group_reply_text.rs

• Python equivalent: demo_group_reply_text.py
• Features: Group message handling and replies
• Intents: public_messages

demo_c2c_reply_text.rs

• Python equivalent: demo_c2c_reply_text.py
• Features: C2C (private/friend) message handling and replies
• Intents: public_messages

demo_at_reply_file_data.rs

• Python equivalent: demo_at_reply_file_data.py
• Features: File upload functionality with multiple methods (bytes, direct, path-based)
• File types: Images, documents, media files
• Intents: public_guild_messages

demo_recall.rs

• Python equivalent: demo_recall.py
• Features: Message sending and immediate recall (deletion)
• Methods: Reply and recall with hide tip option
• Intents: public_guild_messages

demo_dms_reply.rs

• Python equivalent: demo_dms_reply.py
• Features: Direct message handling, DM session creation, private message replies
• Commands: /私信 to trigger DM session creation
• Intents: direct_message, public_guild_messages

demo_at_reply_reference.rs

• Python equivalent: demo_at_reply_reference.py
• Features: Message references (replies to specific messages), emoji support
• Methods: Reference creation and reply with message context
• Intents: public_guild_messages

Intent Types

Different examples use different intent types to receive specific event types:

• public_guild_messages: For receiving @ mentions in guild channels
• public_messages: For receiving group and C2C messages
• direct_message: For receiving direct messages (DMs)
• guilds: For receiving guild-related events

Message Types

The examples demonstrate various message types:

• Text messages: Plain text content
• Embed messages: Rich embeds with titles, descriptions, fields, and colors
• Markdown messages: Formatted messages using markdown syntax
• Keyboard messages: Interactive messages with clickable buttons
• Media messages: Messages with attachments (files, images, etc.)

Error Handling

All examples include proper error handling:

• Token validation
• API call error handling
• Event processing error handling
• Graceful degradation when optional data is missing

Logging

Examples use the tracing crate for structured logging:

• Debug level for BotRS internal operations
• Info level for bot operations and successful actions
• Warn level for recoverable errors
• Error level for serious issues

You can control logging with the RUST_LOG environment variable:

RUST_LOG=debug cargo run --example demo_at_reply --features examples

Development Tips

1. Testing: Use the sandbox environment by setting sandbox = true in your config
2. Debugging: Enable debug logging to see detailed API interactions
3. Hot Reloading: The bot will automatically reconnect on network issues
4. Rate Limiting: The framework handles rate limiting automatically

Common Issues

Invalid Token

• Ensure your App ID and Secret are correct
• Check that your bot has the necessary permissions
• Verify you're using the correct environment (production vs sandbox)

No Events Received

• Check your intent configuration
• Ensure your bot is added to the target guild/group
• Verify network connectivity

Message Send Failures

• Check bot permissions in the target channel/group
• Ensure the message content meets platform requirements
• Verify the target ID (channel_id, group_openid, user_openid) is correct

Further Reading

• BotRS Documentation
• QQ Guild Bot API Documentation
• Rust Async Programming