# BotRS Examples

This directory contains complete examples for developing QQ Guild bots using the BotRS framework.

## 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:

```bash
cargo build --features examples
```

### 2. Configuration

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

```bash
cp config.example.toml config.toml
```

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

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

### 3. Alternative Configuration Methods

You can also configure the bot using:

#### Environment Variables:
```bash
export QQ_BOT_APP_ID="your_bot_app_id"
export QQ_BOT_SECRET="your_bot_secret"
```

#### Command Line Arguments:
```bash
cargo run --example demo_at_reply --features examples your_bot_app_id your_bot_secret
```

## Running Examples

### Basic AT Reply Bot
```bash
cargo run --example demo_at_reply --features examples
```

### Command-based AT Reply Bot
```bash
cargo run --example demo_at_reply_command --features examples
```

### Embed Message Bot
```bash
cargo run --example demo_at_reply_embed --features examples
```

### Markdown Message Bot
```bash
cargo run --example demo_at_reply_markdown --features examples
```

### Keyboard Message Bot
```bash
cargo run --example demo_at_reply_keyboard --features examples
```

### Group Message Bot
```bash
cargo run --example demo_group_reply_text --features examples
```

### C2C (Private) Message Bot
```bash
cargo run --example demo_c2c_reply_text --features examples
```

### File Upload Bot
```bash
cargo run --example demo_at_reply_file_data --features examples
```

### Message Recall Bot
```bash
cargo run --example demo_recall --features examples
```

### Direct Message Bot
```bash
cargo run --example demo_dms_reply --features examples
```

### Message Reference Bot
```bash
cargo run --example demo_at_reply_reference --features examples
```

### Simple Bot (Original)
```bash
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:
```bash
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](https://docs.rs/botrs)
- [QQ Guild Bot API Documentation](https://bot.q.qq.com/wiki/)
- [Rust Async Programming](https://rust-lang.github.io/async-book/)