Struct serenity::model::id::ChannelId

pub struct ChannelId(pub u64);

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(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<F>(
    &self,
    http: impl AsRef<Http>,
    f: F
) -> Result<RichInvite> where
    F: FnOnce(&mut CreateInvite) -> &mut CreateInvite, 

Creates an invite leading to the given channel.

Note: Requres the Create Invite permission.

Errors

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

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, It>(
    self,
    http: impl AsRef<Http>,
    message_ids: It
) -> Result<()> where
    T: AsRef<MessageId>,
    It: IntoIterator<Item = T>, 

Deletes all messages by Ids from the given vector in the given 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.

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_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<F>(self, http: impl AsRef<Http>, f: F) -> Result<GuildChannel> where
    F: FnOnce(&mut EditChannel) -> &mut EditChannel, 

Edits the settings of a Channel, optionally setting new values.

Refer to EditChannel’s documentation for its methods.

Requires the Manage Channel permission.

Examples

Change a voice channel’s name and bitrate:

// assuming a `channel_id` has been bound

channel_id.edit(&http, |c| c.name("test").bitrate(64000)).await;

Errors

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

pub async fn edit_message<F>(
    self,
    http: impl AsRef<Http>,
    message_id: impl Into<MessageId>,
    f: F
) -> Result<Message> where
    F: FnOnce(&mut EditMessage) -> &mut EditMessage, 

Edits a Message in the channel given its Id.

Message editing preserves all unchanged message data.

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

Note: Requires that the current user be the author of the message.

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the the limit, containing the number of unicode code points over the limit.

pub async fn to_channel_cached(
    self,
    cache: impl AsRef<Cache>
) -> Option<Channel>

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

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

First attempts to find a Channel by its Id in the cache, upon failure requests it via the REST API.

Note: If the cache-feature is enabled permissions will be checked and upon owning the required permissions the HTTP-request will be issued.

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,
    http: impl AsRef<Http>,
    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.

pub async fn messages<F>(
    self,
    http: impl AsRef<Http>,
    builder: F
) -> Result<Vec<Message>> where
    F: FnOnce(&mut GetMessages) -> &mut GetMessages, 

Gets messages from the channel.

Refer to GetMessages for more information on how to use builder.

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 does not have permission to view the channel.

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::model::channel::MessagesIter;
use serenity::futures::StreamExt;

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: impl AsRef<Cache>) -> Option<String>

Returns the name of whatever channel this id holds.

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 announcements channels.

Errors

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.

Errors

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

pub async fn say(
    self,
    http: impl AsRef<Http>,
    content: impl Display
) -> Result<Message>

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

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the above limit, containing the number of unicode code points over the limit.

pub async fn send_files<'a, F, T, It>(
    self,
    http: impl AsRef<Http>,
    files: It,
    f: F
) -> Result<Message> where
    F: FnOnce(&'b mut CreateMessage<'a>) -> &'b mut CreateMessage<'a>,
    T: Into<AttachmentType<'a>>,
    It: IntoIterator<Item = T>, 

Sends file(s) along with optional message contents. The filename must be specified.

Message contents may be passed by using the CreateMessage::content method.

The Attach Files and Send Messages permissions are required.

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

Examples

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

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

let channel_id = ChannelId(7);

let paths = vec!["/path/to/file.jpg", "path/to/file2.jpg"];

let _ = channel_id.send_files(&http, paths, |m| {
    m.content("a file")
})
.await;

Send files using File:

use serenity::model::id::ChannelId;
use tokio::fs::File;

let channel_id = ChannelId(7);

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

let files = vec![(&f1, "my_file.jpg"), (&f2, "my_file2.jpg")];

let _ = channel_id.send_files(&http, files, |m| {
    m.content("a file")
})
.await;

Errors

If the content of the message is over the above limit, then a ModelError::MessageTooLong will be returned, containing the number of unicode code points over the limit.

Returns an HttpError::UnsuccessfulRequest(ErrorResponse) if the file(s) are too large to send.

pub async fn send_message<'a, F>(
    self,
    http: impl AsRef<Http>,
    f: F
) -> Result<Message> where
    F: FnOnce(&'b mut CreateMessage<'a>) -> &'b mut CreateMessage<'a>, 

Sends a message to the channel.

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

Requires the Send Messages permission.

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

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the above limit, containing the number of unicode code points over the limit.

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

pub fn start_typing(self, http: &Arc<Http>) -> Result<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(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,
    http: impl AsRef<Http>,
    name: impl Display
) -> Result<Webhook>

Creates a webhook with only a name.

Errors

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

pub async fn create_webhook_with_avatar<'a>(
    &self,
    http: impl AsRef<Http>,
    name: impl Display,
    avatar: impl Into<AttachmentType<'a>>
) -> Result<Webhook>

Creates a webhook with a name and an avatar.

Errors

In addition to the reasons Self::create_webhook may return an Error::Http, if the image is too large.

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

This is supported on crate feature collector only.

Returns a future that will await one message sent in this channel.

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

This is supported on crate feature collector only.

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

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

This is supported on crate feature collector only.

Await a single reaction in this guild.

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

This is supported on crate feature collector only.

Returns a stream builder which can be awaited to obtain a stream of reactions sent in this channel.

impl ChannelId

pub fn created_at(&self) -> DateTime<Utc>

Retrieves the time that the Id was created at.

pub fn as_u64(&self) -> &u64

Immutably borrow inner Id.

pub fn as_mut_u64(&mut self) -> &mut u64

Mutably borrow inner Id.

Trait Implementations

impl AsRef<ChannelId> for ChannelId

fn as_ref(&self) -> &Self

Performs the conversion.

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() -> ChannelId

Returns the “default value” for a type.

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

fn deserialize<D: Deserializer<'de>>(
    deserializer: D
) -> StdResult<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for ChannelId

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

Formats the value using the given formatter.

impl<'a> From<&'a 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

Performs the conversion.

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

fn from(public_channel: &GuildChannel) -> ChannelId

Gets the Id of a guild channel.

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

fn from(private_channel: &PrivateChannel) -> ChannelId

Gets the Id of a private 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

Performs the conversion.

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<u64> for ChannelId

fn from(id_as_u64: u64) -> ChannelId

Performs the conversion.

impl FromStr for ChannelId

type Err = ChannelIdParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> StdResult<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, 

Feeds a slice of this type into the given Hasher.

impl Mentionable for ChannelId

fn mention(&self) -> Mention

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

impl Ord for ChannelId

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

This method returns an Ordering between self and other.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl PartialEq<ChannelId> for ChannelId

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialEq<u64> for ChannelId

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

impl PartialOrd<ChannelId> for ChannelId

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

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

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method 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 StructuralEq for ChannelId

impl StructuralPartialEq for ChannelId