Guilds and Channels Models API Reference

This module provides data structures for guilds (servers) and channels within the QQ Guild Bot API.

Guild Types

Guild

Represents a QQ guild (server) that the bot has access to.

pub struct Guild {
    pub id: String,
    pub name: String,
    pub icon: Option<String>,
    pub owner_id: String,
    pub owner: bool,
    pub member_count: Option<u32>,
    pub max_members: Option<u32>,
    pub description: Option<String>,
    pub joined_at: Option<String>,
    pub features: Vec<String>,
    pub op_user_id: Option<String>,
}

Fields

• id: Unique identifier for the guild
• name: Guild name
• icon: Guild icon URL (optional)
• owner_id: User ID of the guild owner
• owner: Whether the bot is the owner of the guild
• member_count: Current number of members
• max_members: Maximum allowed members
• description: Guild description
• joined_at: Timestamp when the bot joined the guild
• features: List of guild features enabled
• op_user_id: Operator user ID

Example

async fn handle_guild_create(ctx: Context, guild: Guild) {
    println!("Joined guild: {} (ID: {})", guild.name, guild.id);
    println!("Member count: {}", guild.member_count.unwrap_or(0));
    
    if guild.owner {
        println!("Bot is the owner of this guild");
    }
}

GuildRole

Represents a role within a guild.

pub struct GuildRole {
    pub id: String,
    pub name: String,
    pub color: Option<u32>,
    pub hoist: Option<bool>,
    pub number: Option<u32>,
    pub member_limit: Option<u32>,
}

Fields

• id: Unique identifier for the role
• name: Role name
• color: Role color (as hex value)
• hoist: Whether the role is displayed separately in member list
• number: Role position/priority
• member_limit: Maximum number of members that can have this role

Example

async fn list_guild_roles(ctx: Context, guild_id: &str) -> Result<()> {
    let roles = ctx.get_guild_roles(guild_id).await?;
    
    for role in roles.roles {
        println!("Role: {} (ID: {})", role.name, role.id);
        if let Some(color) = role.color {
            println!("  Color: #{:06X}", color);
        }
        if let Some(limit) = role.member_limit {
            println!("  Member limit: {}", limit);
        }
    }
    
    Ok(())
}

GuildRoles

Container for guild role information.

pub struct GuildRoles {
    pub guild_id: String,
    pub roles: Vec<GuildRole>,
    pub role_num_limit: Option<u32>,
}

Fields

• guild_id: ID of the guild these roles belong to
• roles: List of roles in the guild
• role_num_limit: Maximum number of roles allowed in the guild

Channel Types

Channel

Represents a channel within a guild.

pub struct Channel {
    pub id: String,
    pub guild_id: String,
    pub name: String,
    pub channel_type: ChannelType,
    pub sub_type: Option<ChannelSubType>,
    pub position: Option<u32>,
    pub parent_id: Option<String>,
    pub owner_id: Option<String>,
    pub private_type: Option<u32>,
    pub speak_permission: Option<u32>,
    pub application_id: Option<String>,
    pub permissions: Option<String>,
}

Fields

• id: Unique identifier for the channel
• guild_id: ID of the guild this channel belongs to
• name: Channel name
• channel_type: Type of channel (text, voice, etc.)
• sub_type: Channel subtype for additional classification
• position: Channel position in the channel list
• parent_id: ID of parent channel (for channel categories)
• owner_id: ID of the channel owner
• private_type: Privacy setting for the channel
• speak_permission: Speaking permission requirements
• application_id: Associated application ID
• permissions: Channel-specific permissions

Example

async fn handle_channel_create(ctx: Context, channel: Channel) {
    println!("New channel created: {} (Type: {:?})", channel.name, channel.channel_type);
    
    match channel.channel_type {
        ChannelType::Text => {
            println!("Text channel created in guild {}", channel.guild_id);
        }
        ChannelType::Voice => {
            println!("Voice channel created in guild {}", channel.guild_id);
        }
        ChannelType::Category => {
            println!("Category created in guild {}", channel.guild_id);
        }
        _ => {
            println!("Other channel type created");
        }
    }
}

ChannelType

Enumeration of different channel types.

