v5.0.0 | End of beta phase

[MinnDevelopment]

The Long Awaited Stabilization

After almost 3 years of refactoring and polishing, the stabilization of JDA 5.0.0 is here. If you have been following along, not much has changed since the latest beta release.

If you have somehow avoided updating to a beta release since 2021, here is a list of the most noteworthy additions, changes, and bug fixes since 4.4.0.

You can also use our Migration Guide to help you update to the latest version of JDA 5. This guide also includes the most important changes you need to consider.

Interactions / Application Features

Discord has further improved the capabilities of applications with new types of interactions. This major release of JDA adds support for these features, coming with some restructuring to properly accomodate the new types.

We've renamed interaction events to a more consistent naming scheme:

• SlashCommandEvent becomes SlashCommandInteractionEvent
• ButtonClickEvent becomes ButtonInteractionEvent

Similarly, we've renamed component types slightly:

• SelectionMenu is now StringSelectMenu, while adding a new EntitySelectMenu
• What was previously called Component has now been renamed to ActionComponent and ItemComponent, allowing us to introduce Component as an abstraction over both Button and ActionRow (which is now a LayoutComponent). The new Component interface is now an abstraction over both ItemComponent and LayoutComponent.

To learn more about interactions in JDA 5, take a look at our Interactions Wiki Guide.

Channel Type Rework

We've refactored the channel types and usages in JDA to be more maintainable. Each type of channel now directly maps to a specific channel interface, unlike before where VoiceChannel was used for both stage and voice type channels.
Instead there are now concrete interfaces for each type, such as NewsChannel, StageChannel, ForumChannel, etc.

The channel type hierarchy has been further refined, by introducing higher level abstractions to represent the features of multiple channel types:

• Channel
• GuildChannel
• MessageChannel and GuildMessageChannel
• AudioChannel

As well as more specific features or attributes of channels:

• IPermissionContainer
• IPositionableChannel
• IThreadContainer
• IWebhookContainer
• etc.

To properly maintain these many different channel types and make them easy to use, we've also introduced new union types to encompass multiple channels into a simple common union type. This replaces the old getTextChannel()/getVoiceChannel() getters on events with getChannel().asTextChannel(). However, you can also use the standard features of the unions directly. For instance, a MessageChannelUnion allows to send messages and these specialization methods:

MessageChannelUnion channel = event.getChannel();
channel.sendMessage("hello").queue();
if (channel.getType() == TEXT) {
  channel.asTextChannel().getManager().setTopic("test topic").queue();
}

Cache access has also seen some improvement, by introducing a new getChannelById(Class, long) method, allowing to just get a MessageChannel without worrying about the concrete type.

GuildMessageChannel channel = guild.getChannelById(GuildMessageChannel.class, 125227483518861312L);
channel.sendMessage("Hello general chat!").queue();

Learn more about the channel rework in Channel Rework.

Message Features

We've refactored our message sending interfaces to be more consistent, by abstracting MessageAction, MessageBuilder, and ReplyAction into shared interfaces MessageCreateRequest and MessageEditRequest. This makes all message sending code consistent. We recommend to simply chain your builder-like code directly on send messages:

channel.sendMessage("Hello World")
  .setComponents(ActionRow.of(button1, button2))
  .setEmbeds(embed1, embed2)
  .setFiles(files)
  .queue();

However, if you need to use builders, we've introduced MessageEditBuilder and MessageCreateBuilder to replace the old MessageBuilder utility. You can also now use SplitUtil to easily divide message content into multiple messages.

To support file descriptions and reduce the number of sendFile overloads, we've also introduced a new FileUpload type that unifies all attachments into a single type.

FileUpload file = FileUpload.fromData(new File("myFile.png"), "image.png")
  .setDescription("this is my alt text for screenreaders, allowing to make accessible images in your messages!");
channel.sendFiles(file).queue();

Learn more about the changes to message sending in Message Send/Edit Rework.

Emojis and Stickers

In JDA 5, we have decided to unify all emoji types into a consistent type structure:

• Emoji, a top-level interface representing all emoji as well as a type discriminator with Emoji#getType
• UnicodeEmoji, standard unicode emoji such as 🤔
• CustomEmoji, custom emoji found in messages, like <:minn:245267426227388416>
• RichCustomEmoji, emoji with more information such as owner, accessible through the guild settings.
• EmojiUnion, adding type casting for things like MessageReaction#getEmoji

