User Resource

Reference for Discord user objects and management endpoints.

Users in Discord are generally considered the base entity. Users can spawn across the entire platform, be members of guilds, participate in text and voice chat, and much more. Users are separated by a distinction of “bot” vs “normal.” Although they are similar, bot users are automated users that are “owned” by another user. Unlike normal users, bot users do not have a limitation on the number of Guilds they can be a part of.

Usernames and Nicknames

Discord enforces the following restrictions for usernames and nicknames:

1. Names can contain most valid unicode characters. We limit some zero-width and non-rendering characters.
2. Usernames must be between 2 and 32 characters long.
3. Nicknames must be between 1 and 32 characters long.
4. Names are sanitized and trimmed of leading, trailing, and excessive internal whitespace.

The following restrictions are additionally enforced for usernames:

1. Usernames cannot contain the following substrings: @, #, :, ```, discord
2. Usernames cannot be: everyone, here

There are other rules and restrictions not shared here for the sake of spam and abuse mitigation, but the majority of users won’t encounter them. It’s important to properly handle all error messages returned by Discord when editing or updating names.

User Object

User Structure

Field	Type	Description	Required OAuth2 Scope
id	snowflake	the user’s id	identify
username	string	the user’s username, not unique across the platform	identify
discriminator	string	the user’s Discord-tag	identify
global_name	?string	the user’s display name, if it is set	identify
avatar	?string	the user’s avatar hash	identify
bot?	boolean	whether the user belongs to an OAuth2 application	identify
system?	boolean	whether the user is an Official Discord System user (part of the urgent message system)	identify
mfa_enabled?	boolean	whether the user has two factor enabled on their account	identify
banner?	?string	the user’s banner hash	identify
accent_color?	?integer	the user’s banner color encoded as an integer representation of hexadecimal color code	identify
locale?	string	the user’s chosen language option	identify
verified?	boolean	whether the email on this account has been verified	email
email?	?string	the user’s email	email
flags?	integer	the flags on a user’s account	identify
premium_type?	integer	the type of Nitro subscription on a user’s account	identify.premium
public_flags?	integer	the public flags on a user’s account	identify
avatar_decoration_data?	?avatar decoration data object	data for the user’s avatar decoration	identify
collectibles?	?collectibles object	data for the user’s collectibles	identify
primary_guild?	?user primary guild object	the user’s primary guild	identify

Example User

{
  "id": "80351110224678912",
  "username": "Nelly",
  "global_name": null,
  "discriminator": "1337",
  "avatar": "8342729096ea3675442027381ff50dfe",
  "verified": true,
  "email": "[e-mail]",
  "flags": 64,
  "banner": "06c16474723fe537c283b8efa61a30c8",
  "accent_color": 16711680,
  "premium_type": 0,
  "public_flags": 64,
  "avatar_decoration_data": {
    "sku_id": "1144058844004233369",
    "asset": "a_fed43ab12698df65902ba06727e20c0e"
  },
  "collectibles": {
    "nameplate": {
      "sku_id": "2247558840304243311",
      "asset": "nameplates/nameplates/twilight/",
      "label": "",
      "palette": "cobalt"
    }
  },
  "primary_guild": {
    "identity_guild_id": "1234647491267808778",
    "identity_enabled": true,
    "tag": "DISC",
    "badge": "7d1734ae5a615e82bc7a4033b98fade8"
  }
}

User Flags

Value	Name	Description
1 << 0	STAFF	Discord Employee
1 << 1	PARTNER	Partnered Server Owner
1 << 2	HYPESQUAD	HypeSquad Events Member
1 << 3	BUG_HUNTER_LEVEL_1	Bug Hunter Level 1
1 << 6	HYPESQUAD_ONLINE_HOUSE_1	House Bravery Member
1 << 7	HYPESQUAD_ONLINE_HOUSE_2	House Brilliance Member
1 << 8	HYPESQUAD_ONLINE_HOUSE_3	House Balance Member
1 << 9	PREMIUM_EARLY_SUPPORTER	Early Nitro Supporter
1 << 10	TEAM_PSEUDO_USER	User is a team
1 << 14	BUG_HUNTER_LEVEL_2	Bug Hunter Level 2
1 << 16	VERIFIED_BOT	Verified Bot
1 << 17	VERIFIED_DEVELOPER	Early Verified Bot Developer
1 << 18	CERTIFIED_MODERATOR	Moderator Programs Alumni
1 << 19	BOT_HTTP_INTERACTIONS	Bot uses only HTTP interactions and is shown in the online member list

Premium Types

Premium types denote the level of premium a user has. Visit the Nitro page to learn more about the premium plans we currently offer.

Value	Name
0	None
1	Nitro Classic
2	Nitro
3	Nitro Basic

User Primary Guild

Field	Type	Description
identity_guild_id	?snowflake	the id of the user’s primary guild
identity_enabled	?boolean	whether the user is displaying the primary guild’s server tag. This can be null if the system clears the identity, e.g. the server no longer supports tags. This will be false if the user manually removes their tag.
tag	?string	the text of the user’s server tag. Limited to 4 characters
badge	?string	the server tag badge hash

Avatar Decoration Data Object

The data for the user’s avatar decoration.

Avatar Decoration Data Structure

Field	Type	Description
asset	string	the avatar decoration hash
sku_id	snowflake	id of the avatar decoration’s SKU

Collectibles

The collectibles the user has, excluding Avatar Decorations and Profile Effects.