pub enum ChannelType {
    Text = 0,
    Voice = 1,
    Category = 4,
    Announcement = 5,
    Forum = 10,
    Live = 11,
    Application = 12,
}

Variants

• Text: Text channel for messages
• Voice: Voice channel for audio communication
• Category: Category to organize channels
• Announcement: Announcement channel
• Forum: Forum channel for threaded discussions
• Live: Live streaming channel
• Application: Application-specific channel

Example

async fn create_text_channel(ctx: Context, guild_id: &str, name: &str) -> Result<Channel> {
    let channel = ctx.create_channel(
        guild_id,
        name,
        ChannelType::Text,
        None, // sub_type
        None, // position
        None, // parent_id
        None, // private_type
        None, // speak_permission
        None, // application_id
    ).await?;
    
    println!("Created text channel: {}", channel.name);
    Ok(channel)
}

ChannelSubType

Enumeration of channel subtypes for additional classification.

pub enum ChannelSubType {
    Chat = 0,
    Announcement = 1,
    Guide = 2,
    Game = 3,
}

Variants

• Chat: General chat channel
• Announcement: Announcement-specific channel
• Guide: Guide or help channel
• Game: Gaming-related channel

Member Types

Member

Represents a member of a guild.

pub struct Member {
    pub user: Option<User>,
    pub nick: Option<String>,
    pub roles: Vec<String>,
    pub joined_at: Option<String>,
    pub deaf: Option<bool>,
    pub mute: Option<bool>,
}

Fields

• user: User information for this member
• nick: Member's nickname in the guild
• roles: List of role IDs assigned to the member
• joined_at: Timestamp when the member joined the guild
• deaf: Whether the member is deafened in voice channels
• mute: Whether the member is muted in voice channels

Example

async fn handle_member_update(ctx: Context, member: Member) {
    if let Some(user) = &member.user {
        println!("Member updated: {}", user.username.as_deref().unwrap_or("Unknown"));
        
        if let Some(nick) = &member.nick {
            println!("Nickname: {}", nick);
        }
        
        println!("Roles: {:?}", member.roles);
    }
}

User

Represents user information.

pub struct User {
    pub id: String,
    pub username: Option<String>,
    pub avatar: Option<String>,
    pub bot: Option<bool>,
    pub union_openid: Option<String>,
    pub union_user_account: Option<String>,
}

Fields

• id: Unique user identifier
• username: User's display name
• avatar: Avatar image URL
• bot: Whether this user is a bot
• union_openid: Union OpenID for cross-platform identification
• union_user_account: Union user account identifier

Channel Management

Creating Channels

async fn setup_guild_channels(ctx: Context, guild_id: &str) -> Result<()> {
    // Create a category
    let category = ctx.create_channel(
        guild_id,
        "General",
        ChannelType::Category,
        None,
        Some(0), // position at top
        None,
        None,
        None,
        None,
    ).await?;
    
    // Create text channels under the category
    let general_chat = ctx.create_channel(
        guild_id,
        "general",
        ChannelType::Text,
        Some(ChannelSubType::Chat),
        Some(1),
        Some(&category.id), // parent category
        None,
        None,
        None,
    ).await?;
    
    let announcements = ctx.create_channel(
        guild_id,
        "announcements",
        ChannelType::Text,
        Some(ChannelSubType::Announcement),
        Some(2),
        Some(&category.id),
        None,
        None,
        None,
    ).await?;
    
    println!("Created category '{}' with channels:", category.name);
    println!("  - {}", general_chat.name);
    println!("  - {}", announcements.name);
    
    Ok(())
}

Channel Permissions

async fn manage_channel_permissions(ctx: Context, channel_id: &str, user_id: &str) -> Result<()> {
    // Get current permissions for a user
    let permissions = ctx.get_channel_user_permissions(channel_id, user_id).await?;
    println!("User permissions: {}", permissions.permissions);
    
    // Get permissions for a role
    let role_id = "role_id_here";
    let role_permissions = ctx.get_channel_role_permissions(channel_id, role_id).await?;
    println!("Role permissions: {}", role_permissions.permissions);
    
    Ok(())
}

Guild Member Management

