Struct User

#[non_exhaustive]
pub struct User {

    pub id: UserId,
    pub name: String,
    pub discriminator: Option<NonZeroU16>,
    pub global_name: Option<String>,
    pub avatar: Option<ImageHash>,
    pub bot: bool,
    pub system: bool,
    pub mfa_enabled: bool,
    pub banner: Option<ImageHash>,
    pub accent_colour: Option<Colour>,
    pub locale: Option<String>,
    pub verified: Option<bool>,
    pub email: Option<String>,
    pub flags: UserPublicFlags,
    pub premium_type: PremiumType,
    pub public_flags: Option<UserPublicFlags>,
    pub member: Option<Box<PartialMember>>,
}

Information about a user.

Discord docs, existence of additional partial member field documented here.

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: UserId

The unique Id of the user. Can be used to calculate the account’s creation date.

name: String

The account’s username. Changing username will trigger a discriminator change if the username+discriminator pair becomes non-unique. Unless the account has migrated to a next generation username, which does not have a discriminant.

discriminator: Option<NonZeroU16>

The account’s discriminator to differentiate the user from others with the same Self::name. The name+discriminator pair is always unique. If the discriminator is not present, then this is a next generation username which is implicitly unique.

global_name: Option<String>

The account’s display name, if it is set. For bots this is the application name.

avatar: Option<ImageHash>

Optional avatar hash.

bot: bool

Indicator of whether the user is a bot.

system: bool

Whether the user is an Official Discord System user (part of the urgent message system).

mfa_enabled: bool

Whether the user has two factor enabled on their account

banner: Option<ImageHash>

Optional banner hash.

Note: This will only be present if the user is fetched via Rest API, e.g. with crate::http::Http::get_user.

accent_colour: Option<Colour>

The user’s banner colour encoded as an integer representation of hexadecimal colour code

Note: This will only be present if the user is fetched via Rest API, e.g. with crate::http::Http::get_user.

locale: Option<String>

The user’s chosen language option

verified: Option<bool>

Whether the email on this account has been verified

Requires Scope::Email

email: Option<String>

The user’s email

Requires Scope::Email

flags: UserPublicFlags

The flags on a user’s account

premium_type: PremiumType

The type of Nitro subscription on a user’s account

public_flags: Option<UserPublicFlags>

The public flags on a user’s account

member: Option<Box<PartialMember>>

Only included in Message::mentions for messages from the gateway.

Discord docs.

Implementations

impl User

pub fn avatar_url(&self) -> Option<String>

Returns the formatted URL of the user’s icon, if one exists.

This will produce a WEBP image URL, or GIF if the user has a GIF avatar.

pub fn banner_url(&self) -> Option<String>

Returns the formatted URL of the user’s banner, if one exists.

This will produce a WEBP image URL, or GIF if the user has a GIF banner.

Note: This will only be present if the user is fetched via Rest API, e.g. with crate::http::Http::get_user.

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

Creates a direct message channel between the current user and the user. This can also retrieve the channel if one already exists.

Errors

See UserId::create_dm_channel for what errors may be returned.

pub fn created_at(&self) -> Timestamp

Retrieves the time that this user was created at.

pub fn default_avatar_url(&self) -> String

Returns the formatted URL to the user’s default avatar URL.

This will produce a PNG URL.

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

Sends a message to a user through a direct message channel. This is a channel that can only be accessed by you and the recipient.

Examples

See UserId::direct_message for examples.

Errors

See UserId::direct_message for errors.

pub fn display_name(&self) -> &str

Calculates the user’s display name.

The global name takes priority over the user’s username if it exists.

Note: Guild specific information is not included as this is only available on the Member.

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

This is an alias of Self::direct_message.

pub fn face(&self) -> String

Retrieves the URL to the user’s avatar, falling back to the default avatar if needed.

This will call Self::avatar_url first, and if that returns None, it then falls back to Self::default_avatar_url.

pub fn static_face(&self) -> String

Retrieves the URL to the static version of the user’s avatar, falling back to the default avatar if needed.

This will call Self::static_avatar_url first, and if that returns None, it then falls back to Self::default_avatar_url.

pub async fn has_role( &self, cache_http: impl CacheHttp, guild_id: impl Into<GuildId>, role: impl Into<RoleId>, ) -> Result<bool>

Check if a user has a Role. This will retrieve the Guild from the Cache if it is available, and then check if that guild has the given Role.

Examples

Check if a guild has a Role by Id:

// Assumes a 'guild_id' and `role_id` have already been bound
let _ = message.author.has_role(guild_id, role_id);

Errors

Returns an Error::Http if the given Guild is unavailable, if that Role does not exist in the given Guild, or if the given User is not in that Guild.

May also return an Error::Json if there is an error in deserializing the API response.

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

Refreshes the information about the user.

Replaces the instance with the data retrieved over the REST API.

Errors

See UserId::to_user for what errors may be returned.

pub fn static_avatar_url(&self) -> Option<String>

Returns a static formatted URL of the user’s icon, if one exists.

This will always produce a WEBP image URL.

pub fn tag(&self) -> String

Returns the “tag” for the user.

The “tag” is defined as “username#discriminator”, such as “zeyla#5479”.

Examples

Make a command to tell the user what their tag is:

#[serenity::async_trait]
impl EventHandler for Handler {
    async fn message(&self, context: Context, msg: Message) {
        if msg.content == "!mytag" {
            let content = format!("Your tag is: {}", msg.author.tag());
            let _ = msg.channel_id.say(&context.http, &content).await;
        }
    }
}

pub async fn nick_in( &self, cache_http: impl CacheHttp, guild_id: impl Into<GuildId>, ) -> Option<String>

Returns the user’s nickname in the given guild_id.

If none is used, it returns None.

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 by this user.

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 by this user.

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

Same as Self::await_reaction.

Trait Implementations

impl ArgumentConvert for User

Look up a user by a string case-insensitively.

Requires the cache feature to be enabled. If a user is not in cache, they will not be found!

The lookup strategy is as follows (in order):

1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name#discrim.
4. Lookup by name

type Err = UserParseError

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 User

fn clone(&self) -> User

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for User

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

Formats the value using the given formatter.

impl Default for User

fn default() -> User

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for User

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for User

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

Formats a string which will mention the user.

impl From<&User> for CreateEmbedAuthor

fn from(user: &User) -> Self

Converts to this type from the input type.

impl From<&User> for UserId

fn from(user: &User) -> UserId

Gets the Id of a User.

impl From<CurrentUser> for User

fn from(user: CurrentUser) -> Self

Converts to this type from the input type.

impl From<User> for CreateEmbedAuthor

fn from(user: User) -> Self

Converts to this type from the input type.

impl From<User> for UserId

fn from(user: User) -> UserId

Gets the Id of a User.

impl Hash for User

fn hash<H: Hasher>(&self, hasher: &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 Mentionable for User

fn mention(&self) -> Mention

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

impl PartialEq for User

fn eq(&self, other: &Self) -> 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 Serialize for User

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for User