Struct GuildChannel

#[non_exhaustive]
pub struct GuildChannel {

    pub id: ChannelId,
    pub bitrate: Option<u32>,
    pub parent_id: Option<ChannelId>,
    pub guild_id: GuildId,
    pub kind: ChannelType,
    pub owner_id: Option<UserId>,
    pub last_message_id: Option<MessageId>,
    pub last_pin_timestamp: Option<Timestamp>,
    pub name: String,
    pub permission_overwrites: Vec<PermissionOverwrite>,
    pub position: u16,
    pub topic: Option<String>,
    pub user_limit: Option<u32>,
    pub nsfw: bool,
    pub rate_limit_per_user: Option<u16>,
    pub rtc_region: Option<String>,
    pub video_quality_mode: Option<VideoQualityMode>,
    pub message_count: Option<u32>,
    pub member_count: Option<u8>,
    pub thread_metadata: Option<ThreadMetadata>,
    pub member: Option<PartialThreadMember>,
    pub default_auto_archive_duration: Option<AutoArchiveDuration>,
    pub permissions: Option<Permissions>,
    pub flags: ChannelFlags,
    pub total_message_sent: Option<u64>,
    pub available_tags: Vec<ForumTag>,
    pub applied_tags: Vec<ForumTagId>,
    pub default_reaction_emoji: Option<ForumEmoji>,
    pub default_thread_rate_limit_per_user: Option<u16>,
    pub status: Option<String>,
    pub default_sort_order: Option<SortOrder>,
    pub default_forum_layout: Option<ForumLayoutType>,
}

Represents a guild’s text, news, or voice channel.

Some methods are available only for voice channels and some are only available for text channels. News channels are a subset of text channels and lack slow mode hence Self::rate_limit_per_user will be None.

Discord docs.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: ChannelId

The unique Id of the channel.

bitrate: Option<u32>

The bitrate of the channel.

Note: This is only available for voice and stage channels.

parent_id: Option<ChannelId>

The Id of the parent category for a channel, or of the parent text channel for a thread.

Note: This is only available for channels in a category and thread channels.

guild_id: GuildId

The Id of the guild the channel is located in.

The original voice channel has an Id equal to the guild’s Id, incremented by one.

kind: ChannelType

The type of the channel.

owner_id: Option<UserId>

The Id of the user who created this channel

Note: This is only available for threads and forum posts

last_message_id: Option<MessageId>

The Id of the last message sent in the channel.

Note: This is only available for text channels.

last_pin_timestamp: Option<Timestamp>

The timestamp of the time a pin was most recently made.

Note: This is only available for text channels.

name: String

The name of the channel.

permission_overwrites: Vec<PermissionOverwrite>

Permission overwrites for Members and for Roles.

position: u16

The position of the channel.

The default text channel will almost always have a position of 0.

topic: Option<String>

The topic of the channel.

Note: This is only available for text, forum and stage channels.

user_limit: Option<u32>

The maximum number of members allowed in the channel.

Note: This is only available for voice channels.

nsfw: bool

Used to tell if the channel is not safe for work.

rate_limit_per_user: Option<u16>

A rate limit that applies per user and excludes bots.

Note: This is only available for text channels excluding news channels.

rtc_region: Option<String>

The region override.

Note: This is only available for voice and stage channels. None for voice and stage channels means automatic region selection.

video_quality_mode: Option<VideoQualityMode>

The video quality mode for a voice channel.

message_count: Option<u32>

An approximate count of messages in the thread.

This is currently saturated at 255 to prevent breaking.

Note: This is only available on thread channels.

member_count: Option<u8>

An approximate count of users in a thread, stops counting at 50.

Note: This is only available on thread channels.

thread_metadata: Option<ThreadMetadata>

The thread metadata.

Note: This is only available on thread channels.

member: Option<PartialThreadMember>

Thread member object for the current user, if they have joined the thread, only included on certain API endpoints.

default_auto_archive_duration: Option<AutoArchiveDuration>