async fn manage_guild_members(ctx: Context, guild_id: &str) -> Result<()> {
    // Get guild members
    let members = ctx.get_guild_members(guild_id, Some(100), None).await?;
    println!("Guild has {} members", members.len());
    
    for member in &members {
        if let Some(user) = &member.user {
            println!("Member: {}", user.username.as_deref().unwrap_or("Unknown"));
            println!("  Roles: {:?}", member.roles);
            
            if let Some(joined) = &member.joined_at {
                println!("  Joined: {}", joined);
            }
        }
    }
    
    // Get specific member
    let user_id = "specific_user_id";
    let member = ctx.get_guild_member(guild_id, user_id).await?;
    if let Some(user) = &member.user {
        println!("Found member: {}", user.username.as_deref().unwrap_or("Unknown"));
    }
    
    Ok(())
}

Role Management

async fn manage_roles(ctx: Context, guild_id: &str) -> Result<()> {
    // Create a new role
    let new_role = ctx.create_guild_role(
        guild_id,
        "Moderator",
        Some(0x0099ff), // Blue color
        Some(true),     // Hoist (display separately)
        Some(100),      // Member limit
    ).await?;
    
    println!("Created role: {} (ID: {})", new_role.name, new_role.id);
    
    // Assign role to a user
    let user_id = "user_id_here";
    ctx.add_guild_role_member(guild_id, &new_role.id, user_id, None).await?;
    println!("Assigned role to user");
    
    // Update role
    let updated_role = ctx.update_guild_role(
        guild_id,
        &new_role.id,
        "Senior Moderator",
        Some(0xff9900), // Orange color
        Some(true),
        Some(50), // Reduced member limit
    ).await?;
    
    println!("Updated role: {}", updated_role.name);
    
    // Remove role from user
    ctx.remove_guild_role_member(guild_id, &new_role.id, user_id, None).await?;
    println!("Removed role from user");
    
    // Delete role
    ctx.delete_guild_role(guild_id, &new_role.id).await?;
    println!("Deleted role");
    
    Ok(())
}

Common Usage Patterns

Guild Discovery

async fn explore_guilds(ctx: Context) -> Result<()> {
    let guilds = ctx.get_guilds(None, None).await?;
    
    for guild in guilds {
        println!("Guild: {} (ID: {})", guild.name, guild.id);
        
        // Get channels for this guild
        let channels = ctx.get_channels(&guild.id).await?;
        println!("  Channels ({}):", channels.len());
        
        for channel in channels {
            let type_name = match channel.channel_type {
                ChannelType::Text => "Text",
                ChannelType::Voice => "Voice",
                ChannelType::Category => "Category",
                ChannelType::Announcement => "Announcement",
                ChannelType::Forum => "Forum",
                ChannelType::Live => "Live",
                ChannelType::Application => "Application",
            };
            
            println!("    {} - {} ({})", channel.name, type_name, channel.id);
        }
    }
    
    Ok(())
}

Channel Organization

async fn organize_channels(ctx: Context, guild_id: &str) -> Result<()> {
    let channels = ctx.get_channels(guild_id).await?;
    
    // Group channels by category
    let mut categories = std::collections::HashMap::new();
    let mut orphaned_channels = Vec::new();
    
    for channel in channels {
        match (channel.channel_type, &channel.parent_id) {
            (ChannelType::Category, _) => {
                categories.insert(channel.id.clone(), (channel, Vec::new()));
            }
            (_, Some(parent_id)) => {
                if let Some((_, children)) = categories.get_mut(parent_id) {
                    children.push(channel);
                }
            }
            (_, None) => {
                orphaned_channels.push(channel);
            }
        }
    }
    
    // Print organized structure
    for (_, (category, children)) in categories {
        println!("Category: {}", category.name);
        for child in children {
            println!("  └─ {}", child.name);
        }
    }
    
    if !orphaned_channels.is_empty() {
        println!("Uncategorized channels:");
        for channel in orphaned_channels {
            println!("  - {}", channel.name);
        }
    }
    
    Ok(())
}

See Also

• Client API - Main client for guild and channel operations
• Context API - Context object for API access
• Messages - Message types and handling
• Users & Members - User and member management