Users ResourceUsers 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.
Avatar DataAvatar data is a Data URI scheme that supports JPG, GIF, and PNG formats. An example Data URI format is:
Ensure you use the proper header type (
image/gif) that matches the image data being provided.
Usernames and NicknamesDiscord enforces the following restrictions for usernames and nicknames:
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.
- Names can contain most valid unicode characters. We limit some zero-width and non-rendering characters.
- Names must be between 2 and 32 characters long.
- Names cannot contain the following substrings: '@', '#', ':', '```'.
- Names cannot be: 'discordtag', 'everyone', 'here'.
- Names are sanitized and trimmed of leading, trailing, and exessive internal whitespace.
|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 4-digit discord-tag||identify|
|avatar||string||the user's avatar hash||identify|
|bot?||bool||whether the user belongs to an OAuth2 application||identify|
|mfa_enabled?||bool||whether the user has two factor enabled on their account||identify|
|verified?||bool||whether the email on this account has been verified||email|
|email?||string||the user's email||email|
"email": "[email protected]"
Connection ObjectThe connection object that the user has attached.
|id||string||id of the connection account|
|name||string||the username of the connection account|
|type||string||the service of the connection (twitch, youtube)|
|revoked||bool||whether the connection is revoked|
|integrations||array||an array of partial server integrations|
Returns the user object of the requester's account. For OAuth2, this requires the
Get Current UserGET/users/@me
identify scope, which will return the object without an email, and optionally the
email scope, which returns the object with an email.
Returns a user object for a given user ID.
Modify the requester's user account settings. Returns a user object on success.
Modify Current UserPATCH/users/@me
|username||string||users username, if changed may cause the users discriminator to be randomized.|
|avatar||avatar data||if passed, modifies the user's avatar|
Returns a list of partial guild objects the current user is a member of. Requires the
Get Current User GuildsGET/users/@me/guilds
guilds OAuth2 scope.
Example Partial Guild
"name": "1337 Krew",
This endpoint returns 100 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 users' guilds.
Query String Params
Leave a guild. Returns a 204 empty response on success.
|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-100)||false||100|
Returns a list of DM channel objects.
Get User DMsGET/users/@me/channels
Create a new DM channel with a user. Returns a DM channel object.
|recipient_id||snowflake||the recipient to open a DM channel with|
Create a new group DM channel with multiple users. Returns a DM channel object.
Create Group DMPOST/users/@me/channels
By default this endpoint is limited to 10 active group DMs. These limits are raised for whitelisted GameBridge applications.
|access_tokens||array of strings||access tokens of users that have granted your app the |
|nicks||dict||a dictionary of user ids to their respective nicknames|
Returns a list of connection objects. Requires the
Get User ConnectionsGET/users/@me/connections
connections OAuth2 scope.