⚠️ Note: Stay tuned here, in the Change Log, and on the Discord Developers server api-announcements channel, for additional information regarding when and how 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 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. You can also visit our blog to read a message from our cofounder about why we are making this change.
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.
- 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.
- Apps may need to update their code to support the new username system.
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.
Unifying Bot Names and Icons
A bot's username and icon of a verified app will now be the same as the one set in the General Overview page of that app’s settings. For an unverified app, only the bot's icon will be the same as the app's. This change simplifies the app development process while helping users understand the relationship between the apps and their bots 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: Apps' server nicknames will not be affected by this change.
Verified Apps
Verified apps’ bot usernames will be required to be unique and will be automatically migrated to align with the app name. For example, an app named Example App would continue having Example App as the app name, but its bot username would be migrated to exampleapp. Bot usernames will be between 2-32 characters, consisting of only lowercase Latin characters, numbers, and/or underscore _ and one consecutive period . . App Names can additionally include uppercase characters and spaces. Keep in mind, that if a bot'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 may have its current 4-digit discriminator appended to its new bot username. As in the example above, exampleapp would not be available, so another bot with the same app name would be migrated as exampleapp6789. Remember that all apps will be allowed a one-time opportunity to change the name on the Developer Portal during migration.
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. Keep in mind, similar to your own display name, it's the app name 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.
When applying for verification, 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.
Frequently Asked Questions
Why is Discord making this change for apps?
Bot users associated with apps are a type of user, so they are affected by the username change just like standard Discord users. The specific changes for verified and unverified apps help protect against impersonation and move the platform towards using Application Names rather than bot usernames.
Please read the blog post for more information on why this change was made.
Can I get my app verified before the migration in order to make sure it gets reserved?
No, apps that are verified after May 2 will not have a username reserved.
Apps verified after May 2 will still be able to perform a 1-time name change at the time of migration.
Can I change my app’s name before the name migration?
In preparation of the migration, name changes for apps will temporarily be put on hold.
If your app is verified, you will soon be given a one-time opportunity to change your app’s name.
If your app is not verified, you will continue to be able to change its name on your own within the developer portal.
When will apps be able to update their name?
Stay tuned here, in the Change Log, and on the Discord Developers server api-announcements channel, for additional information regarding when and how 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.
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.