Collectible Structure

Field	Type	Description
nameplate?	object	object mapping of nameplate data

Nameplate

The nameplate the user has.

Nameplate Structure

Field	Type	Description
sku_id	snowflake	id of the nameplate SKU
asset	string	path to the nameplate asset
label	string	the label of this nameplate. Currently unused
palette	string	background color of the nameplate, one of: crimson, berry, sky, teal, forest, bubble_gum, violet, cobalt, clover, lemon, white

Connection Object

The connection object that the user has attached.

Connection Structure

Field	Type	Description
id	string	id of the connection account
name	string	the username of the connection account
type	string	the service of this connection
revoked?	boolean	whether the connection is revoked
integrations?	array	an array of partial server integrations
verified	boolean	whether the connection is verified
friend_sync	boolean	whether friend sync is enabled for this connection
show_activity	boolean	whether activities related to this connection will be shown in presence updates
two_way_link	boolean	whether this connection has a corresponding third party OAuth2 token
visibility	integer	visibility of this connection

Services

Value	Name
amazon-music	Amazon Music
battlenet	Battle.net
bungie	Bungie.net
bluesky	Bluesky
crunchyroll	Crunchyroll
domain	Domain
ebay	eBay
epicgames	Epic Games
facebook	Facebook
github	GitHub
instagram *	Instagram
mastodon	Mastodon
paypal	PayPal
playstation	PlayStation Network
reddit	Reddit
roblox	Roblox
spotify	Spotify
skype *	Skype
steam	Steam
tiktok	TikTok
twitch	Twitch
twitter	X (Twitter)
xbox	Xbox
youtube	YouTube

* Service can no longer be added by users

Visibility Types

Value	Name	Description
0	None	invisible to everyone except the user themselves
1	Everyone	visible to everyone

Application Role Connection Object

The role connection object that an application has attached to a user.

Application Role Connection Structure

Field	Type	Description
platform_name	?string	the vanity name of the platform a bot has connected (max 50 characters)
metadata	object	object mapping application role connection metadata keys to their string-ified value (max 100 characters) for the user on the platform a bot has connected

Get Current User

Returns the user object of the requester’s account. For OAuth2, this requires the identify scope, which will return the object without an email, and optionally the email scope, which returns the object with an email if the user has one.

Get User

Returns a user object for a given user ID.

Modify Current User

Modify the requester’s user account settings. Returns a user object on success. Fires a User Update Gateway event.

All parameters to this endpoint are optional.

JSON Params

Field	Type	Description
username	string	user’s username, if changed may cause the user’s discriminator to be randomized.
avatar	?image data	if passed, modifies the user’s avatar
banner	?image data	if passed, modifies the user’s banner

Get Current User Guilds

Returns a list of partial guild objects the current user is a member of. For OAuth2, requires the guilds scope.

Example Partial Guild

{
  "id": "80351110224678912",
  "name": "1337 Krew",
  "icon": "8342729096ea3675442027381ff50dfe",
  "banner": "bb42bdc37653b7cf58c4c8cc622e76cb",
  "owner": true,
  "permissions": "36953089",
  "features": ["COMMUNITY", "NEWS", "ANIMATED_ICON", "INVITE_SPLASH", "BANNER", "ROLE_ICONS"],
  "approximate_member_count": 3268,
  "approximate_presence_count": 784
}

This endpoint returns 200 guilds by default, which is the maximum number of guilds a non-bot user can join. Therefore, pagination is not needed for integrations that need to get a list of the users’ guilds.

Query String Params

Field	Type	Description	Required	Default
before	snowflake	get guilds before this guild ID	false	absent
after	snowflake	get guilds after this guild ID	false	absent
limit	integer	max number of guilds to return (1-200)	false	200
with_counts	boolean	include approximate member and presence counts in response	false	false

Get Current User Guild Member

Returns a guild member object for the current user. Requires the guilds.members.read OAuth2 scope.

Leave Guild

Leave a guild. Returns a 204 empty response on success. Fires a Guild Delete Gateway event and a Guild Member Remove Gateway event.

Create DM

Create a new DM channel with a user. Returns a DM channel object (if one already exists, it will be returned instead).

You should not use this endpoint to DM everyone in a server about something. DMs should generally be initiated by a user action. If you open a significant amount of DMs too quickly, your bot may be rate limited or blocked from opening new ones.

JSON Params

Field	Type	Description
recipient_id	snowflake	the recipient to open a DM channel with

Create Group DM

Create a new group DM channel with multiple users. Returns a DM channel object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a Channel Create Gateway event.

This endpoint is limited to 10 active group DMs.

JSON Params

Field	Type	Description
access_tokens	array of strings	access tokens of users that have granted your app the gdm.join scope
nicks	dict	a dictionary of user ids to their respective nicknames

Get Current User Connections

Returns a list of connection objects. Requires the connections OAuth2 scope.

Get Current User Application Role Connection

Returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.

Update Current User Application Role Connection

Updates and returns the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.

JSON Params

Field	Type	Description
platform_name?	string	the vanity name of the platform a bot has connected (max 50 characters)
platform_username?	string	the username on the platform a bot has connected (max 100 characters)
metadata?	object	object mapping application role connection metadata keys to their string-ified value (max 100 characters) for the user on the platform a bot has connected

Delete Current User Application Role Connection

Deletes the application role connection for the user. Requires an OAuth2 access token with role_connections.write scope for the application specified in the path.