Struct ChannelId

pub struct ChannelId(/* private fields */);

An identifier for a Channel

Implementations

impl ChannelId

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

Broadcasts that the current user is typing to a channel for the next 5 seconds.

After 5 seconds, another request must be made to continue broadcasting that the current user is typing.

This should rarely be used for bots, and should likely only be used for signifying that a long-running command is still being executed.

Note: Requires the Send Messages permission.

Examples

use serenity::model::id::ChannelId;

let _successful = ChannelId::new(7).broadcast_typing(&http).await;

Errors

Returns Error::Http if the current user lacks permission to send messages to this channel.

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.

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 the channel.

Refer to the documentation for GuildChannel::create_permission for more information.

Requires the Manage Channels permission.

Errors

Returns Error::Http if the current user lacks permission, or if an invalid value is set.

pub async fn create_reaction( self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, reaction_type: impl Into<ReactionType>, ) -> Result<()>

React to a Message with a custom Emoji or unicode character.

Message::react may be a more suited method of reacting in most cases.

Requires the Add Reactions permission, if the current user is the first user to perform a react with a certain emoji.

Errors

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

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

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

Note: Requires the Manage Channels permission.

Errors

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

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

Deletes a Message given its Id.

Refer to Message::delete for more information.

Requires the Manage Messages permission, if the current user is not the author of the message.

Errors

Returns Error::Http if the current user lacks permission to delete the message.

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

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

The Discord API supports deleting between 2 and 100 messages at once. This function also handles the case of a single message by calling delete_message internally.

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 0 or more than 100 messages.

Also will return Error::Http if the current user lacks permission to delete 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 did not perform the reaction, and lacks permission.

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 delete_reaction_emoji( self, http: impl AsRef<Http>, message_id: impl Into<MessageId>, reaction_type: impl Into<ReactionType>, ) -> Result<()>

Deletes all Reactions of the given emoji to a message within the channel.

Note: Requires the Manage Messages permission.

Errors

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

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

Edits a 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 channel’s name and bitrate:

let builder = EditChannel::new().name("test").bitrate(64000);
channel_id.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 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 Webhook]: Permissions::MANAGE_WEBHOOKS

pub fn to_channel_cached(self, cache: &Cache) -> Option<GuildChannelRef<'_>>

👎Deprecated: Use Cache::guild and Guild::channels instead

Attempts to find a GuildChannel by its Id in the cache.

pub async fn to_channel(self, cache_http: impl CacheHttp) -> Result<Channel>

First attempts to retrieve the channel from the temp_cache if enabled, otherwise performs a HTTP request.

It is recommended to first check if the channel is accessible via Cache::guild and Guild::members, although this requires a GuildId.

Errors

Returns Error::Http if the channel retrieval request failed.

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 async fn message( self, cache_http: impl CacheHttp, message_id: impl Into<MessageId>, ) -> Result<Message>

Gets a message from the channel.

If the cache feature is enabled the cache will be checked first. If not found it will resort to an http request.

Requires the Read Message History permission.

Errors

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

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 messages_iter<H: AsRef<Http>>( self, http: H, ) -> impl Stream<Item = Result<Message>>

Streams over all the messages in a channel.

This is accomplished and equivalent to repeated calls to Self::messages. A buffer of at most 100 messages is used to reduce the number of calls necessary.

The stream returns the newest message first, followed by older messages.

Examples

use serenity::futures::StreamExt;
use serenity::model::channel::MessagesIter;

let mut messages = channel_id.messages_iter(&ctx).boxed();
while let Some(message_result) = messages.next().await {
    match message_result {
        Ok(message) => println!("{} said \"{}\".", message.author.name, message.content,),
        Err(error) => eprintln!("Uh oh! Error: {}", error),
    }
}

pub async fn name(self, cache_http: impl CacheHttp) -> Result<String>

Returns the name of whatever channel this id holds.

DM channels don’t have a name, so a name is generated according to PrivateChannel::name().

Errors

Same as Self::to_channel().

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 has too many pinned messages.

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

