> ## Documentation Index
> Fetch the complete documentation index at: https://docs.discord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Resource

> Reference for Discord user objects and management endpoints.

export const Route = ({method, children}) => {
  return <div className="MDXRoute">
      <span className={"verb" + " " + method.toLowerCase()}>{method}</span>
      <span className="url">{children}</span>
    </div>;
};

export const ManualAnchor = ({id}) => {
  return <div className="MDXManualAnchor" id={id}></div>;
};

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

<ManualAnchor id="user-object-user-structure" />

###### 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](/developers/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](/developers/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](/developers/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](/developers/resources/user#user-object-user-flags) on a user's account                         | identify              |
| premium\_type?            | integer                                                                                    | the [type of Nitro subscription](/developers/resources/user#user-object-premium-types) on a user's account | identify.premium      |
| public\_flags?            | integer                                                                                    | the public [flags](/developers/resources/user#user-object-user-flags) on a user's account                  | identify              |
| avatar\_decoration\_data? | ?[avatar decoration data](/developers/resources/user#avatar-decoration-data-object) object | data for the user's avatar decoration                                                                      | identify              |
| collectibles?             | ?[collectibles](/developers/resources/user#collectibles) object                            | data for the user's collectibles                                                                           | identify              |
| primary\_guild?           | ?[user primary guild](/developers/resources/user#user-object-user-primary-guild) object    | the user's primary guild                                                                                   | identify              |

<ManualAnchor id="user-object-example-user" />

###### Example User

```json theme={"system"}
{
  "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"
  }
}
```

<ManualAnchor id="user-object-user-flags" />

###### 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](/developers/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](/developers/interactions/receiving-and-responding#receiving-an-interaction) and is shown in the online member list |

<ManualAnchor id="user-object-premium-types" />

###### 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   |

<ManualAnchor id="user-object-user-primary-guild" />

###### 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](/developers/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).

<ManualAnchor id="avatar-decoration-data-object-avatar-decoration-data-structure" />

###### Avatar Decoration Data Structure

| Field   | Type      | Description                                                          |
| ------- | --------- | -------------------------------------------------------------------- |
| asset   | string    | the [avatar decoration hash](/developers/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.

<ManualAnchor id="collectibles-collectible-structure" />

###### Collectible Structure

| Field      | Type   | Description                                                                                  |
| ---------- | ------ | -------------------------------------------------------------------------------------------- |
| nameplate? | object | object mapping of [nameplate data](/developers/resources/user#nameplate-nameplate-structure) |

### Nameplate

The nameplate the user has.

<ManualAnchor id="nameplate-nameplate-structure" />

###### Nameplate Structure

| Field   | Type      | Description                                                                                                                                          |
| ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| sku\_id | snowflake | id of the nameplate SKU                                                                                                                              |
| asset   | string    | path to the [nameplate asset](/developers/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.

<ManualAnchor id="connection-object-connection-structure" />

###### Connection Structure

| Field          | Type    | Description                                                                                    |
| -------------- | ------- | ---------------------------------------------------------------------------------------------- |
| id             | string  | id of the connection account                                                                   |
| name           | string  | the username of the connection account                                                         |
| type           | string  | the [service](/developers/resources/user#connection-object-services) of this connection        |
| revoked?       | boolean | whether the connection is revoked                                                              |
| integrations?  | array   | an array of partial [server integrations](/developers/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](/developers/resources/user#connection-object-visibility-types) of this connection |

<ManualAnchor id="connection-object-services" />

###### 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

<ManualAnchor id="connection-object-visibility-types" />

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

<ManualAnchor id="application-role-connection-object-application-role-connection-structure" />

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

<Route method="GET">/users/@me</Route>

Returns the [user](/developers/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

<Route method="GET">/users/[\{user.id}](/developers/resources/user#user-object)</Route>

Returns a [user](/developers/resources/user#user-object) object for a given user ID.

## Modify Current User

<Route method="PATCH">/users/@me</Route>

Modify the requester's user account settings. Returns a [user](/developers/resources/user#user-object) object on success. Fires a [User Update](/developers/events/gateway-events#user-update) Gateway event.

<Note>
  All parameters to this endpoint are optional.
</Note>

<ManualAnchor id="modify-current-user-json-params" />

###### JSON Params

| Field    | Type                                            | Description                                                                      |
| -------- | ----------------------------------------------- | -------------------------------------------------------------------------------- |
| username | string                                          | user's username, if changed may cause the user's discriminator to be randomized. |
| avatar   | ?[image data](/developers/reference#image-data) | if passed, modifies the user's avatar                                            |
| banner   | ?[image data](/developers/reference#image-data) | if passed, modifies the user's banner                                            |

## Get Current User Guilds

<Route method="GET">/users/@me/guilds</Route>

Returns a list of partial [guild](/developers/resources/guild#guild-object) objects the current user is a member of. For OAuth2, requires the `guilds` scope.

<ManualAnchor id="get-current-user-guilds-example-partial-guild" />

###### Example Partial Guild

```json theme={"system"}
{
  "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
}
```

<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.
</Info>

<ManualAnchor id="get-current-user-guilds-query-string-params" />

###### 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](/developers/reference#boolean-query-strings) | include approximate member and presence counts in response | false    | false   |

## Get Current User Guild Member

<Route method="GET">/users/@me/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/member</Route>

Returns a [guild member](/developers/resources/guild#guild-member-object) object for the current user. Requires the `guilds.members.read` OAuth2 scope.

## Leave Guild

<Route method="DELETE">/users/@me/guilds/[\{guild.id}](/developers/resources/guild#guild-object)</Route>

Leave a guild. Returns a 204 empty response on success. Fires a [Guild Delete](/developers/events/gateway-events#guild-delete) Gateway event and a [Guild Member Remove](/developers/events/gateway-events#guild-member-remove) Gateway event.

## Create DM

<Route method="POST">/users/@me/channels</Route>

Create a new DM channel with a user. Returns a [DM channel](/developers/resources/channel#channel-object) object (if one already exists, it will be returned instead).

<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.
</Warning>

<ManualAnchor id="create-dm-json-params" />

###### JSON Params

| Field         | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| recipient\_id | snowflake | the recipient to open a DM channel with |

## Create Group DM

<Route method="POST">/users/@me/channels</Route>

Create a new group DM channel with multiple users. Returns a [DM channel](/developers/resources/channel#channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a [Channel Create](/developers/events/gateway-events#channel-create) Gateway event.

<Warning>
  This endpoint is limited to 10 active group DMs.
</Warning>

<ManualAnchor id="create-group-dm-json-params" />

###### 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

<Route method="GET">/users/@me/connections</Route>

Returns a list of [connection](/developers/resources/user#connection-object) objects. Requires the `connections` OAuth2 scope.

## Get Current User Application Role Connection

<Route method="GET">/users/@me/applications/[\{application.id}](/developers/resources/application#application-object)/role-connection</Route>

Returns the [application role connection](/developers/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

<Route method="PUT">/users/@me/applications/[\{application.id}](/developers/resources/application#application-object)/role-connection</Route>

Updates and returns the [application role connection](/developers/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.

<ManualAnchor id="update-current-user-application-role-connection-json-params" />

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

<Route method="DELETE">/users/@me/applications/[\{application.id}](/developers/resources/application#application-object)/role-connection</Route>

Deletes the [application role connection](/developers/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.