Default duration for newly created threads, in minutes, to automatically archive the thread after recent activity.

permissions: Option<Permissions>

Computed permissions for the invoking user in the channel, including overwrites.

Only included inside CommandDataResolved.

flags: ChannelFlags

Extra information about the channel

Note: This is only available in forum channels.

total_message_sent: Option<u64>

The number of messages ever sent in a thread, it’s similar to message_count on message creation, but will not decrement the number when a message is deleted.

available_tags: Vec<ForumTag>

The set of available tags.

Note: This is only available in forum channels.

applied_tags: Vec<ForumTagId>

The set of applied tags.

Note: This is only available in a thread in a forum.

default_reaction_emoji: Option<ForumEmoji>

The emoji to show in the add reaction button

Note: This is only available in a forum.

default_thread_rate_limit_per_user: Option<u16>

The initial rate_limit_per_user to set on newly created threads in a channel. This field is copied to the thread at creation time and does not live update.

Note: This is only available in a forum or text channel.

status: Option<String>

The status of a voice channel.

Note: This is only available in voice channels.

default_sort_order: Option<SortOrder>

The default sort order type used to order posts

Note: This is only available in a forum.

default_forum_layout: Option<ForumLayoutType>

The default forum layout view used to display posts in a forum. Defaults to 0, which indicates a layout view has not been set by a channel admin.

Note: This is only available in a forum.

Implementations

impl GuildChannel

pub fn is_text_based(&self) -> bool

Whether or not this channel is text-based, meaning that it is possible to send messages.

pub async fn broadcast_typing(&self, http: impl AsRef<Http>) -> Result<()>

Broadcasts to the channel that the current user is typing.

For bots, this is a good indicator for long-running commands.

Note: Requires the Send Messages permission.

Errors

Returns Error::Http if the current user does not have the required permissions.