Crossposts a Message.

Requires either to be the message author or to have manage Manage Messages permissions on this channel.

Note: Only available on news channels.

Errors

Returns Error::Http if the current user lacks permission, and if the user is not the author of the message.

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

Gets the list of Messages which are pinned to the channel.

Note: Returns an empty Vec if the current user does not have the Read Message History permission.

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 to read messages in the channel.

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. The filename must be specified.

Message contents may be passed using the builder argument.

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

Examples

Send files with the paths /path/to/file.jpg and /path/to/file2.jpg:

use serenity::builder::{CreateAttachment, CreateMessage};
use serenity::model::id::ChannelId;

let channel_id = ChannelId::new(7);

let paths = [
    CreateAttachment::path("/path/to/file.jpg").await?,
    CreateAttachment::path("path/to/file2.jpg").await?,
];

let builder = CreateMessage::new().content("some files");
channel_id.send_files(&http, paths, builder).await?;

Send files using File:

use serenity::builder::{CreateAttachment, CreateMessage};
use serenity::model::id::ChannelId;
use tokio::fs::File;

let channel_id = ChannelId::new(7);

let f1 = File::open("my_file.jpg").await?;
let f2 = File::open("my_file2.jpg").await?;

let files = [
    CreateAttachment::file(&f1, "my_file.jpg").await?,
    CreateAttachment::file(&f2, "my_file2.jpg").await?,
];

