JDA Interface - JDA (Java Discord API)

The core of JDA. Acts as a registry system of JDA. All parts of the API can be accessed starting from this interface.

Overview

The JDA interface is the main entry point for all Discord bot operations. It provides access to:

User and guild caches
Event management
REST operations
WebSocket connection management
Audio system

Creating a JDA Instance

Use JDABuilder to create a JDA instance:

JDA jda = JDABuilder.createDefault(token)
    .enableIntents(GatewayIntent.MESSAGE_CONTENT)
    .build();

Connection Status

getStatus

Gets the current connection status of the JDA instance.

return

Status

The current JDA status

Status status = jda.getStatus();
if (status == Status.CONNECTED) {
    System.out.println("Bot is ready!");
}

Status Enum Values:

INITIALIZING - JDA is setting up supporting systems
INITIALIZED - Ready to log in
LOGGING_IN - Currently attempting to log in
CONNECTING_TO_WEBSOCKET - Connecting to Discord’s WebSocket
IDENTIFYING_SESSION - Sending authentication
AWAITING_LOGIN_CONFIRMATION - Waiting for confirmation
LOADING_SUBSYSTEMS - Populating internal objects
CONNECTED - Fully connected and operational
DISCONNECTED - WebSocket disconnected
RECONNECT_QUEUED - Waiting to reconnect
ATTEMPTING_TO_RECONNECT - Trying to reconnect
SHUTTING_DOWN - Shutting down
SHUTDOWN - Fully shut down
FAILED_TO_LOGIN - Invalid authentication

awaitReady

Blocks the current thread until JDA reaches the CONNECTED status.

return

JDA

The current JDA instance for chaining

JDA jda = JDABuilder.createDefault(token).build();
jda.awaitReady(); // Wait until bot is ready
System.out.println("Bot is connected!");

awaitStatus

Blocks until JDA reaches a specific status.

status

Status

required

The status to wait for

failOn

Status...

Optional failure states that force premature return

return

JDA

The current JDA instance for chaining

jda.awaitStatus(Status.CONNECTED);

Gateway and Intents

getGatewayIntents

Returns the enabled gateway intents for this session.

return

EnumSet<GatewayIntent>

Set of active gateway intents

EnumSet<GatewayIntent> intents = jda.getGatewayIntents();
if (intents.contains(GatewayIntent.MESSAGE_CONTENT)) {
    System.out.println("Can read message content");
}

getCacheFlags

Returns the enabled cache flags for this session.

return

EnumSet<CacheFlag>

Copy of the EnumSet of cache flags

EnumSet<CacheFlag> flags = jda.getCacheFlags();

Ping and Latency

getGatewayPing

The time in milliseconds that Discord took to respond to the last heartbeat.

return

long

Time in milliseconds between heartbeat and acknowledgment

long ping = jda.getGatewayPing();
System.out.println("Gateway ping: " + ping + "ms");

getRestPing

Requests the current user from the API and calculates response time.

return

RestAction<Long>

RestAction returning the REST ping in milliseconds

jda.getRestPing().queue(time -> 
    System.out.println("REST ping: " + time + "ms")
);

User Management

getSelfUser

Returns the currently logged in account.

return

SelfUser

The bot’s user account

SelfUser self = jda.getSelfUser();
System.out.println("Logged in as: " + self.getAsTag());

getUserById

Retrieves a cached user by ID.

long | string

required

The user’s ID

return

User

The user, or null if not cached

User user = jda.getUserById(123456789L);
if (user != null) {
    System.out.println("Found user: " + user.getName());
}

retrieveUserById

Fetches a user from the API by ID. If cached, returns immediately.

long | string

required

The user’s ID

return

CacheRestAction<User>

RestAction that retrieves the user

jda.retrieveUserById(123456789L).queue(user -> {
    System.out.println("Retrieved: " + user.getName());
});

getUserCache

Returns the cache view of all cached users.

return

SnowflakeCacheView<User>

Cache view of users

SnowflakeCacheView<User> cache = jda.getUserCache();
System.out.println("Cached users: " + cache.size());

Guild Management

getGuildById

Retrieves a cached guild by ID.

long | string

required

The guild’s ID

return

Guild

The guild, or null if not cached

Guild guild = jda.getGuildById(987654321L);
if (guild != null) {
    System.out.println("Guild: " + guild.getName());
}

getGuilds

Returns an immutable list of all cached guilds.

return

List<Guild>

List of all guilds this bot is connected to

List<Guild> guilds = jda.getGuilds();
System.out.println("Connected to " + guilds.size() + " guilds");

getGuildCache

Returns the cache view of all cached guilds.

return

SnowflakeCacheView<Guild>

Cache view of guilds

SnowflakeCacheView<Guild> cache = jda.getGuildCache();

Event Management

addEventListener

Adds event listeners to handle Discord events.

listeners

Object...

required

One or more EventListener instances

jda.addEventListener(new MessageListener(), new ReadyListener());

removeEventListener

Removes previously registered event listeners.

listeners

Object...

required

One or more EventListener instances to remove

jda.removeEventListener(listener);

setEventManager

Changes the internal event manager implementation.

manager

IEventManager