pub async fn create_invite( &self, cache_http: impl CacheHttp, builder: CreateInvite<'_>, ) -> Result<RichInvite>

Creates an invite for the given channel.

Note: Requires the Create Instant Invite permission.

Examples

Create an invite that can only be used 5 times:

let builder = CreateBuilder::default().max_uses(5);
let invite = channel.create_invite(&context, builder).await;

Errors

If the cache is enabled, returns ModelError::InvalidPermissions if the current user lacks permission. Otherwise returns Error::Http, as well as if invalid data is given.

pub async fn create_permission( &self, http: impl AsRef<Http>, target: PermissionOverwrite, ) -> Result<()>

Creates a permission overwrite for either a single Member or Role within a Channel.

Refer to the documentation for PermissionOverwrites for more information.

Requires the Manage Channels permission.

Examples

Creating a permission overwrite for a member by specifying the PermissionOverwriteType::Member variant, allowing it the Send Messages permission, but denying the Send TTS Messages and Attach Files permissions:

use serenity::model::channel::{PermissionOverwrite, PermissionOverwriteType};
use serenity::model::{ModelError, Permissions};
let allow = Permissions::SEND_MESSAGES;
let deny = Permissions::SEND_TTS_MESSAGES | Permissions::ATTACH_FILES;
let overwrite = PermissionOverwrite {
    allow,
    deny,
    kind: PermissionOverwriteType::Member(user_id),
};
// assuming the cache has been unlocked
let channel = cache.channel(channel_id).ok_or(ModelError::ItemMissing)?;

channel.create_permission(&http, overwrite).await?;

Creating a permission overwrite for a role by specifying the PermissionOverwriteType::Role variant, allowing it the Manage Webhooks permission, but denying the Send TTS Messages and Attach Files permissions:

use serenity::model::channel::{Channel, PermissionOverwrite, PermissionOverwriteType};
use serenity::model::{ModelError, Permissions};

let allow = Permissions::SEND_MESSAGES;
let deny = Permissions::SEND_TTS_MESSAGES | Permissions::ATTACH_FILES;
let overwrite = PermissionOverwrite {
    allow,
    deny,
    kind: PermissionOverwriteType::Role(role_id),
};

let channel = cache.channel(channel_id).ok_or(ModelError::ItemMissing)?;

channel.create_permission(&http, overwrite).await?;

Errors

Returns Error::Http if the current user lacks permission.

pub async fn delete(&self, cache_http: impl CacheHttp) -> Result<GuildChannel>

Deletes this channel, returning the channel on a successful deletion.

Note: Requires the Manage Channels permission.

Errors

If the cache is enabled, returns ModelError::InvalidPermissions if the current user does not have permission.

Otherwise returns Error::Http if the current user lacks permission.

pub async fn delete_messages<T: AsRef<MessageId>>( &self, http: impl AsRef<Http>, message_ids: impl IntoIterator<Item = T>, ) -> Result<()>

Deletes all messages by Ids from the given vector in the channel.

The minimum amount of messages is 2 and the maximum amount is 100.

Requires the Manage Messages permission.

Note: Messages that are older than 2 weeks can’t be deleted using this method.

Errors

Returns ModelError::BulkDeleteAmount if an attempt was made to delete either 0 or more than 100 messages.

pub async fn delete_permission( &self, http: impl AsRef<Http>, permission_type: PermissionOverwriteType, ) -> Result<()>

Deletes all permission overrides in the channel from a member or role.

Note: Requires the Manage Channel permission.

Errors

Returns Error::Http if the current user lacks permission.

pub async fn delete_reaction( &self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, user_id: Option<UserId>, reaction_type: impl Into<ReactionType>, ) -> Result<()>

Deletes the given Reaction from the channel.

Note: Requires the [Manage Messages] permission, if the current user did not perform the reaction.

Errors

Returns Error::Http if the current user lacks permission. [Manage Messages]: Permissions::MANAGE_MESSAGES

pub async fn delete_reactions( &self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, ) -> Result<()>

Deletes all of the Reactions associated with the provided message id.

Note: Requires the Manage Messages permission.

Errors

Returns Error::Http if the current user lacks permission

pub async fn edit( &mut self, cache_http: impl CacheHttp, builder: EditChannel<'_>, ) -> Result<()>

Edits the channel’s settings.

Refer to the documentation for EditChannel for a full list of methods.

Note: Requires the Manage Channels permission. Modifying permissions via EditChannel::permissions also requires the Manage Roles permission.

Examples

Change a voice channels name and bitrate:

let builder = EditChannel::new().name("test").bitrate(86400);
channel.edit(&http, builder).await;

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user lacks permission. Otherwise returns Error::Http, as well as if invalid data is given.

pub async fn edit_message( &self, cache_http: impl CacheHttp, message_id: impl Into<MessageId>, builder: EditMessage, ) -> Result<Message>

Edits a Message in the channel given its Id.

Message editing preserves all unchanged message data, with some exceptions for embeds and attachments.

Note: In most cases requires that the current user be the author of the message.

Refer to the documentation for EditMessage for information regarding content restrictions and requirements.

Errors

See EditMessage::execute for a list of possible errors, and their corresponding reasons.

pub async fn edit_thread( &mut self, cache_http: impl CacheHttp, builder: EditThread<'_>, ) -> Result<()>

Edits a thread.

Errors

Returns Error::Http if the current user lacks permission.

pub async fn edit_voice_state( &self, cache_http: impl CacheHttp, user_id: impl Into<UserId>, builder: EditVoiceState, ) -> Result<()>

Edits the voice state of a given user in a stage channel.

Note: Requires the Request to Speak permission. Also requires the Mute Members permission to suppress another user or unsuppress the current user. This is not required if suppressing the current user.

Example

Invite a user to speak.

use serenity::builder::EditVoiceState;
use serenity::model::ModelError;

// assuming the cache has been unlocked
let channel = cache.channel(channel_id).ok_or(ModelError::ItemMissing)?;

let builder = EditVoiceState::new().suppress(false);
channel.edit_voice_state(&http, user_id, builder).await?;

Errors

Returns a ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if the user lacks permission, or if invalid data is given.

pub async fn edit_own_voice_state( &self, cache_http: impl CacheHttp, builder: EditVoiceState, ) -> Result<()>

Edits the current user’s voice state in a stage channel.

Note: Requires the Request to Speak permission. The Mute Members permission is not required.

Example

Send a request to speak, then clear the request.

use serenity::builder::EditVoiceState;
use serenity::model::ModelError;

// assuming the cache has been unlocked
let channel = cache.channel(channel_id).ok_or(ModelError::ItemMissing)?;

// Send a request to speak
let builder = EditVoiceState::new().request_to_speak(true);
channel.edit_own_voice_state(&http, builder.clone()).await?;

// Clear own request to speak
let builder = builder.request_to_speak(false);
channel.edit_own_voice_state(&http, builder).await?;

Errors

If the cache is enabled, returns a ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if the user lacks permission, or if invalid data is given.

pub async fn follow( &self, http: impl AsRef<Http>, target_channel_id: impl Into<ChannelId>, ) -> Result<FollowedChannel>

Follows the News Channel

Requires [Manage Webhook] permissions on the target channel.

Note: Only available on news channels.

Errors

Returns Error::Http if the current user lacks permission. [Manage Messages]: Permissions::MANAGE_MESSAGES

pub fn guild<'a>(&self, cache: &'a impl AsRef<Cache>) -> Option<GuildRef<'a>>

Attempts to find this channel’s guild in the Cache.

pub async fn invites(&self, http: impl AsRef<Http>) -> Result<Vec<RichInvite>>

Gets all of the channel’s invites.

Requires the Manage Channels permission.

Errors

Returns Error::Http if the current user lacks permission.

pub fn is_nsfw(&self) -> bool

👎Deprecated: Use the GuildChannel::nsfw field

Determines if the channel is NSFW.

pub async fn message( &self, cache_http: impl CacheHttp, message_id: impl Into<MessageId>, ) -> Result<Message>

Gets a message from the channel.

Requires the Read Message History permission.

Errors

Returns Error::Http if the current user lacks permission, or if a message with the given Id does not exist in the channel.

pub async fn messages( &self, cache_http: impl CacheHttp, builder: GetMessages, ) -> Result<Vec<Message>>

Gets messages from the channel.

Note: If the user does not have the Read Message History permission, returns an empty Vec.

Errors

Returns Error::Http if the current user lacks permission.

pub fn name(&self) -> &str

Returns the name of the guild channel.

pub fn permissions_for_user( &self, cache: impl AsRef<Cache>, user_id: impl Into<UserId>, ) -> Result<Permissions>

👎Deprecated: Use Guild::user_permissions_in

Calculates the permissions of a member.

The Id of the argument must be a Member of the Guild that the channel is in.

Examples

Calculate the permissions of a User who posted a Message in a channel:

#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, context: Context, msg: Message) {
        let channel = match context.cache.channel(msg.channel_id) {
            Some(channel) => channel,
            None => return,
        };

        if let Ok(permissions) = channel.permissions_for_user(&context.cache, &msg.author) {
            println!("The user's permissions: {:?}", permissions);
        }
    }
}

