Client API Reference

The Client is the main entry point for creating and managing QQ Guild bots. It handles the WebSocket connection, authentication, and event dispatching to your event handler.

Overview

use botrs::{Client, EventHandler, Intents, Token};

pub struct Client<H: EventHandler> {
    // Internal fields...
}

The Client manages:

• WebSocket connection to QQ Guild gateway
• Authentication with QQ servers
• Event dispatching to your EventHandler
• Automatic reconnection and heartbeat handling
• Rate limiting and request management

Constructor

new

Creates a new client instance.

pub fn new(
    token: Token,
    intents: Intents,
    handler: H,
    use_sandbox: bool,
) -> Result<Self>

Parameters

• token: Authentication token containing your app ID and secret
• intents: Event subscription configuration
• handler: Your event handler implementing the EventHandler trait
• use_sandbox: Whether to use sandbox environment for testing

Returns

Returns Result<Client<H>, BotError> - the client instance or an error if initialization fails.

Example

use botrs::{Client, EventHandler, Intents, Token};

struct MyHandler;

#[async_trait::async_trait]
impl EventHandler for MyHandler {
    // Event handling methods...
}

let token = Token::new("your_app_id", "your_secret");
let intents = Intents::default().with_public_guild_messages();
let handler = MyHandler;

let client = Client::new(token, intents, handler, false)?;

Methods

start

Starts the bot and begins listening for events. This method blocks until the connection is closed.

pub async fn start(&mut self) -> Result<()>

Returns

Returns Result<(), BotError> - Ok(()) when the bot stops gracefully, or an error if connection fails.

Example

let mut client = Client::new(token, intents, handler, false)?;
client.start().await?;

stop

Gracefully stops the bot and closes the WebSocket connection.

pub async fn stop(&mut self) -> Result<()>

Returns

Returns Result<(), BotError> - Ok(()) when successfully stopped, or an error if stopping fails.

Example

// In another task or signal handler
client.stop().await?;

is_connected

Checks if the client is currently connected to the gateway.

pub fn is_connected(&self) -> bool

Returns

Returns true if connected, false otherwise.

Example

if client.is_connected() {
    println!("Bot is online");
} else {
    println!("Bot is offline");
}

get_session_info

Gets information about the current session.

pub fn get_session_info(&self) -> Option<&ConnectionSession>

Returns

Returns Some(&ConnectionSession) if connected, None if disconnected.

Example

if let Some(session) = client.get_session_info() {
    println!("Session ID: {}", session.session_id);
    println!("Shard: {}/{}", session.shard_id, session.shard_count);
}

Configuration

Environment URLs

The client automatically selects the appropriate API endpoints:

• Production: https://api.sgroup.qq.com
• Sandbox: https://sandbox.api.sgroup.qq.com

Connection Settings

Default connection settings:

• WebSocket URL: wss://api.sgroup.qq.com/websocket
• Timeout: 30 seconds for HTTP requests
• Heartbeat: Automatic based on server requirements
• Reconnection: Automatic with exponential backoff

Error Handling

The client can return various errors:

use botrs::BotError;

match client.start().await {
    Ok(_) => println!("Bot stopped gracefully"),
    Err(BotError::Authentication(e)) => eprintln!("Auth error: {}", e),
    Err(BotError::Network(e)) => eprintln!("Network error: {}", e),
    Err(BotError::Gateway(e)) => eprintln!("Gateway error: {}", e),
    Err(e) => eprintln!("Other error: {}", e),
}

Event Flow

1. Connection: Client connects to WebSocket gateway
2. Authentication: Sends identify payload with token and intents
3. Ready: Receives ready event, bot is now online
4. Event Loop: Continuously receives and dispatches events
5. Reconnection: Automatically reconnects if connection drops

Thread Safety

The Client is designed to be used from a single async task. For multi-threaded applications, wrap it in appropriate synchronization primitives:

use std::sync::Arc;
use tokio::sync::Mutex;

let client = Arc::new(Mutex::new(client));

Examples

Basic Bot

use botrs::{Client, Context, EventHandler, Intents, Message, Ready, Token};

struct BasicBot;

#[async_trait::async_trait]
impl EventHandler for BasicBot {
    async fn ready(&self, _ctx: Context, ready: Ready) {
        println!("Bot ready: {}", ready.user.username);
    }

    async fn message_create(&self, ctx: Context, message: Message) {
        if let Some(content) = &message.content {
            if content == "!ping" {
                let _ = message.reply(&ctx.api, &ctx.token, "Pong!").await;
            }
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = Token::new("app_id", "secret");
    let intents = Intents::default().with_public_guild_messages();
    let mut client = Client::new(token, intents, BasicBot, false)?;
    
    client.start().await?;
    Ok(())
}

Bot with Graceful Shutdown

use tokio::signal;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = Token::new("app_id", "secret");
    let intents = Intents::default().with_public_guild_messages();
    let mut client = Client::new(token, intents, MyHandler, false)?;
    
    // Start bot in background task
    let client_handle = tokio::spawn(async move {
        client.start().await
    });
    
    // Wait for Ctrl+C
    signal::ctrl_c().await?;
    println!("Shutdown signal received");
    
    // Stop the bot
    client_handle.abort();
    
    Ok(())
}

Multiple Intents

let intents = Intents::default()
    .with_public_guild_messages()
    .with_direct_message()
    .with_guilds()
    .with_guild_members();

let mut client = Client::new(token, intents, handler, false)?;

See Also

• EventHandler - Define how your bot responds to events
• Context - Access API client and token in event handlers
• Intents - Configure which events to receive
• Token - Authentication and credentials management