The new event manager (null to use default)

jda.setEventManager(new AnnotatedEventManager());

listenOnce

Creates a builder for one-time event listeners.

eventType

Class<E>

required

The type of event to listen for

return

Once.Builder<E>

Builder for configuring the one-time listener

jda.listenOnce(MessageReceivedEvent.class)
    .filter(e -> e.getAuthor().getId().equals(userId))
    .timeout(Duration.ofSeconds(30))
    .subscribe(event -> {
        System.out.println("Received: " + event.getMessage().getContentRaw());
    });

Command Management

retrieveCommands

Retrieves the list of global slash commands.

withLocalizations

boolean

default:"false"

Whether to include localization data

return

RestAction<List<Command>>

RestAction returning list of commands

jda.retrieveCommands().queue(commands -> {
    System.out.println("Global commands: " + commands.size());
});

upsertCommand

Creates or updates a global command.

command

CommandData

required

The command data

return

RestAction<Command>

RestAction that creates or updates the command

CommandData data = Commands.slash("ping", "Check bot latency");
jda.upsertCommand(data).queue();

updateCommands

Replaces all global commands with a new list.

return

CommandListUpdateAction

Action to configure and execute the update

jda.updateCommands()
    .addCommands(
        Commands.slash("ping", "Check latency"),
        Commands.slash("help", "Show help")
    )
    .queue();

deleteCommandById

Deletes a global command by ID.

commandId

long | string

required

The command’s ID

return

RestAction<Void>

RestAction to delete the command

jda.deleteCommandById("123456789").queue();

Private Channels

openPrivateChannelById

Opens a private channel with a user.

userId

long | string

required

The user’s ID

return

CacheRestAction<PrivateChannel>

RestAction that opens the private channel

jda.openPrivateChannelById(userId)
    .flatMap(channel -> channel.sendMessage("Hello!"))
    .queue();

Presence and Activity

getPresence

Returns the presence manager for this bot.

return

Presence

The presence manager

Presence presence = jda.getPresence();
presence.setActivity(Activity.playing("a game"));
presence.setStatus(OnlineStatus.ONLINE);

Shutdown

shutdown

Gracefully shuts down JDA, finishing all pending requests.

jda.shutdown();

shutdownNow

Immediately shuts down JDA, cancelling all pending requests.

jda.shutdownNow();

awaitShutdown

Blocks until shutdown is complete.

duration

long

Maximum time to wait (0 = indefinite)

unit

TimeUnit

Time unit for duration

return

boolean

True if shutdown completed, false if timeout elapsed

jda.shutdown();
if (!jda.awaitShutdown(Duration.ofSeconds(10))) {
    jda.shutdownNow();
    jda.awaitShutdown();
}

Thread Pools

getRateLimitPool

Returns the executor used for rate-limit handling.

return

ScheduledExecutorService

The rate limit pool

getGatewayPool

Returns the executor used for WebSocket operations.

return

ScheduledExecutorService

The gateway pool

getCallbackPool

Returns the executor used for RestAction callbacks.

return

ExecutorService

The callback pool

Sharding

getShardInfo

Returns shard information for this instance.

return

ShardInfo

The shard info, or ShardInfo.SINGLE if not sharded

ShardInfo info = jda.getShardInfo();
System.out.println("Shard: " + info.getShardString());

JDABuilder - Build and configure JDA instances
RestAction - Asynchronous request handling

Core API

Entities

Events

Interactions

Utilities

Audio

Sharding

​Overview

​Creating a JDA Instance

​Connection Status

​getStatus

​awaitReady

​awaitStatus

​Gateway and Intents

​getGatewayIntents

​getCacheFlags

​Ping and Latency

​getGatewayPing

​getRestPing

​User Management

​getSelfUser

​getUserById

​retrieveUserById

​getUserCache

​Guild Management

​getGuildById

​getGuilds

​getGuildCache

​Event Management

​addEventListener

​removeEventListener

​setEventManager

​listenOnce

​Command Management

​retrieveCommands

​upsertCommand

​updateCommands

​deleteCommandById

​Private Channels

​openPrivateChannelById

​Presence and Activity

​getPresence

​Shutdown

​shutdown

​shutdownNow

​awaitShutdown

​Thread Pools

​getRateLimitPool

​getGatewayPool

​getCallbackPool

​Sharding

​getShardInfo

​Related

Build docs developers (and LLMs) love

Overview

Creating a JDA Instance

Connection Status

getStatus

awaitReady

awaitStatus

Gateway and Intents

getGatewayIntents

getCacheFlags

Ping and Latency

getGatewayPing

getRestPing

User Management

getSelfUser

getUserById

retrieveUserById

getUserCache

Guild Management

getGuildById

getGuilds

getGuildCache

Event Management

addEventListener

removeEventListener

setEventManager

listenOnce

Command Management

retrieveCommands

upsertCommand

updateCommands

deleteCommandById

Private Channels

openPrivateChannelById

Presence and Activity

getPresence

Shutdown

shutdown

shutdownNow

awaitShutdown

Thread Pools

getRateLimitPool

getGatewayPool

getCallbackPool

Sharding

getShardInfo

Related