Errors

Returns a ModelError::GuildNotFound if the channel’s guild could not be found in the Cache.

pub fn permissions_for_role( &self, cache: impl AsRef<Cache>, role_id: impl Into<RoleId>, ) -> Result<Permissions>

👎Deprecated: this function ignores other roles the user may have as well as user-specific permissions; use Guild::user_permissions_in instead

Calculates the permissions of a role.

The Id of the argument must be a Role of the Guild that the channel is in.

Errors

Returns a ModelError::GuildNotFound if the channel’s guild could not be found in the Cache.

Returns a ModelError::RoleNotFound if the given role could not be found in the Cache.

pub async fn pin( &self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, ) -> Result<()>

Pins a Message to the channel.

Note: Requires the Manage Messages permission.

Errors

Returns Error::Http if the current user lacks permission, or if the channel already has too many pinned messages.

pub async fn pins(&self, http: impl AsRef<Http>) -> Result<Vec<Message>>

Gets all channel’s pins.

Note: If the current user lacks the Read Message History permission an empty Vec will be returned.

Errors

Returns Error::Http if the current user lacks permission to view the channel.

pub async fn reaction_users( &self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, reaction_type: impl Into<ReactionType>, limit: Option<u8>, after: impl Into<Option<UserId>>, ) -> Result<Vec<User>>

