Username Docs Updates (#6218)

* start username docs * default avatar * Update docs/Reference.md Co-authored-by: Florian Spieß <business@minn.dev> * Update docs/Change_Log.md Co-authored-by: Néstor Pérez <25409753+prryplatypus@users.noreply.github.com> * fix docs * reorder * clarify migrated/legacy * small changelog clarification * Update docs/Change_Log.md Co-authored-by: Florian Spieß <business@minn.dev> * Update docs/Reference.md Co-authored-by: Florian Spieß <business@minn.dev> * oops * great --------- Co-authored-by: Florian Spieß <business@minn.dev> Co-authored-by: Néstor Pérez <25409753+prryplatypus@users.noreply.github.com>
discord · Jun 7, 2023 · 6e9622b · onerandomusername · Jun 8, 2023 · Doc94
1 parent dd48c48
commit 6e9622b
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 8 deletions.
diff --git a/docs/Change_Log.md b/docs/Change_Log.md
@@ -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": "nelly@discord.com",
+  "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

diff --git a/docs/Reference.md b/docs/Reference.md
@@ -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      |
@@ -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.
 

diff --git a/docs/resources/User.md b/docs/resources/User.md
@@ -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              |
+| 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              |
@@ -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 |