Skip to content

Username Docs Updates #6218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jun 7, 2023
Merged

Username Docs Updates #6218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a768ffc
start username docs
shaydewael May 4, 2023
9a162cf
default avatar
shaydewael May 4, 2023
551843e
Update docs/Reference.md
shaydewael May 17, 2023
090d609
Update docs/Change_Log.md
shaydewael May 17, 2023
8c74893
fix docs
shaydewael Jun 7, 2023
c75d7ef
reorder
shaydewael Jun 7, 2023
7379fc0
clarify migrated/legacy
shaydewael Jun 7, 2023
3f0c9ca
small changelog clarification
shaydewael Jun 7, 2023
a77d595
Merge branch 'main' into username-updates
shaydewael Jun 7, 2023
f7b0650
Update docs/Change_Log.md
shaydewael Jun 7, 2023
8500126
Update docs/Reference.md
shaydewael Jun 7, 2023
9f6ddd2
oops
shaydewael Jun 7, 2023
bc56661
great
shaydewael Jun 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/Change_Log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,50 @@
- Add Auto Moderation `mention_raid_protection_enabled` [trigger_metadata](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object-trigger-metadata) field for the `MENTION_SPAM` [trigger_type](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object-trigger-types). If this field and its parent `MENTION_SPAM` rule are enabled, Auto Moderation provides baseline detection against sudden spikes in mention activity that are normally indicative of mention raids.
- Add `safety_alerts_channel_id` [guild](#DOCS_RESOURCES_GUILD/guild-object) field and [`RAID_ALERTS_DISABLED` guild feature flag](#DOCS_RESOURCES_GUILD/guild-object-guild-features) which are associated with join raid protection

## Unique usernames on Discord

#### May 3, 2023

> warn
> Bot users will stay on the legacy username system for now. More details can be found on the [Developer Help Center article](https://dis.gd/app-usernames).

Discord’s username system is changing. Discriminators are being removed and new, unique usernames and display names are being introduced. You can read more details about how changes to the username system affects non-bot users in the [general Help Center article](https://dis.gd/usernames). To learn how it impacts bot users specifically, you can read the [Developer Help Center article](https://dis.gd/app-usernames).

This changelog focuses only on the technical changes to be aware of to update your app's code.

### Identifying migrated users

The new username system will rollout to users over time rather than all at once. The value of a single zero (`"0"`) in the [`discriminator` field](#DOCS_RESOURCES_USER/user-object-user-structure) on a user will indicate that the user has been migrated to the new username system. Note that the discriminator for migrated users will *not* be 4-digits like a standard discriminator (it is `"0"`, not `"0000"`). The value of the `username` field will become the migrated user's unique username.

After migration of all users is complete, the `discriminator` field may be removed.

#### Example migrated user

```json
{
"id": "80351110224678912",
"username": "nelly",
"discriminator": "0",
"global_name": "Nelly",
"avatar": "8342729096ea3675442027381ff50dfe",
"verified": true,
"email": "[email protected]",
"flags": 64,
"banner": "06c16474723fe537c283b8efa61a30c8",
"accent_color": 16711680,
"premium_type": 1,
"public_flags": 64
}
```

### Display names

As part of the new username system, standard Discord users can define a non-unique display name. This value will be a new `global_name` field with a max length of 32 characters. If the user has not set a display name, `global_name` will be null.

### Default avatars

For users with migrated accounts, default avatar URLs will be based on the user ID instead of the discriminator. The URL can now be calculated using `(user_id >> 22) % 6`. Users on the legacy username system will continue using `discriminator % 5`.

## Bot users added to all new apps

#### April 14, 2023
Expand Down
4 changes: 2 additions & 2 deletions docs/Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,7 +318,7 @@ Discord uses ids and hashes to render images in the client. These hashes can be
| Guild Discovery Splash | discovery-splashes/[guild_id](#DOCS_RESOURCES_GUILD/guild-object)/[guild_discovery_splash](#DOCS_RESOURCES_GUILD/guild-object).png | PNG, JPEG, WebP |
| Guild Banner | banners/[guild_id](#DOCS_RESOURCES_GUILD/guild-object)/[guild_banner](#DOCS_RESOURCES_GUILD/guild-object).png \* | PNG, JPEG, WebP, GIF |
| User Banner | banners/[user_id](#DOCS_RESOURCES_USER/user-object)/[user_banner](#DOCS_RESOURCES_USER/user-object).png \* | PNG, JPEG, WebP, GIF |
| Default User Avatar | embed/avatars/[user_discriminator](#DOCS_RESOURCES_USER/user-object).png \*\* \*\*\* | PNG |
| Default User Avatar | embed/avatars/[index](#DOCS_RESOURCES_USER/user-object).png \*\* \*\*\* | PNG |
| User Avatar | avatars/[user_id](#DOCS_RESOURCES_USER/user-object)/[user_avatar](#DOCS_RESOURCES_USER/user-object).png \* | PNG, JPEG, WebP, GIF |
| Guild Member Avatar | guilds/[guild_id](#DOCS_RESOURCES_GUILD/guild-object)/users/[user_id](#DOCS_RESOURCES_USER/user-object)/avatars/[member_avatar](#DOCS_RESOURCES_GUILD/guild-member-object).png \* | PNG, JPEG, WebP, GIF |
| Application Icon | app-icons/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[icon](#DOCS_RESOURCES_APPLICATION/application-object).png | PNG, JPEG, WebP |
Expand All @@ -335,7 +335,7 @@ Discord uses ids and hashes to render images in the client. These hashes can be

\* In the case of endpoints that support GIFs, the hash will begin with `a_` if it is available in GIF format. (example: `a_1269e74af4df7417b13759eae50c83dc`)

\*\* In the case of the Default User Avatar endpoint, the value for `user_discriminator` in the path should be the user's discriminator modulo 5—Test#1337 would be `1337 % 5`, which evaluates to 2.
\*\* In the case of the Default User Avatar endpoint, the value for `index` depends on whether the user is [migrated to the new username system](#DOCS_CHANGE_LOG/unique-usernames-on-discord). For users on the new username system, `index` will be `(user_id >> 22) % 6`. For users on the *legacy* username system, `index` will be `discriminator % 5`.

\*\*\* In the case of the Default User Avatar and Sticker endpoints, the size of images returned is constant with the "size" querystring parameter being ignored.

Expand Down
13 changes: 7 additions & 6 deletions docs/resources/User.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ There are other rules and restrictions not shared here for the sake of spam and
| ------------- | --------- | ---------------------------------------------------------------------------------------------------- | --------------------- |
| 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 |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You seem to have missed this with the restrictions (or link) at the header New Usernames here.

| discriminator | string | the user's Discord-tag | identify |
| global_name | ?string | the user's display name, if it is set. For bots, this is the application name | identify |
| avatar | ?string | the user's [avatar hash](#DOCS_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 |
Expand Down Expand Up @@ -254,8 +255,8 @@ Updates and returns the [application role connection](#DOCS_RESOURCES_USER/appli

###### 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](#DOCS_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 |
| 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](#DOCS_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 |