Gets the list of Users who have reacted to a Message with a certain Emoji.

The default limit is 50 - specify otherwise to receive a different maximum number of users. The maximum that may be retrieve at a time is 100, if a greater number is provided then it is automatically reduced.

The optional after attribute is to retrieve the users after a certain user. This is useful for pagination.

Note: Requires the Read Message History permission.

Note: If the passed reaction_type is a custom guild emoji, it must contain the name. So, Emoji or EmojiIdentifier will always work, ReactionType only if ReactionType::Custom::name is Some, and EmojiId will never work.

Errors

Returns Error::Http if the current user lacks permission.

pub async fn say( &self, cache_http: impl CacheHttp, content: impl Into<String>, ) -> Result<Message>

Sends a message with just the given message content in the channel.

Note: Message content must be under 2000 unicode code points.

Errors

Returns a ModelError::MessageTooLong if the content length is over the above limit. See CreateMessage::execute for more details.

pub async fn send_files( self, cache_http: impl CacheHttp, files: impl IntoIterator<Item = CreateAttachment>, builder: CreateMessage, ) -> Result<Message>

Sends file(s) along with optional message contents.

Refer to ChannelId::send_files for examples and more information.

Errors

See CreateMessage::execute for a list of possible errors, and their corresponding reasons.

pub async fn send_message( &self, cache_http: impl CacheHttp, builder: CreateMessage, ) -> Result<Message>

Sends a message to the channel.

Refer to the documentation for CreateMessage for information regarding content restrictions and requirements.

Errors

See CreateMessage::execute for a list of possible errors, and their corresponding reasons.

pub fn start_typing(&self, http: &Arc<Http>) -> Typing

Starts typing in the channel for an indefinite period of time.

Returns Typing that is used to trigger the typing. Typing::stop must be called on the returned struct to stop typing. Note that on some clients, typing may persist for a few seconds after Typing::stop is called. Typing is also stopped when the struct is dropped.

If a message is sent while typing is triggered, the user will stop typing for a brief period of time and then resume again until either Typing::stop is called or the struct is dropped.

This should rarely be used for bots, although it is a good indicator that a long-running command is still being processed.

Examples

// Initiate typing (assuming http is `Arc<Http>` and `channel` is bound)
let typing = channel.start_typing(&http);

// Run some long-running process
long_process();

// Stop typing
typing.stop();

pub async fn unpin( &self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, ) -> Result<()>

Unpins a Message in the channel given by its Id.

Requires the Manage Messages permission.

Errors

Returns Error::Http if the current user lacks permission.

pub async fn webhooks(&self, http: impl AsRef<Http>) -> Result<Vec<Webhook>>

Retrieves the channel’s webhooks.

Note: Requires the Manage Webhooks permission.

Errors

Returns Error::Http if the current user lacks permission.

pub fn members(&self, cache: impl AsRef<Cache>) -> Result<Vec<Member>>

Retrieves Members from the current channel.

ChannelType::Voice and ChannelType::Stage returns Members using the channel.

ChannelType::Text and ChannelType::News return Members that can read the channel.

Errors

Other ChannelTypes lack the concept of Members and will return: ModelError::InvalidChannelType.

pub fn await_reply( &self, shard_messenger: impl AsRef<ShardMessenger>, ) -> MessageCollector

