v4.3.0 | Interactions, Slash-Commands, and Buttons

In this release, we are adding support for the new interactions API for bots. You can now use slash-commands and buttons with your bot to enhance the integration into the Discord interface.

Some useful resources:

• SlashBotExample
• Interactions Wiki
• Interaction Docs
• Component Docs (aka Buttons)

Keep in mind that Slash-Commands are a lot more limited and always require a response. You should make sure you understand the restrictions implied by slash-commands before converting your existing implementations. I wrote some guidelines you should be aware of in this gist: Slash Command Limitations

Support for stage channels will be added in the next release. In the meantime, just imagine a place where it's implemented!

New Features

• Interactions (Slash-Commands and Buttons) #1501
• Voice Channel Regions #1622
• Guild Templates #1465

You can check the full list of pull requests for more details:
4.3.0 Milestone

Thank you all for your contributions!

Deprecation

Detailed javadoc can be found in the deprecated tab of the docs

Installation

The release version is: 4.3.0_277

The latest version is:

Gradle

repositories {
    mavenCentral()
    maven {
        name 'm2-dv8tion'
        url 'https://m2.dv8tion.net/releases'
    }
}
dependencies {
    implementation("net.dv8tion:JDA:4.3.0_277")
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.3.0_277</version>
</dependency>
<repository>
    <id>dv8tion</id>
    <name>m2-dv8tion</name>
    <url>https://m2.dv8tion.net/releases</url>
</repository>

v4.2.1 | New Maven Repository, Replies, News Channels

With this release, we are addressing the sunset of the jcenter repository. (Read More)
We switched our release to a custom solution which is now hosted on https://m2.dv8tion.net/releases
See below in the Installation section for further details on the new repository.

Slash Commands, Stage Channels, and API v8 are going to be addressed in 4.3.0.

New Features

• Message Replies (#1408)
• RestAction#and and RestAction.allOf (#1320)
• News Channels and Crossposting (#1362)
• GuildMemberUpdateEvent (#1422)
• RoleTags (#1343)

You can check the full list of pull requests for more details:
4.2.1 Milestone

Thank you all for your contributions!

Deprecation

Detailed javadoc can be found in the deprecated tab of the docs

Installation

The release version is: 4.2.1_253

The latest version is:

Gradle

repositories {
    mavenCentral()
    maven {
        name 'm2-dv8tion'
        url 'https://m2.dv8tion.net/releases'
    }
}
dependencies {
    implementation("net.dv8tion:JDA:4.2.1_253")
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.2.1_253</version>
</dependency>
<repository>
    <id>dv8tion</id>
    <name>m2-dv8tion</name>
    <url>https://m2.dv8tion.net/releases</url>
</repository>

v4.2.0 | Gateway Intents

All support for AccountType.CLIENT has been removed. We can no longer support this API as it has diverged too much from the bot API.

In this release, we have to take a look at the new Discord API changes. As of late discord has been putting a lot of work into the privacy protection of their users. Unfortunately, that also includes limiting the data available to bots.
Bots are now required to explicitly state which features they intend to use by providing a set of GatewayIntents.

Additionally, bots should no longer directly depend on the cache of users/members with methods like getUserById() and getMembers(). You should now use lazy loading and load members through methods like retrieveMemberById or retrieveMembersByPrefix.

The old default behavior was to perform chunking on startup (explained in wiki article below). However, chunking is now a privileged feature which bots should not depend on. For this reason, we deprecated the old JDABuilder (and DefaultShardManagerBuilder) constructors in favor of new factory methods:

• createDefault
• createLight
• create

I've added a new wiki page that explains this in more detail: Gateway Intents and Member Cache Policy.

We have switched to the new domain discord.com. This will be required as of November 7, 2020.

New Features

• GatewayIntents
• MemberCachePolicy
• Invite events
• Mention Whitelist
• RestAction timeout/deadline

You can check the full list of pull requests for more details:
4.2.0 Milestone

Thank you all for your contributions!

Deprecation

Detailed javadoc can be found in the deprecated tab of the docs

Installation

The release version is: 4.2.0_168

The latest version is:

Gradle

repositories {
    jcenter()
}
dependencies {
    compile("net.dv8tion:JDA:4.2.0_168")
}

Maven

The jcenter repository now only works with https! Please change your URL from http to https

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.2.0_168</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>https://jcenter.bintray.com</url>
</repository>

v4.1.1 | Avoid callback hell and rate limits

A lot of people use nested callbacks for things like sending private messages or adding reactions:

@Override
public void onMessageReceived(MessageReceivedEvent event) {
  if (event.getMessage().getContentRaw().equals("!hello")) {
    user.openPrivateChannel().queue(
      channel -> channel.sendMessage("Hello Friend").queue(null,
        error -> event.getChannel().sendMessage("Failed to send message!").queue()));
  }
}

This gets very hard to read and maintain. Instead you can use something like submit() which returns a CompletableFuture to allow using continuations such as thenCompose and similar. This is great and all but that API is rather bad as it will swallow any errors by default and the error handling methods are not very nice.
We added a few new operators for common actions on RestAction:

• map
  Convert the result of the RestAction to a different value
• flatMap
  Chain another RestAction on the result
• delay
  Delay the element of the previous step

Let's look at the same example using the new flatMap operator:

@Override
public void onMessageReceived(MessageReceivedEvent event) {
  if (event.getMessage().getContentRaw().equals("!hello")) {
    user.openPrivateChannel()
           .flatMap(channel -> channel.sendMessage("Hello Friend"))
           .queue(null, error -> event.getChannel().sendMessage("Failed to send message!").queue()));
  }
}

This can be expanded to even more complicated chains:

@Override
public void onMessageReceived(MessageReceivedEvent event) {
  if (event.getMessage().getContentRaw().equals("!hello")) {
    event.getChannel().sendMessage("I'll contact you in 10 seconds") // MessageAction
      .delay(Duration.ofSeconds(10)) // delay next flatMap by 10 seconds
      .flatMap(m -> user.openPrivateChannel()) // RestAction<PrivateChannel>
      .flatMap(channel -> channel.sendMessage("Hello Friend, this will self destruct in 30 seconds")) // RestAction<Message>
      .delay(Duration.ofSeconds(30)) // delay next flatMap by 30 seconds
      .flatMap(Message::delete) // RestAction<Void>
      .queue(null, error -> event.getChannel().sendMessage("Failed to send message!").queue()));
  }
}

You can imagine how this would look with just queue/queueAfter:

@Override
public void onMessageReceived(MessageReceivedEvent event) {
  if (event.getMessage().getContentRaw().equals("!hello")) {
    event.getChannel().sendMessage("I'll contact you in 10 seconds").queue(m ->
      user.openPrivateChannel().queueAfter(10, TimeUnit.SECONDS, channel -> 
        channel.sendMessage("Hello Friend, this will self descruct in 30 seconds").queueAfter(30, TimeUnit.SECONDS,
          message -> message.delete().queue(),
          error -> event.getChannel().sendMessage("Failed to send message!").queue()
        )
      )
    );
  }
}

---

We also changed the implementation for the Rate Limiter in JDA which will now properly keep track of the "new" X-RateLimit-Bucket header to track which endpoints share the same rate-limit. This also means that JDA will now allow multiple requests to the same path while they follow different HTTP methods. For the user this just means, JDA now has a better understanding of how discord will limit your requests.

The new rate-limiter also has improved logging. You can now see which routes have what rate-limit by setting the logging level of net.dv8tion.jda.internal.requests.RateLimiter to trace. This will log messages such as this:

Updated bucket 80c17d2f203122d936070c88c8d10f33:guild_id:125227483518861312:webhook_id to (4/5, 4408)

The numbers at the end have this meaning (remaining requests/allowed requests in the reset time, milliseconds until reset).
The long bucket id is composed of the hash and the major parameters of the request. You can figure out which hash is for which bucket fairly quickly by looking for the corresponding cache log:

Caching bucket hash POST/channels/{channel_id}/messages -> 80c17d2f203122d936070c88c8d10f33

New Features

• RestAction operators (flatMap, map, delay)
• JDABuilder#setMaxBufferSize (same for shard manager)
• Message#suppressEmbeds and Message#getFlags

Deprecation

Detailed javadoc can be found in the deprecated tab of the docs

Installation

The release version is: 4.1.1_101

The latest version is:

Gradle

repositories {
    jcenter()
}
dependencies {
    compile "net.dv8tion:JDA:4.1.1_101"
}

Maven

The jcenter repository now only works with https! Please change your URL from http to https

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.1.1_101</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>https://jcenter.bintray.com</url>
</repository>

Pull Requests

You can view the 4.1.1 Milestone for a list of accepted pull requests for this release. Thank you to everyone who contributed!

v4.1.0 | Be More Lazy

We added support for lazy loading and now allow to disable guild subscriptions!

To enable lazy loading you have to configure a ChunkingFilter on your builder of choice [1]. Lazy loading means that JDA will not attempt to request the entire member list of a guild before starting to send events. Instead, members will be loaded on their first activity and members who are never active will never be loaded into cache.

new JDABuilder(TOKEN)
    .setChunkingFilter(ChunkingFilter.NONE) // don't chunk any guilds
    .build();

^{1) Example how to enable lazy loading}

The more extreme choice is to disable guild subscriptions [2]. This feature completely disables member and user cache for the shard/jda session. Note that if you need methods like Guild#getMembers or similar things that require knowledge of the entire member list this is not something you should be using. JDA cannot determine the size of a guild or member join/leave with this disabled. The benefit of this is a greatly reduced memory footprint with the disadvantage of losing member state tracking.

new JDABuilder(TOKEN)
    .setGuildSubscriptionsEnabled(false)
    .build();

^{2) Example how to disable guild subscriptions}

A footnote is that CacheFlag.VOICE_STATE can still be tracked and users in voice channels will still be loaded into cache when this cache flag is enabled. This is useful for music bots that want to leave a voice channel if they are alone.

You can now ignore specific ErrorResponse failures more easily. With ErroResponseException.ignore(...) you can create a failure consumer that drops any ErrorResponseException for the specified set of responses. [3]

import static net.dv8tion.jda.api.exceptions.ErrorResponseException.ignore;
import static net.dv8tion.jda.api.requests.ErrorResponse.*;

message.delete().queue(null, ignore(UNKNOWN_MESSAGE)); // ignore if message doesn't exist anymore
message.delete().queue(null, ignore(Logger::error, UNKNOWN_MESSAGE)); // ignore otherwise log

^{3) Example how to ignore UNKNOWN_MESSAGE errors}

New Features

• Lazy Loading and disable guild subscriptions
• Readonly support for custom status
• Member#getActiveClients
• ErrorResponseException.ignore(...)

Deprecation

Detailed javadoc can be found in the deprecated tab of the docs

• GuildUnavailableException, Guild#isAvailable this is no longer used, unavailable guilds are no longer in the guild cache. You can check if a guild is unavailable with JDA#getUnavailableGuilds
• Guild#retrieveVanityUrl replace with Guild#getVanityUrl
• Invite#getCreationTime replace with Invite#getTimeCreated
• JDA#getVoiceChannelByName replace with JDA#getVoiceChannelsByName
• ShardManager#setGame replace with ShardManager#setActivity
• SessionController#getGatewayBot replace with SessionController#getShardedGateway

Incubating

• AccountType#CLIENT this is most likely going to break soon with impending changes to the gateway
• JDABuilder(AccountType) this will be removed when AccountType#CLIENT breaks in the future
• Activity#watching, ActivityType#WATCHING this is not officially supported by the API but currently usable
• ActivityType#CUSTOM_STATUS this is currently not usable for bots and can only be seen on other users
• AudioManager#getSpeakingMode, AudioManager#setSpeakingMode this is not a confident implementation and should be used with care

Installation

The release version is: 4.1.0_81

The latest version is:

Gradle

repositories {
    jcenter()
}
dependencies {
    compile "net.dv8tion:JDA:4.1.0_81"
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.1.0_81</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>https://jcenter.bintray.com</url>
</repository>

Pull Requests

You can view the 4.1.0 Milestone for a list of accepted pull requests for this release. Thank you to everyone who contributed!

v4.0.0 | Refactoring with Breaking Changes

This release bumps the major version because we have done a number of breaking changes. The most notable ones are:

• Package rename core -> api
• Removed GuildController
• Renamed getX(): RestAction to retrieveX(): RestAction
• Added @Nonnull and @Nullable annotations

More can be found in the migration guide.

The plan for version 3.X is to keep updating it with bug fixes until 01/01/2020. We recommend migrating your codebase before then.

New Features

• MarkdownUtil A utility to easily apply markdown to text
• MarkdownSanitizer A state-machine to sanitize discord markdown
• GatewayPingEvent An event for updates to the gateway ping
• ApplicationInfo#getTeam Team support in applications
• Message#getMentionedXBag(): Bag<X> Bag accessors for mentions to check for duplicates
• Guild#getVanityCode and Guild#getVanityUrl
• Guild#getBoostTier, Guild#getBoostCount, and Guild#getBoosters
• Guild#getBannerId and Guild#getBannerUrl
• Guild#getMaxBitrate and Guild#getMaxEmotes
• Guild#getMaxMembers and Guild#getMaxPresences
• Guild#getDescription
• Member#getTimeBoosted
• AudioReceiveHandler#handleEncodedAudio and AudioReceiveHandler#canReceiveEncoded
• AudioReceiveHandler#includeUserInCombinedAudio
• Member#ban, Member#kick, Member#mute, Member#deafen, and Member#modifyNickname
• Guild#getGuildChannelById and JDA#getGuildChannelById
• Guild#kickVoiceMember
• MessageChannel#getHistoryFromBeginning
• Member#getOnlineStatus(ClientType)
• ReactionEmote#isEmoji, ReactionEmote#getAsCodepoints, and ReactionEmote#getEmoji
• AudioManager#setSpeakingDelay
• JDA#getUserByTag, ShardManager#getUserByTag, and Guild#getMemberByTag
• GuildChannel#upsertPermissionOverride
• JDABuilder#setVoiceDispatchInterceptor and DefaultShardManagerBuilder#setVoiceDispatchInterceptor
• CacheView#forEachUnordered, CacheView#applyStream, CacheView#acceptStream, and CacheView#lockedIterator
• JDA#getRestPing
• PaginationAction#skipTo
• Support for StoreChannel
• New message types
• Lots of new events and setters on managers

Deprecation

• Emote#hasRoles -> Emote#canProvideRoles
• Guild#retrieveVanityUrl -> Guild#getVanityCode
• Invite#getCreationTime -> Invite#getTimeCreated
• JDA#getVoiceChannelByName -> JDA#getVoiceChannelsByName
• DefaultShardManagerBuilder#setEventManager -> DefaultShardManagerBuilder#setEventManagerProvider
• ShardManager#setGame -> ShardManager#setActivity
• SessionController#getGatewayBot -> SessionController#getShardedGateway

Incubating

• JDABuilder(AccountType)
• Activity.watching
• AudioManager#setSpeakingMode and AudioManager#getSpeakingMode

Installation

The release version is: 4.0.0_39

The latest version is:

Gradle

repositories {
    jcenter()
}
dependencies {
    compile "net.dv8tion:JDA:4.0.0_39"
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.0.0_39</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>https://jcenter.bintray.com</url>
</repository>

v4.BETA.0 | Breaking Changes - Pre-Release

This is the first pre-release of the version 4 changes. I've written a migration guide which should help updating an existing v3 codebase to v4.

We will continue pushing critical bug fixes for v3 for a few months after the final release of v4 but we recommend updating to v4.

Versions

Latest version:

The latest release build: 4.BETA.0_1

Gradle

repositories {
    jcenter()
}
dependencies {
    implementation("net.dv8tion:JDA:4.BETA.0_1")
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>4.BETA.0_1</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>https://jcenter.bintray.com</url>
</repository>

v3.8.3 | Version 3 Stable Release

In this version we only updated the OkHTTP dependency to the stable 3.13.0 release.

Gradle

repositories {
    jcenter()
}
dependencies {
    implementation("net.dv8tion:JDA:3.8.3_464")
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>3.8.3_464</version>
</dependency>
<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>http://jcenter.bintray.com</url>
</repository>

v3.8.2 | JDA LTS Release

Important Notice

Recently we have started work on the new major version of JDA
This release signals the end of JDA v3's lifecycle in which we will only be fixing critical issues for the supported timeframe. Once v4 becomes the new stable release we will continue fixing issues with v3 for 6 months to give people with a huge codebase enough time for the conversion. The current expected time for the JDA version 4 release is mid May.

Currently JDA version 4 is in its alpha stadium. This means it receives breaking changes which are not yet supported by 3rd party extensions like lavalink. Once version 4 reaches its beta stadium we will make efforts to help extension developers to adapt to the new ABI provided as soon as possible. We attempt to make a clear separation between what we consider API and internal. We expect extensions to only target the API side of JDA in the future to reduce the possibility of causing incompatibilities.

New features and enhancements will only be coming to JDA 4. This includes new features of Discord as well as overhead reduction such as the changes done to CacheView. One of the major changes coming here is the removal of client-only features such as group channels/messages. We will however continue to support using JDA with AccountType.CLIENT but it will be reduced to features available to bot accounts.

To track what is happening with JDA 4 you can take a look at the milestone: v4

---

Pull Requests

PR	Description
#793	Read-only MessageActivity support
#795	Add Guild#getChannels for convenience
#811	Added setPresence to ShardManager and improved documentation consistency
#814	Added appendCodeLine(CharSequence text)
#819	Add ChannelAction#setPosition(Integer)
#820	Close socket on malformed zip data
#825	Added copying of the slowmode when cloning a channel
#826	Hacktoberfest Changes
#827	Don't check admin on permission overrides
#843	Update OkHTTP to 3.12.0
#849	Create User#getAsTag
#887	Add MESSAGE_ADD_REACTION to text only permissions
#896	Ignore alpha when comparing colors in MessageEmbed

Thank you all for your contributions!

Versions

Latest version:

The latest release build: 3.8.2_459

Changelog

Additions

• Guild#getChannels to get the display order of the channels in a guild
• MessageBuilder#appendCodeLine for more intuitive monospace usage
• ShardManager#setPresence to update both game an online-status in one request
• ChannelAction#setPosition for applying a channel position before its creation
• User#getAsTag for easy retrieval of Minn#6688 format
• MessageActivity support for spotify and game invites

Changes

• The WebSocket will now reconnect when malformed data is received for better recovering
• MessageEmbed#equals now only checks RGB value of the raw color instead of RGBA

Fixes

• VoiceJoin events now fire with updated muted/deafened status
• Slowmode property is now copied with Channel#createCopy
• ContextException are now fired properly again
• The ADMINISTRATOR permission is no longer checked when set on permission overrides

---

Gradle

repositories {
    jcenter()
    // Required for OkHTTP 3.13.0-SNAPSHOT
    maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}

dependencies {
    compile 'net.dv8tion:JDA:3.8.2_459'
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>3.8.2_459</version>
</dependency>


<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>http://jcenter.bintray.com</url>
</repository>
<repository> <!-- Required for OkHTTP 3.13.0-SNAPSHOT -->
    <id>sonatype</id>
    <name>sonatype-snapshots</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>

v3.8.1 | Slowmode - Chunking timeout - No more complete() in callbacks

Due to deadlocks in code of less experienced programmers (and even experienced ones) we now prohibit usage of complete() in callbacks of RestAction#queue. This means code similar to the following will no longer work and throw an exception (in the callback).

channel.sendMessage("hello there").queue(message -> {
    message.editMessage("hello world").queue(); // this is still fine
    message.delete().complete(); // exception
});

---

Requesting member chunks can cause a shard to not finish connecting when discord fails to respond. This issue has been known for quite a while and can now be handled properly by JDA thanks to the new setup system introduced in 3.8.0. Now JDA will re-attempt requesting chunks when nothing was received.

---

Discord has released slowmode for text channels in servers, this can now be configured through JDA to allow automation by bots.

Pull Requests

PR	Description
#762	Prevent using complete() in callbacks
#771	Cleanup logs
#773	Slowmode
#776	Configuration for [gateway] sending pools
#778	Prevent creation of send and receive systems before ws ready
#785	Add DefaultShardManager#setEventManagerProvider and JDA#getEventManager
#788	Add timeout mechanic for chunk requests

Thank you all for your contributions!

Versions

Latest version:

The latest release build: 3.8.1_437

Changelog

Additions

• Various additions for slowmode support
• DefaultShardManagerBuilder#setEventManagerProvider and JDA#getEventManager
• JDABuilder#setGatewayPool as well as similar methods for shard manager

Changes

• You can no longer use complete() in queue callbacks
• closeAudioConnection() can once again be used in lavaplayer event handlers
• The logs for rate-limiter and gateway have been improved (useful for debugging)

Fixes

• Idle audio send-system should no longer cause CPU issues
• UnavailableGuildJoinedEvent should fire again

Deprecation

• DefaultShardManagerBuilder#setEventManager should be replaced with setEventManagerProvider(...)

Incubating

• JDABuilder(AccountType) may not be available in the future
• Game.watching(...) is not officially released
• Game.GameType.WATCHING is not officially released
• RichPresence.Party.getMax() and RichPresence.Party.getSize() will return long in the future
• AudioManager.setSpeakingMode(...) and AudioManager.getSpeakingMode() is not officially released

Note the Incubating category which marks things that might change without deprecation phase.

---

Gradle

repositories {
    jcenter()
}

dependencies {
    compile 'net.dv8tion:JDA:3.8.1_437'
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>3.8.1_437</version>
</dependency>


<repository>
    <id>jcenter</id>
    <name>jcenter-bintray</name>
    <url>http://jcenter.bintray.com</url>
</repository>