let builder = CreateMessage::new().content("some files");
let _ = channel_id.send_files(&http, files, builder).await;

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>`)
let typing = ChannelId::new(7).start_typing(&http);

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

// Stop typing
typing.stop();

Errors

Returns Error::Http if the current user lacks permission to send messages in this channel.

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 async fn create_webhook( self, cache_http: impl CacheHttp, builder: CreateWebhook<'_>, ) -> Result<Webhook>

Creates a webhook in the channel.

Errors

See CreateWebhook::execute for a detailed list of possible errors.

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 in this 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 builder which can be awaited to obtain a reaction or stream of reactions sent in this channel.

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

Same as Self::await_reaction.

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

Gets a stage instance.

Errors

Returns Error::Http if the channel is not a stage channel, or 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 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 edit_thread( self, cache_http: impl CacheHttp, builder: EditThread<'_>, ) -> Result<GuildChannel>

Edits a thread.

Errors

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

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

Deletes a stage instance.

Errors

Returns Error::Http if the channel is not a stage channel, or 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.

pub async fn get_thread_members( self, http: impl AsRef<Http>, ) -> Result<Vec<ThreadMember>>

Gets the thread members, if this channel is a thread.

Errors

It may return an Error::Http if the channel is not a thread channel

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

Joins the thread, if this channel is a thread.

Errors

It may return an Error::Http if the channel is not a thread channel

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

Leaves the thread, if this channel is a thread.

Errors

It may return an Error::Http if the channel is not a thread channel

pub async fn add_thread_member( self, http: impl AsRef<Http>, user_id: UserId, ) -> Result<()>

Adds a thread member, if this channel is a thread.

Errors

It may return an Error::Http if the channel is not a thread channel

pub async fn remove_thread_member( self, http: impl AsRef<Http>, user_id: UserId, ) -> Result<()>

Removes a thread member, if this channel is a thread.

Errors

It may return an Error::Http if the channel is not a thread channel

pub async fn get_thread_member( self, http: impl AsRef<Http>, user_id: UserId, with_member: bool, ) -> Result<ThreadMember>

Gets a thread member, if this channel is a thread.

with_member controls if ThreadMember::member should be Some

Errors

It may return an Error::Http if the channel is not a thread channel

pub async fn get_archived_private_threads( self, http: impl AsRef<Http>, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets private archived threads of a channel.

Errors

It may return an Error::Http if the bot doesn’t have the permission to get it.

pub async fn get_archived_public_threads( self, http: impl AsRef<Http>, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets public archived threads of a channel.

Errors

It may return an Error::Http if the bot doesn’t have the permission to get it.

pub async fn get_joined_archived_private_threads( self, http: impl AsRef<Http>, before: Option<u64>, limit: Option<u64>, ) -> Result<ThreadsData>

Gets private archived threads joined by the current user of a channel.

Errors

It may return an Error::Http if the bot doesn’t have the permission to get it.

pub async fn get_poll_answer_voters( self, http: impl AsRef<Http>, message_id: MessageId, answer_id: AnswerId, after: Option<UserId>, limit: Option<u8>, ) -> Result<Vec<User>>

Get a list of users that voted for this specific answer.

Errors

If the message does not have a poll.

pub async fn end_poll( self, http: impl AsRef<Http>, message_id: MessageId, ) -> Result<Message>

Ends the Poll on a given MessageId, if there is one.

Errors

If the message does not have a poll, or if the poll was not created by the current user.

impl ChannelId

pub const fn new(id: u64) -> Self

Creates a new ChannelId from a u64.

Panics

Panics if id is zero.

pub const fn get(self) -> u64

Retrieves the inner id as a u64.

pub fn created_at(&self) -> Timestamp

Retrieves the time that the ChannelId was created.

Trait Implementations

impl AsRef<ChannelId> for ChannelId

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for ChannelId

fn clone(&self) -> ChannelId

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ChannelId

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

Formats the value using the given formatter.

impl Default for ChannelId

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ChannelId

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ChannelId

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

Formats the value using the given formatter.

impl From<&Channel> for ChannelId

fn from(channel: &Channel) -> ChannelId

Gets the Id of a Channel.

impl<'a> From<&'a ChannelId> for ChannelId

fn from(id: &'a ChannelId) -> ChannelId

Converts to this type from the input type.

impl From<&GuildChannel> for ChannelId

fn from(public_channel: &GuildChannel) -> ChannelId

Gets the Id of a guild channel.

impl From<&PrivateChannel> for ChannelId

fn from(private_channel: &PrivateChannel) -> ChannelId

Gets the Id of a private channel.

impl From<&WebhookChannel> for ChannelId

fn from(webhook_channel: &WebhookChannel) -> ChannelId

Gets the Id of a webhook channel.

impl From<Channel> for ChannelId

fn from(channel: Channel) -> ChannelId

Gets the Id of a Channel.

impl From<ChannelId> for Mention

fn from(value: ChannelId) -> Self

Converts to this type from the input type.

impl From<ChannelId> for NonZeroI64

fn from(id: ChannelId) -> NonZeroI64

Converts to this type from the input type.

impl From<ChannelId> for NonZeroU64

fn from(id: ChannelId) -> NonZeroU64

Converts to this type from the input type.

impl From<ChannelId> for i64

fn from(id: ChannelId) -> i64

Converts to this type from the input type.

impl From<ChannelId> for u64

fn from(id: ChannelId) -> u64

Converts to this type from the input type.

impl From<GuildChannel> for ChannelId

fn from(public_channel: GuildChannel) -> ChannelId

Gets the Id of a guild channel.

impl From<NonZero<u64>> for ChannelId

fn from(id: NonZeroU64) -> ChannelId

Converts to this type from the input type.

impl From<PrivateChannel> for ChannelId

fn from(private_channel: PrivateChannel) -> ChannelId

Gets the Id of a private channel.

impl From<WebhookChannel> for ChannelId

fn from(webhook_channel: WebhookChannel) -> ChannelId

Gets the Id of a webhook channel.

impl From<u64> for ChannelId

fn from(id: u64) -> ChannelId

Converts to this type from the input type.

impl FromStr for ChannelId

type Err = <u64 as FromStr>::Err

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for ChannelId

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for ChannelId

fn cmp(&self, other: &ChannelId) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<u64> for ChannelId

fn eq(&self, u: &u64) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for ChannelId

fn eq(&self, other: &ChannelId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for ChannelId

fn partial_cmp(&self, other: &ChannelId) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for ChannelId

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for ChannelId

impl Eq for ChannelId

impl StructuralPartialEq for ChannelId