User

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:

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

The following restrictions are additionally enforced for usernames:

Usernames cannot contain the following substrings: @, #, :, `, discord
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

snowflake

required

The user’s id. Requires the identify OAuth2 scope.

username

string

required

The user’s username, not unique across the platform. Requires the identify OAuth2 scope.

discriminator

string

required

The user’s Discord-tag. Requires the identify OAuth2 scope.

global_name

?string

required

The user’s display name, if it is set. Requires the identify OAuth2 scope.

avatar

?string

required

The user’s avatar hash. Requires the identify OAuth2 scope.

bot

boolean

Whether the user belongs to an OAuth2 application. Requires the identify OAuth2 scope.

system

boolean

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

mfa_enabled

boolean

Whether the user has two factor enabled on their account. Requires the identify OAuth2 scope.

banner

?string

The user’s banner hash. Requires the identify OAuth2 scope.

accent_color

?integer

The user’s banner color encoded as an integer representation of hexadecimal color code. Requires the identify OAuth2 scope.

locale

string

The user’s chosen language option. Requires the identify OAuth2 scope.

verified

boolean

Whether the email on this account has been verified. Requires the email OAuth2 scope.

?string

The user’s email. Requires the email OAuth2 scope.

flags

integer

The flags on a user’s account. Requires the identify OAuth2 scope.

premium_type

integer

The type of Nitro subscription on a user’s account. Requires the identify OAuth2 scope.

public_flags

integer

The public flags on a user’s account. Requires the identify OAuth2 scope.

avatar_decoration_data

?avatar decoration data object

Data for the user’s avatar decoration. Requires the identify OAuth2 scope.

collectibles

?collectibles object

Data for the user’s collectibles. Requires the identify OAuth2 scope.

primary_guild

?user primary guild object

The user’s primary guild. Requires the identify OAuth2 scope.

Example user

{
  "id": "80351110224678912",
  "username": "Nelly",
  "global_name": null,
  "discriminator": "1337",
  "avatar": "8342729096ea3675442027381ff50dfe",
  "verified": true,
  "email": "nelly@discord.com",
  "flags": 64,
  "banner": "06c16474723fe537c283b8efa61a30c8",
  "accent_color": 16711680,
  "premium_type": 1,
  "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 currently offered.

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

User primary guild

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 (for example, 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.

asset

string

required

The avatar decoration hash.

sku_id

snowflake

required

Id of the avatar decoration’s SKU.

Collectibles

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

nameplate

object

Object mapping of nameplate data.

Nameplate

The nameplate the user has.

sku_id

snowflake

required

Id of the nameplate SKU.

asset

string

required

Path to the nameplate asset.

label

string

required

The label of this nameplate. Currently unused.

palette

string

required

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.

string

required

Id of the connection account.

name

string

required

The username of the connection account.

type

string

required

The service of this connection.

revoked

boolean

Whether the connection is revoked.

integrations

array

An array of partial server integrations.

verified

boolean

required

Whether the connection is verified.

friend_sync

boolean

required

Whether friend sync is enabled for this connection.

show_activity

boolean

required

Whether activities related to this connection will be shown in presence updates.

two_way_link

boolean

required

Whether this connection has a corresponding third party OAuth2 token.

visibility

integer

required

Visibility of this connection.

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
`leagueoflegends`	League of Legends
`mastodon`	Mastodon
`paypal`	PayPal
`playstation`	PlayStation Network
`reddit`	Reddit
`riotgames`	Riot Games
`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.

Connection 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.

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

required

Object mapping [application role connection metadata](/developers/resources/application

Get current user

GET /users/@me

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

GET /users/{user.id}

Returns a user object for a given user ID.

Modify current user

PATCH /users/@me

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

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. See image data.

banner

?image data

If passed, modifies the user’s banner. See image data.

Get current user guilds

GET /users/@me/guilds

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

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.

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
}

Query string params

before

snowflake

Get guilds before this guild ID.

after

snowflake

Get guilds after this guild ID.

limit

integer

default:"200"

Max number of guilds to return (1–200).

with_counts

boolean

default:"false"

Include approximate member and presence counts in the response.

Get current user guild member

GET /users/@me/guilds/{guild.id}/member

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

Leave guild

DELETE /users/@me/guilds/{guild.id}

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

Create DM

POST /users/@me/channels

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

recipient_id

snowflake

required

The recipient to open a DM channel with.

Create group DM

POST /users/@me/channels

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

access_tokens

array of strings

required

Access tokens of users that have granted your app the gdm.join scope.

nicks

object

required

A dictionary of user ids to their respective nicknames.

Get current user connections

GET /users/@me/connections

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

Get current user application role connection

GET /users/@me/applications/{application.id}/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

PUT /users/@me/applications/{application.id}/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

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](/developers/resources/application

Core Reference

Resources

Events & Gateway

Monetization Resources

Voice & RPC

Usernames and nicknames

User object

User structure

Example user

User flags

Premium types

User primary guild

Avatar decoration data object

Collectibles

Nameplate

Connection object

Connection services

Connection visibility types

Application role connection object

Get current user

Get user

Modify current user

JSON params

Get current user guilds

Example partial guild

Query string params

Get current user guild member

Leave guild

Create DM

JSON params

Create group DM

JSON params

Get current user connections

Get current user application role connection

Update current user application role connection

JSON params

Core Reference

Resources

Events & Gateway

Monetization Resources

Voice & RPC

​Usernames and nicknames

​User object

​User structure

​Example user

​User flags

​Premium types

​User primary guild

​Avatar decoration data object

​Collectibles

​Nameplate

​Connection object

​Connection services

​Connection visibility types

​Application role connection object

​Get current user

​Get user

​Modify current user

​JSON params

​Get current user guilds

​Example partial guild

​Query string params

​Get current user guild member

​Leave guild

​Create DM

​JSON params

​Create group DM

​JSON params

​Get current user connections

​Get current user application role connection

​Update current user application role connection

​JSON params

Usernames and nicknames

User object

User structure

Example user

User flags

Premium types

User primary guild

Avatar decoration data object

Collectibles

Nameplate

Connection object

Connection services

Connection visibility types

Application role connection object

Get current user

Get user

Modify current user

JSON params

Get current user guilds

Example partial guild

Query string params

Get current user guild member

Leave guild

Create DM

JSON params

Create group DM

JSON params

Get current user connections

Get current user application role connection

Update current user application role connection

JSON params