These new emoji types replace the duplication of ReactionEmote and Activity.Emoji.

Stickers have also been refactored in a similar way, making a clear distinction between stickers found in messages and guild settings:

• Sticker, a top-level abstraction of all sticker types
• StickerItem, stickers found in messages
• RichSticker, stickers with more information that is usually omitted for messages (sticker items)
• StandardSticker, rich stickers provided by nitro instead of guilds
• GuildSticker, rich stickers provided in guilds
• StickerUnion, adding type casting

Learn more about the changes to emojis and stickers in Sticker and Emoji Rework.

Installation

All future JDA releases will be distributed through maven central. You no longer need to use jcenter() in your dependency manager.

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("net.dv8tion:JDA:5.0.0")
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>5.0.0</version> 
</dependency>

Changelog (5.0.0-beta.24 -> 5.0.0)

The changes since the latest beta release to this release.

• Allow UserSnowflake subtypes in bulk ban methods by @freya022 (Allow UserSnowflake subtypes in bulk ban methods #2689)
• Update MessageType enum by @MinnDevelopment (Update MessageType enum #2691)
• Improve Unknown Interaction error responses by @freya022 (Improve Unknown Interaction error responses #2687)
• Update ErrorResponse enum by @MinnDevelopment (Update ErrorResponse enum #2693)
• Add missing permissions by @MinnDevelopment (Add missing permissions #2690)
• Update and remove deprecated symbols by @MinnDevelopment (Update and remove deprecated symbols #2686)

Changelog (4.4.0 -> 5.0.0)

Note that this changelog is a linear history of changes. This means some earlier changes have already been superseded or refined in more recent changes. This changelog is slightly compressed to remove unimportant changes, you can see the full list of commits here.

Thank you all for contributing!

New Features

New feature additions since 4.4.0

• Add GenericMessageEvent#getThreadChannel() by @rtm516 in Add GenericMessageEvent#getThreadChannel() #1924
• Add Message.Attachment#getDescription by @sebm253 in add Message.Attachment#getDescription #1930
• Add Guild#isBoostProgressBarEnabled by @sebm253 in Add Guild#isBoostProgressBarEnabled #1891
• Add support for member timeouts by @sebm253 in Add support for member timeouts #1902
• Add support for attachment options by @MinnDevelopment in Add support for attachment options #2001
• Add CommandInteractionPayload#getOption fallback overloads by @MinnDevelopment in Add CommandInteractionPayload#getOption fallback overloads #2018
• Add Booster to memberCachePolicy by @sofiadparamo in Add Booster to memberCachePolicy #2022
• Add PaginationAction#order by @MinnDevelopment in Add PaginationAction#order #1945
• Add Tags, Default Install Url, Scopes and Permissions to ApplicationInfo by @Xirado in Add Tags, Default Install Url, Scopes and Permissions to ApplicationInfo #1936
• Add CommandInteractionPayload#isGuildCommand by @MinnDevelopment in Add CommandInteractionPayload#isGuildCommand #2091
• Add UserSnowflake and improve User#fromId by @MinnDevelopment in Add UserSnowflake and improve User#fromId #2065
• Add support for modals by @Xirado in Add support for modals #2024
• Add ImageProxy & FileProxy by @freya022 in Add ImageProxy & FileProxy #1955
• Add Message#getStartedThread and ThreadChannel#retrieveParentMessage by @Almighty-Satan in Add Message#getStartedThread and ThreadChannel#retrieveParentMessage #2099
• Add FileUpload class by @MinnDevelopment in Add FileUpload class #2120
• Add Support for Application-Command Permissions V2 by @Xirado in Add Support for Application-Command Permissions V2 #2113
• Application command localization by @freya022 in Application command localization #2090
• Add EmojiUnion by @MinnDevelopment in Add EmojiUnion #2167
• Add JDABuilder#setEventPassthrough by @freya022 in Add JDABuilder#setEventPassthrough #2014
• Add ApplicationInfo#getFlags by @MinnDevelopment in Add ApplicationInfo#getFlags #2202
• Add support for setting voice region on channel creation/copy by @CheesyGamer77 in Add support for setting voice region on channel creation/copy #2209
• add support for string option bounds by @sebm253 in add support for string option bounds #2169
• Add DataPath util by @MinnDevelopment in Add DataPath util #2212
• Add category feature to ChannelOrderAction by @MinnDevelopment in Add category feature to ChannelOrderAction #2136
• Added RestAction#onSuccess by @Zabuzard in Added RestAction#onSuccess #2227
• Add support for forum channels by @MinnDevelopment in Add support for forum channels #2184
• Add GuildManager#setFeatures by @MinnDevelopment in Add GuildManager#setFeatures #2222
• Add support for guild scheduled events v2 by @Mitmocc in Add support for guild scheduled events v2 #2047
• Implement new select menus by @MinnDevelopment in Implement new select menus #2287
• Add slash command mentions by @freya022 in Add slash command mentions #2251
• Implement "ACTIVE_DEVELOPER" UserFlag by @jasonlessenich in Implement "ACTIVE_DEVELOPER" UserFlag #2326
• Add support for age-restricted (nsfw) commands by @MinnDevelopment in Add support for age-restricted (nsfw) commands #2325
• Add application_id support for received messages by @Almighty-Satan in Add application_id support for received messages #2335
• Implement thread member pagination by @MinnDevelopment in Implement thread member pagination #2338
• Add guild welcome screens by @freya022 in Add guild welcome screens #2264
• Add support for gif stickers by @MinnDevelopment in Add support for gif stickers #2377
• Add support for reverse audit-log iteration by @MinnDevelopment in Add support for reverse audit-log iteration #2370
• Add GuildAuditLogEntryCreateEvent by @MinnDevelopment in Add GuildAuditLogEntryCreateEvent #2380
• Add SUPPRESS_NOTIFICATIONS flag for message by @Mysterious-Dev in Add SUPPRESS_NOTIFICATIONS flag for message #2393
• Add new message types by @MinnDevelopment in Add new message types #2371
• Add rate-limiter customization by @MinnDevelopment in Add rate-limiter customization #2307
• Add support for member flags by @MinnDevelopment in Add support for member flags #2417
• Support custom timeout on tasks by @MinnDevelopment in Support custom timeout on tasks #2439
• Add EmbedBuilder#setUrl by @Xirado in Add EmbedBuilder#setUrl #2449
• Add voice message read support by @RedDaedalus in Add voice message read support #2445
• Add automod support by @MinnDevelopment in Add automod support #2429
• Add ThreadChannel#retrieveStartMessage by @MinnDevelopment in Add ThreadChannel#retrieveStartMessage #2438
• Support embed deserialization from JSON data by @MinnDevelopment in Support embed deserialization from JSON data #2471
• Add the message author id to message reaction events by @MinnDevelopment in Add the message author id to message reaction events #2499
• Add supplier based FileUpload by @MinnDevelopment in Add supplier based FileUpload #2508
• Add custom status support for bots by @RedDaedalus in Add custom status support for bots #2521
• Allow slowmode & nsfw in Stage Channels by @kazuryyx in Allow slowmode & nsfw in Stage Channels #2538
• Add LRUMemberCachePolicy by @MinnDevelopment in Add LRUMemberCachePolicy #2506
• Add initial support for media channels by @MinnDevelopment in Add initial support for media channels #2516
• Add default_values support by @MinnDevelopment in Add default_values support #2542
• Implement super reaction handling by @MinnDevelopment in Implement super reaction handling #2554
• Add voice status feature by @MinnDevelopment in Add voice status feature #2532
• Add missing proxy url field to the MessageEmbed.VideoInfo class by @shaksternano in Add missing proxy url field to the MessageEmbed.VideoInfo class #2618
• Add support for bulk banning users by @MinnDevelopment in Add support for bulk banning users #2630
• Add the ability to set the bot banner by @freya022 in Add the ability to set the bot banner #2629
• Add support for premium app subscriptions by @Giuliopime in Add support for premium app subscriptions #2583
• Poll support by @MinnDevelopment in Poll support #2649
• Add missing features relating to premium app subscriptions by @Tobias123567 in Add missing features relating to premium app subscriptions #2667
• Update MessageType enum by @MinnDevelopment in Update MessageType enum #2691
• Update ErrorResponse enum by @MinnDevelopment in Update ErrorResponse enum #2693
• Add missing permissions by @MinnDevelopment in Add missing permissions #2690

Breaking Changes

Breaking changes since 4.4.0

• Update Activity(Type) by @DManstrator in Update Activity(Type) #1798
• Update Permissions for JDA5 by @DManstrator in Update Permissions for JDA5 #1797
• Remove GuildManager#setVanityCode by @sebm253 in Remove GuildManager#setVanityCode #1933
• Interaction Rework by @MinnDevelopment in Interaction Rework #1971
• Make getDefaultChannel return BaseGuildMessageChannel by @MinnDevelopment in Make getDefaultChannel return BaseGuildMessageChannel #2016
• Change PrivateChannel#getUser to handle API nullability by @oliver276 in Change PrivateChannel#getUser to handle API nullability #2012
• Remove StoreChannel by @V-Play-Games in Remove StoreChannel #2011
• Change some voice Regions and remove VOICE_CHANNEL_REGIONS set by @sebm253 in Change some voice Regions and remove VOICE_CHANNEL_REGIONS set #1962
• Fix misspelled ErrorResponse enum value by @Xirado in Fix misspelled ErrorResponse enum value #2031
• Implement pagination for the guild ban list by @RedDaedalus in Implement pagination for the guild ban list #2076
• Return MessageReaction for getReactionX methods by @duncte123 in Return MessageReaction for getReactionX methods #2026
• Remove confusing permission override methods by @MinnDevelopment in Remove confusing permission override methods #2067
• Remove manager instance cache by @duncte123 in Remove manager instance cache #2106
• Message interface declutter: Message#getMentions() by @DV8FromTheWorld in Message interface declutter: Message#getMentions() #2015
• Rework stickers by @MinnDevelopment in Rework stickers #2104
• Changed addField String name and String Value to Nonnull by @RealYusufIsmail in Changed addField String name and String Value to Nonnull #2133
• Uniform representation of emoji by @MinnDevelopment in Uniform representation of emoji #2117
• Introduce Channel Unions by @DV8FromTheWorld in Introduce Channel Unions #2138
• Replace occurrences of Locale with DiscordLocale by @MineKing9534 in Replace occurrences of Locale with DiscordLocale #2173
• Message Rework by @MinnDevelopment in Message Rework #2187
• Remove ChannelAction#setType by @MinnDevelopment in Remove ChannelAction#setType #2218
• Invalid token exception by @java-coding-prodigy in Invalid token exception #2025
• Add support for ban deletion with seconds precision by @MinnDevelopment in Add support for ban deletion with seconds precision #2229
• Update to gateway version 10 by @freyacodes in Update to gateway version 10 #2228
• Move channels to separate package and cleanup code by @MinnDevelopment in Move channels to separate package and cleanup code #2180
• Update event hierarchy by @MinnDevelopment in Update event hierarchy #1952
• Make Widget an interface and move it to it's own file by @Almighty-Satan in Make Widget an interface and move it to it's own file #2295
• Remove AccountType by @MinnDevelopment in Remove AccountType #2420
• Deprecate and replace onUserSpeaking by @MinnDevelopment in Deprecate and replace onUserSpeaking #2496

Other Changes

Other noteworthy changes since 4.4.0

• Add Missing Varargs and Methods Accepting Collection Arguments by @aasmart in Add Missing Varargs and Methods Accepting Collection Arguments #1810
• Make OptionData#addChoice accept long instead of int by @Xirado in Make OptionData#addChoice accept long instead of int #1816
• Make SelectionMenu#getOptions return an unmodifiable list by @freya022 in Make SelectionMenu#getOptions return an unmodifiable list #1922
• Make Guild#moveVoiceMember support AudioChannel instead by @sebm253 in Make Guild#moveVoiceMember support AudioChannel instead #1928
• Add support for animated guild banners by @sebm253 in Add support for animated guild banners #1897
• Hardcode gateway url by @Xirado in Hardcode gateway url #1957
• Move requestToSpeak to StageChannel by @MinnDevelopment in Move requestToSpeak to StageChannel #1978
• Add IGuildChannelContainer and getChannelById(Class, id) by @MinnDevelopment in Add IGuildChannelContainer and getChannelById(Class, id) #1949
• Don't override latest message id on deletion event by @ishwi in Dont override latest message id on deletion event #2013
• Remove mentioning members with ! by @Tais993 in Remove mentioning members with ! #2081
• Add new message types for automod by @MinnDevelopment in Add new message types for automod #2116
• Do not ignore member cache policy when chunking is enabled by @MinnDevelopment in Do not ignore member cache policy when chunking is enabled #2053
• Make more use of CacheRestAction by @MinnDevelopment in Make more use of CacheRestAction #2158
• Handle text in voice channels by @MinnDevelopment in Handle text in voice channels #2072
• Update to API version 10 by @MinnDevelopment in Update to API version 10 #2165
• Implement gateway resume url handling by @MinnDevelopment in Implement gateway resume url handling #2203
• Add support for component-only messages by @MinnDevelopment in Add support for component-only messages #2241
• Use String#intern for guild features and atoms by @MinnDevelopment in Use String#intern for guild features and atoms #2235
• Improve toString methods by @freya022 in Improve toString methods #2273
• Forward shutdown reason to awaitStatus exception by @MinnDevelopment in Forward shutdown reason to awaitStatus exception #2268
• Improve GuildChannel#getPosition and Guild#getChannels by @MinnDevelopment in Improve GuildChannel#getPosition and Guild#getChannels #2320
• Replace lock code with atomic int by @MinnDevelopment in Replace lock code with atomic int #2359
• Improve implementation of command data by @MinnDevelopment in Improve implementation of command data #2258
• Necessary additions for role subscriptions by @MinnDevelopment in Necessary additions for role subscriptions #2375
• Support messages in stage channels by @MinnDevelopment in Support messages in stage channels #2399
• Start migration to new username API by @MinnDevelopment in Start migration to new username API #2462
• Improve handling of method discovery in AnnotatedEventManager by @freya022 in Improve handling of method discovery in AnnotatedEventManager #2454
• Change thread model used for requests by @MinnDevelopment in Change thread model used for requests #2463
• Add more logging to request handling by @MinnDevelopment in Add more logging to request handling #2589
• Add missing message types by @MinnDevelopment in Add missing message types #2531
• Unified channel cache by @MinnDevelopment in Unified channel cache #2528
• Add support for enforce_nonce by @MinnDevelopment in Add support for enforce_nonce #2614
• Create an exception when receiving UNKNOWN_WEBHOOK in interaction hooks by @freya022 in Create an exception when receiving UNKNOWN_WEBHOOK in interaction hooks #2621
• Add USER_MUST_BE_VERIFIED ErrorResponse by @GitMilchi in Add USER_MUST_BE_VERIFIED ErrorResponse #2651
• Update permission enum by @MinnDevelopment in Update permission enum #2654
• Add more static analyzer annotations by @MinnDevelopment in Add more static analyzer annotations #2675
• Improve Unknown Interaction error responses by @freya022 in Improve Unknown Interaction error responses #2687

Bug Fixes

Bugs fixed since 4.4.0

• Fix wrong check in GenericMessageEvent#getGuildChannel by @sebm253 in fix wrong check in GenericMessageEvent#getGuildChannel #1927
• Fix rate limiter not shutting down if there is an empty bucket at shutdown by @Vankka in Fix rate limiter not shutting down if there is an empty bucket at shutdown #2080
• Prevent creating OptionData with OptionType#UNKNOWN by @sebm253 in prevent creating OptionData with OptionType#UNKNOWN #2101
• Handle emoji_id sometimes being 0 instead of null by @MinnDevelopment in Handle emoji_id sometimes being 0 instead of null #2279
• Use deep copy for layout components when applying message data by @freya022 in Use deep copy for layout components when applying message data #2236
• Fix some lock issues by @MinnDevelopment in Fix some lock issues #2339
• Change handling of speaking updates in voice connections by @MinnDevelopment in Change handling of speaking updates in voice connections #2240
• Improve conditional waiting and shutdown handling by @MinnDevelopment in Improve conditional waiting and shutdown handling #2269
• Fix slow shutdown during reconnects by @MinnDevelopment in Fix slow shutdown during reconnects #2464
• Update modulo for default avatars by id by @MinnDevelopment in Update modulo for default avatars by id #2475
• Fix handling of wrong length discriminators by @MinnDevelopment in Fix handling of wrong length discriminators #2478
• Handle clyde in DMs correctly by @MinnDevelopment in Handle clyde in DMs correctly #2489
• Update User#formatTo by @MinnDevelopment in Update User#formatTo #2492
• Improve handling of query parameters in image proxy by @MinnDevelopment in Improve handling of query parameters in image proxy #2551
• Fix orphaned rate-limit buckets by @MinnDevelopment in Fix orphaned rate-limit buckets #2585
• Handle numeric keys for ETF maps by @MinnDevelopment in Handle numeric keys for ETF maps #2642
• Fix ClassCastException in EntityBuilder#updateMemberCache by @Xirado in Fix ClassCastException in EntityBuilder#updateMemberCache #2660

---

This discussion was created from the release v5.0.0 | End of beta phase.