# User Resource 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](/guides/api-reference-reference#image-formatting) | 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](/guides/api-reference-reference#image-formatting) | 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](/guides/api-reference-reference#locales) | identify | | verified? | boolean | whether the email on this account has been verified | email | | email? | ?string | the user's email | email | | flags? | integer | the [flags](/guides/http-api-resources-user#user-flags) on a user's account | identify | | premium\_type? | integer | the [type of Nitro subscription](/guides/http-api-resources-user#premium-types) on a user's account | identify.premium | | public\_flags? | integer | the public [flags](/guides/http-api-resources-user#user-flags) on a user's account | identify | | avatar\_decoration\_data? | ?[avatar decoration data](/guides/http-api-resources-user#avatar-decoration-data-object) object | data for the user's avatar decoration | identify | | collectibles? | ?[collectibles](/guides/http-api-resources-user#collectibles) object | data for the user's collectibles | identify | | primary\_guild? | ?[user primary guild](/guides/http-api-resources-user#user-primary-guild) object | the user's primary guild | identify | ###### Example User ```json { "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": 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](/guides/tools-resources-topics-teams) | | `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](/guides/interactions-receiving-and-responding#receiving-an-interaction) and is shown in the online member list | ###### Premium Types Premium types denote the level of premium a user has. Visit the [Nitro](https://discord.com/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](/guides/api-reference-reference#image-formatting) | ### Avatar Decoration Data Object The data for the user's [avatar decoration](https://support.discord.com/hc/en-us/articles/13410113109911-Avatar-Decorations). ###### Avatar Decoration Data Structure | Field | Type | Description | | ------- | --------- | ------------------------------------------------------------------------------ | | asset | string | the [avatar decoration hash](/guides/api-reference-reference#image-formatting) | | 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](/guides/http-api-resources-user#nameplate-structure) | ### 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](/guides/api-reference-reference#image-formatting) | | 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](/guides/http-api-resources-user#services) of this connection | | revoked? | boolean | whether the connection is revoked | | integrations? | array | an array of partial [server integrations](/guides/http-api-resources-guild#integration-object) | | 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](/guides/http-api-resources-user#visibility-types) of this connection | ###### Services | Value | Name | | ------------ | ------------------- | | amazon-music | Amazon Music | | 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](/guides/http-api-resources-application-role-connection-metadata#application-role-connection-metadata-object) keys to their `string`-ified value (max 100 characters) for the user on the platform a bot has connected | ## Get Current User /users/@me Returns the [user](/guides/http-api-resources-user#user-object) 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 /users/[{user.id}](/guides/http-api-resources-user#user-object) Returns a [user](/guides/http-api-resources-user#user-object) object for a given user ID. ## Modify Current User /users/@me Modify the requester's user account settings. Returns a [user](/guides/http-api-resources-user#user-object) object on success. Fires a [User Update](/guides/events-gateway-events#user-update) Gateway event. :::callout{intent="note"} 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](/guides/api-reference-reference#image-data) | if passed, modifies the user's avatar | | banner | ?[image data](/guides/api-reference-reference#image-data) | if passed, modifies the user's banner | ## Get Current User Guilds /users/@me/guilds Returns a list of partial [guild](/guides/http-api-resources-guild#guild-object) objects the current user is a member of. For OAuth2, requires the `guilds` scope. ###### Example Partial Guild ```json { "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 } ``` :::callout{intent="info"} 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 | | shard | integer | only return guilds in this shard (`0` to `max_concurrency - 1`) | false, unless using large bot sharding | absent | | with\_counts | [boolean](/guides/api-reference-reference#boolean-query-strings) | include approximate member and presence counts in response | false | false | :::callout{intent="warning"} Apps using [large bot sharding](/guides/events-gateway#sharding-for-large-bots) must provide the `shard` param. Valid values are `0` through `max_concurrency - 1`, where `max_concurrency` comes from the [session start limit object](/guides/events-gateway#session-start-limit-object) on [Get Gateway Bot](/guides/events-gateway#get-gateway-bot). Iterate over every shard to retrieve the full guild list. Apps that are not using large bot sharding are unaffected. Note that this value is different from the shard id used when connecting to the [Gateway](/guides/events-gateway). ::: ## Get Current User Guild Member /users/@me/guilds/[{guild.id}](/guides/http-api-resources-guild#guild-object)/member Returns a [guild member](/guides/http-api-resources-guild#guild-member-object) object for the current user. Requires the `guilds.members.read` OAuth2 scope. ## Leave Guild /users/@me/guilds/[{guild.id}](/guides/http-api-resources-guild#guild-object) Leave a guild. Returns a 204 empty response on success. Fires a [Guild Delete](/guides/events-gateway-events#guild-delete) Gateway event and a [Guild Member Remove](/guides/events-gateway-events#guild-member-remove) Gateway event. ## Create DM /users/@me/channels Create a new DM channel with a user. Returns a [DM channel](/guides/http-api-resources-channel#channel-object) object (if one already exists, it will be returned instead). :::callout{intent="warning"} 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 /users/@me/channels Create a new group DM channel with multiple users. Returns a [DM channel](/guides/http-api-resources-channel#channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a [Channel Create](/guides/events-gateway-events#channel-create) Gateway event. :::callout{intent="warning"} 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 /users/@me/connections Returns a list of [connection](/guides/http-api-resources-user#connection-object) objects. Requires the `connections` OAuth2 scope. ## Get Current User Application Role Connection /users/@me/applications/[{application.id}](/guides/http-api-resources-application#application-object)/role-connection Returns the [application role connection](/guides/http-api-resources-user#application-role-connection-object) 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 /users/@me/applications/[{application.id}](/guides/http-api-resources-application#application-object)/role-connection Updates and returns the [application role connection](/guides/http-api-resources-user#application-role-connection-object) 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](/guides/http-api-resources-application-role-connection-metadata#application-role-connection-metadata-object) 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 /users/@me/applications/[{application.id}](/guides/http-api-resources-application#application-object)/role-connection Deletes the [application role connection](/guides/http-api-resources-user#application-role-connection-object) for the user. Requires an OAuth2 access token with `role_connections.write` scope for the application specified in the path. ## Related pages - [API Reference](./api-reference-index.md) - [App Fundamentals](./app-fundamentals-index.md) - [Best Practices](./best-practices-index.md) - [Bots & Companion Apps](./bots-companion-apps-index.md) - [Building Games](./building-games-index.md) - [Building on Discord](./building-on-discord-index.md) - [Change Log](./change-log-index.md) - [Communities & Servers](./communities-servers-index.md) - [Components](./components-index.md) - [Core Concepts](./core-concepts-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.