⚠️ Note: Stay tuned here, in the Change Log, and on the Discord Developers server api-announcements channel, for additional information regarding when the migration of application (app) names will occur. In the meantime, the Review Your Code section will help give you an idea of the steps you can take to prepare.
Table of Contents
Discord has announced the release of new usernames and this article will help you understand how apps will be migrated to this new system! Take a time to review the New Usernames article and familiarize yourself with the overall concept, then we can discuss what it means, how it will affect apps, and how to be ready.
How Apps are Affected
Developers can expect their apps to receive a couple of updates during migration to the new username system.
- All apps will have a bot user. New apps will automatically be assigned a bot user while existing apps will receive one during migration.
- App names and icons will be the default. Bot usernames and icons will default to the app’s name and icon.
- Apps will be migrated to the new username system as outlined in the Permitted Characters section. Notable impacts to Apps are, names between 2-32 characters consisting of only lowercase Latin characters, numbers, underscores, and one consecutive period.
Bot Users Added to all Apps
Going forward, every app will result in the creation of a bot user. Apps currently without bot users will be assigned one during migration. Please note, that if an app does not require a bot user, then the bot scope can simply be omitted when installing. However, don’t forget the bot scope if an app is going to utilize a bot.
Unifying Bot Names and Icons
A bot username and icon will no longer differ from the app’s name and icon. The bot username and icon will now be the same as whatever has been chosen in the General Overview page of an app’s settings. This change simplifies the development process and makes it easier for users to understand the relationship between the apps and bots you create on Discord.
Unique Names for all Apps
During migration, apps and bot users will be automatically assigned new usernames. New usernames affect verified and unverified apps in different ways so it is important to note how it applies to your app.
⚠️ Note: App’s server nicknames will not be affected by this change.
Verified Apps
Verified app names, like usernames, will be required to be unique and bot usernames will be automatically migrated to the app name. For example, an app named App#1234 would be migrated to a new app name and bot username: @app. App names will be between 2-32 characters, consisting of only lowercase Latin characters, numbers, and/or underscore _ and one consecutive period.. Keep in mind, that if an app's current name is greater than 32 characters, it will be truncated. Developers will also want to pay attention to the following circumstances that would require attention.
Duplicate App Names
The automatic migration process could result in multiple apps sharing the same name. To avoid this, any app where this might occur will have its current 4-digit discriminator appended to its new app name. As in the example above, @app would not be available, so another app named App#6789 would be migrated as @app6789. Remember that all apps will be allowed a one-time opportunity to change their name on the Developer Portal.
Restricted Characters in App Names
The migration will differ slightly if an app’s current name contains restricted characters. If the app’s name contains a mixture of permitted and restricted characters, as outlined in the How to Prepare section below, the name will be scrubbed of the restricted characters so only permitted characters remain. For example, an app named !..A..p..p..#1234 would be scrubbed and migrated as @app.
However, if an app’s name is comprised entirely of restricted characters, the app will be given a random name. You can then update the app to your preferred name with your allotted one-time opportunity to change the name from the app’s Developer Portal page.
Unverified and New Apps
As mentioned in the Bot Users Added to all Apps, above, all apps will have bot users. The bot usernames for unverified and newly-created apps will be randomly generated. But remember: It's the app name that’s most important now because that is what users will see across Discord. Until an app applies for verification, developers can still change the app’s name. As always, please ensure your app name is set to the name you desire before applying for verification.
At the time of verification application, your app’s bot usernames would be updated to match that of the app. However, if the app’s current name is not available, developers have the opportunity to choose a unique app name.
How to Prepare
Plan ahead! Whether you currently have, or plan to have a verified app choosing an app’s username is important, so take some time to plan out your username and how that can best represent the app’s brand.
Consider the following information when planning out an app’s name:
Permitted characters for new usernames:
- Latin characters
a-z - Numbers
0-9 - Certain special characters
_.
Restrictions for new usernames:
- Usernames must be at least 2 characters and at most 32 characters long
- Usernames are case insensitive and forced lowercase
- Usernames cannot use any other special characters besides underscore
_and period. - Usernames cannot use 2 consecutive period characters
..- (.a.b. is allowed, a..b is not allowed)
- Usernames are unique to each user and no two users can share the same username
-
Usernames (and App Names) must adhere to our Community Guidelines. Some examples of Usernames that are not permitted include:
- Usernames used to impersonate Discord, Discord staff, or Discord system messages
- Usernames used to impersonate an individual, group, or organization
- Usernames that attack other people or promote hate
- Usernames that contain sexually explicit language
Review Your Code
With the username change around the corner, it is a good idea to review your code and ensure no logic relies on usernames or app names.
- If your code references usernames instead of IDs, we recommend making changes to the code for a smoother transition.
- Identify code that will need updating if it relies on user payloads or the manipulation of discriminators. During migration, usernames will appear in payloads with a
#0discriminator. Make sure to account for this temporary discriminator when updating your code.
Ultimately, by unifying the name of your app and bot user, our hope is that unique app names will help users grow a deeper sense of trust and understanding when engaging with your app’s brand.
As always, if you have any further questions please contact Developer Support.