Returns a builder which can be awaited to obtain a message or stream of messages sent in this guild channel.

pub fn await_replies( &self, shard_messenger: impl AsRef<ShardMessenger>, ) -> MessageCollector

Same as Self::await_reply.

pub fn await_reaction( &self, shard_messenger: impl AsRef<ShardMessenger>, ) -> ReactionCollector

Returns a stream builder which can be awaited to obtain a reaction or stream of reactions sent by this guild channel.

pub fn await_reactions( &self, shard_messenger: impl AsRef<ShardMessenger>, ) -> ReactionCollector

Same as Self::await_reaction.

pub async fn create_webhook( &self, cache_http: impl CacheHttp, builder: CreateWebhook<'_>, ) -> Result<Webhook>

Creates a webhook in the channel.

Errors

Returns ModelError::InvalidChannelType if the corresponding channel is not of type ChannelType::Text or ChannelType::News.

See CreateWebhook::execute for a detailed list of other possible errors,

pub async fn get_stage_instance( &self, http: impl AsRef<Http>, ) -> Result<StageInstance>

Gets a stage instance.

Errors

Returns ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if there is no stage instance currently.

pub async fn create_stage_instance( &self, cache_http: impl CacheHttp, builder: CreateStageInstance<'_>, ) -> Result<StageInstance>

Creates a stage instance.

Errors

Returns ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if there is already a stage instance currently.

pub async fn edit_stage_instance( &self, cache_http: impl CacheHttp, builder: EditStageInstance<'_>, ) -> Result<StageInstance>

Edits the stage instance

Errors

Returns ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if the channel is not a stage channel, or there is no stage instance currently.

pub async fn delete_stage_instance(&self, http: impl AsRef<Http>) -> Result<()>

Deletes a stage instance.

Errors

Returns ModelError::InvalidChannelType if the channel is not a stage channel.

Returns Error::Http if there is no stage instance currently.

pub async fn create_thread_from_message( &self, cache_http: impl CacheHttp, message_id: impl Into<MessageId>, builder: CreateThread<'_>, ) -> Result<GuildChannel>

Creates a public thread that is connected to a message.

Errors

Returns Error::Http if the current user lacks permission, or if invalid data is given.

pub async fn create_thread( &self, cache_http: impl CacheHttp, builder: CreateThread<'_>, ) -> Result<GuildChannel>

Creates a thread that is not connected to a message.

Errors

Returns Error::Http if the current user lacks permission, or if invalid data is given.

pub async fn create_forum_post( &self, cache_http: impl CacheHttp, builder: CreateForumPost<'_>, ) -> Result<GuildChannel>

Creates a post in a forum channel.

Errors

Returns Error::Http if the current user lacks permission, or if invalid data is given.

Trait Implementations

impl ArgumentConvert for GuildChannel

Look up a GuildChannel by a string case-insensitively.

Lookup is done by the global cache, hence the cache feature needs to be enabled.

For more information, see the ArgumentConvert implementation for Channel

type Err = GuildChannelParseError

The associated error which can be returned from parsing.

fn convert<'life0, 'async_trait>( ctx: impl 'async_trait + CacheHttp, guild_id: Option<GuildId>, channel_id: Option<ChannelId>, s: &'life0 str, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Err>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Parses a string s as a command parameter of this type.

impl Clone for GuildChannel

fn clone(&self) -> GuildChannel

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GuildChannel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GuildChannel

fn default() -> GuildChannel

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GuildChannel

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for GuildChannel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the channel, creating a mention of it.

impl From<&GuildChannel> for ChannelId

fn from(public_channel: &GuildChannel) -> ChannelId

Gets the Id of a guild channel.

impl From<GuildChannel> for ChannelId

fn from(public_channel: GuildChannel) -> ChannelId

Gets the Id of a guild channel.

impl Mentionable for GuildChannel

fn mention(&self) -> Mention

Creates a Mention that will be able to notify or create a link to the item.

impl Serialize for GuildChannel

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.