Package net.dv8tion.jda.api

Interface JDA

All Superinterfaces:

IGuildChannelContainer<Channel>

public interface JDA
extends IGuildChannelContainer<Channel>

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

See Also:

• JDABuilder

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	JDA.ShardInfo	Represents the information used to create this shard.
static enum	JDA.Status	Represents the connection status of JDA and its Main WebSocket.

Method Summary

Modifier and Type	Method	Description
void	addEventListener(Object... listeners)	Adds all provided listeners to the event-listeners that will be used to handle events.
default JDA	awaitReady()	This method will block until JDA has reached the status JDA.Status.CONNECTED.
default boolean	awaitShutdown()	Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
boolean	awaitShutdown(long duration, TimeUnit unit)	Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
default boolean	awaitShutdown(Duration timeout)	Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
default JDA	awaitStatus(JDA.Status status)	This method will block until JDA has reached the specified connection status.
JDA	awaitStatus(JDA.Status status, JDA.Status... failOn)	This method will block until JDA has reached the specified connection status.
int	cancelRequests()	Cancels all currently scheduled RestAction requests.
RestAction<ApplicationEmoji>	createApplicationEmoji(String name, Icon icon)	Creates a new ApplicationEmoji for this bot.
GuildAction	createGuild(String name)	Constructs a new Guild with the specified name Use the returned GuildAction to provide further details and settings for the resulting Guild!
RestAction<Void>	createGuildFromTemplate(String code, String name, Icon icon)	Constructs a new Guild from the specified template code.
TestEntitlementCreateAction	createTestEntitlement(long skuId, long ownerId, TestEntitlementCreateAction.OwnerType ownerType)	Constructs a new Entitlement with the skuId and the type.
default TestEntitlementCreateAction	createTestEntitlement(String skuId, String ownerId, TestEntitlementCreateAction.OwnerType ownerType)	Constructs a new Entitlement with the skuId and the type.
default RestAction<Void>	deleteCommandById(long commandId)	Delete the global command for this id.
RestAction<Void>	deleteCommandById(String commandId)	Delete the global command for this id.
RestAction<Void>	deleteTestEntitlement(long entitlementId)	Deletes a test entitlement by its id.
default RestAction<Void>	deleteTestEntitlement(String entitlementId)	Deletes a test entitlement by its id.
default CommandEditAction	editCommandById(long id)	Edit an existing global command by id.
CommandEditAction	editCommandById(String id)	Edit an existing global command by id.
CacheView<AudioManager>	getAudioManagerCache()	CacheView of all cached AudioManagers created for this JDA instance.
default @Unmodifiable List<AudioManager>	getAudioManagers()	Immutable list of all created AudioManagers for this JDA instance!
EnumSet<CacheFlag>	getCacheFlags()	The cache flags that have been enabled for this JDA session.
ExecutorService	getCallbackPool()	ExecutorService used to handle RestAction callbacks and completions.
DirectAudioController	getDirectAudioController()	Direct access to audio (dis-)connect requests.
default RichCustomEmoji	getEmojiById(long id)	Retrieves a custom emoji matching the specified id if one is available in our cache.
default RichCustomEmoji	getEmojiById(String id)	Retrieves a custom emoji matching the specified id if one is available in our cache.
SnowflakeCacheView<RichCustomEmoji>	getEmojiCache()	Unified SnowflakeCacheView of all cached Custom Emojis visible to this JDA session.
default @Unmodifiable List<RichCustomEmoji>	getEmojis()	A collection of all to us known custom emoji (managed/restricted included).
default @Unmodifiable List<RichCustomEmoji>	getEmojisByName(String name, boolean ignoreCase)	An unmodifiable list of all Custom Emojis that have the same name as the one provided.
IEventManager	getEventManager()	The EventManager used by this JDA instance.
EnumSet<GatewayIntent>	getGatewayIntents()	The GatewayIntents for this JDA session.
long	getGatewayPing()	The time in milliseconds that discord took to respond to our last heartbeat This roughly represents the WebSocket ping of this session
ScheduledExecutorService	getGatewayPool()	ScheduledExecutorService used to send WebSocket messages to discord.
default Guild	getGuildById(long id)	This returns the Guild which has the same id as the one provided.
default Guild	getGuildById(String id)	This returns the Guild which has the same id as the one provided.
SnowflakeCacheView<Guild>	getGuildCache()	SnowflakeCacheView of all cached Guilds visible to this JDA session.
default @Unmodifiable List<Guild>	getGuilds()	An immutable List of all Guilds that the logged account is connected to.
default @Unmodifiable List<Guild>	getGuildsByName(String name, boolean ignoreCase)	An immutable list of all Guilds that have the same name as the one provided.
okhttp3.OkHttpClient	getHttpClient()	The OkHttpClient used for handling http requests from RestActions.
String	getInviteUrl(Collection<Permission> permissions)	Creates an authorization invite url for the currently logged in Bot-Account.
String	getInviteUrl(Permission... permissions)	Creates an authorization invite url for the currently logged in Bot-Account.
int	getMaxReconnectDelay()	This value is the maximum amount of time, in seconds, that JDA will wait between reconnect attempts.
@Unmodifiable List<Guild>	getMutualGuilds(Collection<User> users)	Gets all Guilds that contain all given users as their members.
@Unmodifiable List<Guild>	getMutualGuilds(User... users)	Gets all Guilds that contain all given users as their members.
Presence	getPresence()	The Presence controller for the current session.
default PrivateChannel	getPrivateChannelById(long id)	This returns the PrivateChannel which has the same id as the one provided.
default PrivateChannel	getPrivateChannelById(String id)	This returns the PrivateChannel which has the same id as the one provided.
SnowflakeCacheView<PrivateChannel>	getPrivateChannelCache()	SnowflakeCacheView of all cached PrivateChannels visible to this JDA session.
default @Unmodifiable List<PrivateChannel>	getPrivateChannels()	An unmodifiable list of all known PrivateChannels.
ScheduledExecutorService	getRateLimitPool()	ScheduledExecutorService used to handle rate-limits for RestAction executions.
List<Object>	getRegisteredListeners()	Immutable List of Objects that have been registered as EventListeners.
long	getResponseTotal()	This value is the total amount of JSON responses that discord has sent.
default RestAction<Long>	getRestPing()	The time in milliseconds that discord took to respond to a REST request.
default Role	getRoleById(long id)	Retrieves the Role associated to the provided id.
default Role	getRoleById(String id)	Retrieves the Role associated to the provided id.
SnowflakeCacheView<Role>	getRoleCache()	Unified SnowflakeCacheView of all cached Roles visible to this JDA session.
default @Unmodifiable List<Role>	getRoles()	All Roles this JDA instance can see.
default @Unmodifiable List<Role>	getRolesByName(String name, boolean ignoreCase)	Retrieves all Roles visible to this JDA instance.
default ScheduledEvent	getScheduledEventById(long id)	This returns the ScheduledEvent which has the same id as the one provided.
default ScheduledEvent	getScheduledEventById(String id)	This returns the ScheduledEvent which has the same id as the one provided.
SnowflakeCacheView<ScheduledEvent>	getScheduledEventCache()	SnowflakeCacheView of all cached ScheduledEvents visible to this JDA session.
default @Unmodifiable List<ScheduledEvent>	getScheduledEvents()	An unmodifiable list of all ScheduledEvents of all connected Guilds.
default @Unmodifiable List<ScheduledEvent>	getScheduledEventsByName(String name, boolean ignoreCase)	An unmodifiable list of all ScheduledEvents that have the same name as the one provided.
SelfUser	getSelfUser()	Returns the currently logged in account represented by SelfUser.
JDA.ShardInfo	getShardInfo()	The shard information used when creating this instance of JDA.
ShardManager	getShardManager()	Returns the ShardManager that manages this JDA instances or null if this instance is not managed by any ShardManager.
JDA.Status	getStatus()	Gets the current Status of the JDA instance.
String	getToken()	The login token that is currently being used for Discord authentication.
Set<String>	getUnavailableGuilds()	Set of Guild IDs for guilds that were marked unavailable by the gateway.
default User	getUserById(long id)	This returns the User which has the same id as the one provided.
default User	getUserById(String id)	This returns the User which has the same id as the one provided.
default User	getUserByTag(String tag)	Searches for a user that has the matching Discord Tag.
default User	getUserByTag(String username, String discriminator)	Searches for a user that has the matching Discord Tag.
SnowflakeCacheView<User>	getUserCache()	SnowflakeCacheView of all cached Users visible to this JDA session.
default @Unmodifiable List<User>	getUsers()	An immutable list of all Users that share a Guild with the currently logged in account.
default @Unmodifiable List<User>	getUsersByName(String name, boolean ignoreCase)	This immutable returns all Users that have the same username as the one provided.
default AuditableRestAction<Integer>	installAuxiliaryPort()	Installs an auxiliary port for audio transfer.
boolean	isAutoReconnect()	Used to determine whether or not autoReconnect is enabled for JDA.
boolean	isBulkDeleteSplittingEnabled()	Used to determine if JDA will process MESSAGE_DELETE_BULK messages received from Discord as a single MessageBulkDeleteEvent or split the deleted messages up and fire multiple MessageDeleteEvents, one for each deleted message.
boolean	isUnavailable(long guildId)	Whether the guild is unavailable.
<E extends GenericEvent> Once.Builder<E>	listenOnce(Class<E> eventType)	Returns a reusable builder for a one-time event listener.
CacheRestAction<PrivateChannel>	openPrivateChannelById(long userId)	Opens a PrivateChannel with the provided user by id.
default CacheRestAction<PrivateChannel>	openPrivateChannelById(String userId)	Opens a PrivateChannel with the provided user by id.
void	removeEventListener(Object... listeners)	Removes all provided listeners from the event-listeners and no longer uses them to handle events.
default RestAction<ApplicationEmoji>	retrieveApplicationEmojiById(long emojiId)	Retrieves an application emoji together with its respective creator.
RestAction<ApplicationEmoji>	retrieveApplicationEmojiById(String emojiId)	Retrieves an application emoji together with its respective creator.
RestAction<List<ApplicationEmoji>>	retrieveApplicationEmojis()	Retrieves a list of Application Emojis together with their respective creators.
RestAction<ApplicationInfo>	retrieveApplicationInfo()	Retrieves the ApplicationInfo for the application that owns the logged in Bot-Account.
default RestAction<Command>	retrieveCommandById(long id)	Retrieves the existing Command instance by id.
RestAction<Command>	retrieveCommandById(String id)	Retrieves the existing Command instance by id.
default RestAction<List<Command>>	retrieveCommands()	Retrieves the list of global commands.
RestAction<List<Command>>	retrieveCommands(boolean withLocalizations)	Retrieves the list of global commands.
RestAction<Entitlement>	retrieveEntitlementById(long entitlementId)	Retrieves an Entitlement by its id.
default RestAction<Entitlement>	retrieveEntitlementById(String entitlementId)	Retrieves an Entitlement by its id.
EntitlementPaginationAction	retrieveEntitlements()	A PaginationAction implementation which allows you to iterate over Entitlements that are applicable to the logged in application.
RestAction<@Unmodifiable List<StickerPack>>	retrieveNitroStickerPacks()	Retrieves a list of all the public StickerPacks used for nitro.
RestAction<List<RoleConnectionMetadata>>	retrieveRoleConnectionMetadata()	Retrieves the currently configured RoleConnectionMetadata records for this application.
RestAction<StickerUnion>	retrieveSticker(StickerSnowflake sticker)	Attempts to retrieve a Sticker object based on the provided snowflake reference.
CacheRestAction<User>	retrieveUserById(long id)	Attempts to retrieve a User object based on the provided id.
default CacheRestAction<User>	retrieveUserById(String id)	Attempts to retrieve a User object based on the provided id.
default RestAction<Webhook>	retrieveWebhookById(long webhookId)	Retrieves a Webhook by its id.
RestAction<Webhook>	retrieveWebhookById(String webhookId)	Retrieves a Webhook by its id.
void	setAutoReconnect(boolean reconnect)	Sets whether or not JDA should try to automatically reconnect if a connection-error is encountered.
void	setEventManager(IEventManager manager)	Changes the internal EventManager.
void	setRequestTimeoutRetry(boolean retryOnTimeout)	Whether the Requester should retry when a SocketTimeoutException occurs.
default JDA	setRequiredScopes(String... scopes)	Configures the required scopes applied to the getInviteUrl(Permission...) and similar methods.
JDA	setRequiredScopes(Collection<String> scopes)	Configures the required scopes applied to the getInviteUrl(Permission...) and similar methods.
void	shutdown()	Shuts down this JDA instance, closing all its connections.
void	shutdownNow()	Shuts down this JDA instance instantly, closing all its connections.
boolean	unloadUser(long userId)	Attempts to remove the user with the provided id from the cache.
CommandListUpdateAction	updateCommands()	Configures the complete list of global commands.
RestAction<List<RoleConnectionMetadata>>	updateRoleConnectionMetadata(Collection<? extends RoleConnectionMetadata> records)	Updates the currently configured RoleConnectionMetadata records for this application.
default CommandCreateAction	upsertCommand(String name, String description)	Creates or updates a global slash command.
RestAction<Command>	upsertCommand(CommandData command)	Creates or updates a global command.

Methods inherited from interface net.dv8tion.jda.api.entities.channel.attribute.IGuildChannelContainer

getCategories, getCategoriesByName, getCategoryById, getCategoryById, getCategoryCache, getChannelById, getChannelById, getChannelCache, getForumChannelById, getForumChannelById, getForumChannelCache, getForumChannels, getForumChannelsByName, getGuildChannelById, getGuildChannelById, getGuildChannelById, getGuildChannelById, getMediaChannelById, getMediaChannelById, getMediaChannelCache, getMediaChannels, getMediaChannelsByName, getNewsChannelById, getNewsChannelById, getNewsChannelCache, getNewsChannels, getNewsChannelsByName, getStageChannelById, getStageChannelById, getStageChannelCache, getStageChannels, getStageChannelsByName, getTextChannelById, getTextChannelById, getTextChannelCache, getTextChannels, getTextChannelsByName, getThreadChannelById, getThreadChannelById, getThreadChannelCache, getThreadChannels, getThreadChannelsByName, getVoiceChannelById, getVoiceChannelById, getVoiceChannelCache, getVoiceChannels, getVoiceChannelsByName

Method Details

getStatus

@Nonnull
JDA.Status getStatus()

Gets the current Status of the JDA instance.

Returns:

Current JDA status.

getGatewayIntents

@Nonnull
EnumSet<GatewayIntent> getGatewayIntents()

The GatewayIntents for this JDA session.

Returns:

EnumSet of active gateway intents

getCacheFlags

@Nonnull
EnumSet<CacheFlag> getCacheFlags()

The cache flags that have been enabled for this JDA session.

Returns:

Copy of the EnumSet of cache flags for this session

unloadUser

boolean unloadUser(long userId)

Attempts to remove the user with the provided id from the cache.
If you attempt to remove the SelfUser this will simply return false.

This should be used by an implementation of MemberCachePolicy as an upstream request to remove a member.

Parameters:

userId - The target user id

Returns:

True, if the cache was changed

getGatewayPing

long getGatewayPing()

The time in milliseconds that discord took to respond to our last heartbeat
This roughly represents the WebSocket ping of this session

RestAction request times do not correlate to this value!

The GatewayPingEvent indicates an update to this value.

Returns:

time in milliseconds between heartbeat and the heartbeat ack response

See Also:

• Getting RestAction ping

getRestPing

@Nonnull
@CheckReturnValue
default RestAction<Long> getRestPing()

The time in milliseconds that discord took to respond to a REST request.
This will request the current user from the API and calculate the time the response took.

Example

 jda.getRestPing().queue( (time) ->
     channel.sendMessageFormat("Ping: %d ms", time).queue()
 );
 

Returns:

RestAction - Type: long

Since:

4.0.0

See Also:

• getGatewayPing()

awaitStatus

@Nonnull
default JDA awaitStatus(@Nonnull
 JDA.Status status)
                 throws InterruptedException

This method will block until JDA has reached the specified connection status.

Login Cycle

1. INITIALIZING
2. INITIALIZED
3. LOGGING_IN
4. CONNECTING_TO_WEBSOCKET
5. IDENTIFYING_SESSION
6. AWAITING_LOGIN_CONFIRMATION
7. LOADING_SUBSYSTEMS
8. CONNECTED

Parameters:

status - The init status to wait for, once JDA has reached the specified stage of the startup cycle this method will return.

Returns:

The current JDA instance, for chaining convenience

Throws:

InterruptedException - If this thread is interrupted while waiting

IllegalArgumentException - If the provided status is null or not an init status (JDA.Status.isInit())

IllegalStateException - If JDA is shutdown during this wait period

awaitStatus

@Nonnull
JDA awaitStatus(@Nonnull
 JDA.Status status,
 @Nonnull
 JDA.Status... failOn)
         throws InterruptedException

This method will block until JDA has reached the specified connection status.

Login Cycle

1. INITIALIZING
2. INITIALIZED
3. LOGGING_IN
4. CONNECTING_TO_WEBSOCKET
5. IDENTIFYING_SESSION
6. AWAITING_LOGIN_CONFIRMATION
7. LOADING_SUBSYSTEMS
8. CONNECTED

Parameters:

status - The init status to wait for, once JDA has reached the specified stage of the startup cycle this method will return.

failOn - Optional failure states that will force a premature return

Returns:

The current JDA instance, for chaining convenience

Throws:

InterruptedException - If this thread is interrupted while waiting

IllegalArgumentException - If the provided status is null or not an init status (JDA.Status.isInit())

IllegalStateException - If JDA is shutdown during this wait period

awaitReady

@Nonnull
default JDA awaitReady()
                throws InterruptedException

This method will block until JDA has reached the status JDA.Status.CONNECTED.
This status means that JDA finished setting up its internal cache and is ready to be used.

Returns:

The current JDA instance, for chaining convenience

Throws:

InterruptedException - If this thread is interrupted while waiting

IllegalStateException - If JDA is shutdown during this wait period

awaitShutdown

@CheckReturnValue
boolean awaitShutdown(long duration,
 @Nonnull
 TimeUnit unit)
               throws InterruptedException

Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
This can be useful in certain situations like disabling class loading.

Note that shutdown time depends on the length of the rate-limit queue. You can use shutdownNow() to cancel all pending requests and immediately shutdown.

Example

 jda.shutdown();
 // Allow at most 10 seconds for remaining requests to finish
 if (!jda.awaitShutdown(10, TimeUnit.SECONDS)) {
     jda.shutdownNow(); // Cancel all remaining requests
     jda.awaitShutdown(); // Wait until shutdown is complete (indefinitely)
 }
 

This will not implicitly call shutdown(), you are responsible to ensure that the shutdown process has started.

Parameters:

duration - The maximum time to wait, or 0 to wait indefinitely

unit - The time unit for the duration

Returns:

False, if the timeout has elapsed before the shutdown has completed, true otherwise.

Throws:

IllegalArgumentException - If the provided unit is null

InterruptedException - If the current thread is interrupted while waiting

awaitShutdown

@CheckReturnValue
default boolean awaitShutdown(@Nonnull
 Duration timeout)
                       throws InterruptedException

Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
This can be useful in certain situations like disabling class loading.

Note that shutdown time depends on the length of the rate-limit queue. You can use shutdownNow() to cancel all pending requests and immediately shutdown.

Example

 jda.shutdown();
 // Allow at most 10 seconds for remaining requests to finish
 if (!jda.awaitShutdown(Duration.ofSeconds(10))) {
     jda.shutdownNow(); // Cancel all remaining requests
     jda.awaitShutdown(); // Wait until shutdown is complete (indefinitely)
 }
 

This will not implicitly call shutdown(), you are responsible to ensure that the shutdown process has started.

Parameters:

timeout - The maximum time to wait, or Duration.ZERO to wait indefinitely

Returns:

False, if the timeout has elapsed before the shutdown has completed, true otherwise.

Throws:

IllegalArgumentException - If the provided timeout is null

InterruptedException - If the current thread is interrupted while waiting

awaitShutdown

default boolean awaitShutdown()
                       throws InterruptedException

Blocks the current thread until getStatus() returns JDA.Status.SHUTDOWN.
This can be useful in certain situations like disabling class loading.

This will wait indefinitely by default. Use awaitShutdown(Duration) to set a timeout.

Note that shutdown time depends on the length of the rate-limit queue. You can use shutdownNow() to cancel all pending requests and immediately shutdown.

Example

 jda.shutdown();
 // Allow at most 10 seconds for remaining requests to finish
 if (!jda.awaitShutdown(Duration.ofSeconds(10))) {
     jda.shutdownNow(); // Cancel all remaining requests
     jda.awaitShutdown(); // Wait until shutdown is complete (indefinitely)
 }
 

This will not implicitly call shutdown(), you are responsible to ensure that the shutdown process has started.

Returns:

Always true

Throws:

IllegalArgumentException - If the provided timeout is null

InterruptedException - If the current thread is interrupted while waiting

cancelRequests

int cancelRequests()

Cancels all currently scheduled RestAction requests.
When a RestAction is cancelled, a CancellationException will be provided to the failure callback. This means RestAction.queue(Consumer, Consumer) will invoke the second callback and RestAction.complete() will throw an exception.

This is only recommended as an extreme last measure to avoid backpressure. If you want to stop requests on shutdown you should use shutdownNow() instead of this method.

Returns:

how many requests were cancelled

See Also:

• RestAction.setCheck(BooleanSupplier)

getRateLimitPool

@Nonnull
ScheduledExecutorService getRateLimitPool()

ScheduledExecutorService used to handle rate-limits for RestAction executions. This is also used in other parts of JDA related to http requests.

Returns:

The ScheduledExecutorService used for http request handling

Since:

4.0.0

getGatewayPool

@Nonnull
ScheduledExecutorService getGatewayPool()

ScheduledExecutorService used to send WebSocket messages to discord.
This involves initial setup of guilds as well as keeping the connection alive.

Returns:

The ScheduledExecutorService used for WebSocket transmissions

Since:

4.0.0

getCallbackPool

@Nonnull
ExecutorService getCallbackPool()

ExecutorService used to handle RestAction callbacks and completions. This is also used for handling Message.Attachment downloads when needed.
By default this uses the CommonPool of the runtime.

Returns:

The ExecutorService used for callbacks

Since:

4.0.0

getHttpClient

@Nonnull
okhttp3.OkHttpClient getHttpClient()

The OkHttpClient used for handling http requests from RestActions.

Returns:

The http client

Since:

4.0.0

getDirectAudioController

@Nonnull
DirectAudioController getDirectAudioController()

Direct access to audio (dis-)connect requests.
This should not be used when normal audio operation is desired.

The correct way to open and close an audio connection is through the Guild's AudioManager.

Returns:

The DirectAudioController for this JDA instance

Throws:

IllegalStateException - If GatewayIntent.GUILD_VOICE_STATES is disabled

Since:

4.0.0

setEventManager

void setEventManager(@Nullable
 IEventManager manager)

Changes the internal EventManager.

The default EventManager is InterfacedEventListener.
There is also an AnnotatedEventManager available.

Parameters:

manager - The new EventManager to use

addEventListener

void addEventListener(@Nonnull
 Object... listeners)

Adds all provided listeners to the event-listeners that will be used to handle events. This uses the InterfacedEventListener by default. To switch to the AnnotatedEventManager, use setEventManager(IEventManager).

Note: when using the InterfacedEventListener (default), given listener must be instance of EventListener!

Parameters:

listeners - The listener(s) which will react to events.

Throws:

IllegalArgumentException - If either listeners or one of it's objects is null.

removeEventListener

void removeEventListener(@Nonnull
 Object... listeners)

Removes all provided listeners from the event-listeners and no longer uses them to handle events.

Parameters:

listeners - The listener(s) to be removed.

Throws:

IllegalArgumentException - If either listeners or one of it's objects is null.

getRegisteredListeners

@Nonnull
List<Object> getRegisteredListeners()

Immutable List of Objects that have been registered as EventListeners.

Returns:

List of currently registered Objects acting as EventListeners.

listenOnce

@Nonnull
@CheckReturnValue
<E extends GenericEvent> Once.Builder<E> listenOnce(@Nonnull
 Class<E> eventType)

Returns a reusable builder for a one-time event listener.

Note that this method only works if the event manager is either the InterfacedEventManager or AnnotatedEventManager.
Other implementations can support it as long as they call EventListener.onEvent(GenericEvent).

Example:

Listening to a message from a channel and a user, after using a slash command:

 final Duration timeout = Duration.ofSeconds(5);
 event.reply("Reply in " + TimeFormat.RELATIVE.after(timeout) + " if you can!")
         .setEphemeral(true)
         .queue();

 event.getJDA().listenOnce(MessageReceivedEvent.class)
         .filter(messageEvent -> messageEvent.getChannel().getIdLong() == event.getChannel().getIdLong())
         .filter(messageEvent -> messageEvent.getAuthor().getIdLong() == event.getUser().getIdLong())
         .timeout(timeout, () -> {
             event.getHook().editOriginal("Timeout!").queue();
         })
         .subscribe(messageEvent -> {
             event.getHook().editOriginal("You sent: " + messageEvent.getMessage().getContentRaw()).queue();
         });
 

Parameters:

eventType - Type of the event to listen to

Returns:

The one-time event listener builder

Throws:

IllegalArgumentException - If the provided event type is null

retrieveCommands

@Nonnull
@CheckReturnValue
default RestAction<List<Command>> retrieveCommands()

Retrieves the list of global commands.
This list does not include guild commands! Use Guild.retrieveCommands() for guild commands.
This list does not include localization data. Use retrieveCommands(boolean) to get localization data

Returns:

RestAction - Type: List of Command

retrieveCommands

@Nonnull
@CheckReturnValue
RestAction<List<Command>> retrieveCommands(boolean withLocalizations)

Retrieves the list of global commands.
This list does not include guild commands! Use Guild.retrieveCommands() for guild commands.

Parameters:

withLocalizations - true if the localization data (such as name and description) should be included

Returns:

RestAction - Type: List of Command

retrieveCommandById

@Nonnull
@CheckReturnValue
RestAction<Command> retrieveCommandById(@Nonnull
 String id)

Retrieves the existing Command instance by id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

id - The command id

Returns:

RestAction - Type: Command

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

retrieveCommandById

@Nonnull
@CheckReturnValue
default RestAction<Command> retrieveCommandById(long id)

Retrieves the existing Command instance by id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

id - The command id

Returns:

RestAction - Type: Command

upsertCommand

@Nonnull
@CheckReturnValue
RestAction<Command> upsertCommand(@Nonnull
 CommandData command)

Creates or updates a global command.
If a command with the same name exists, it will be replaced. This operation is idempotent. Commands will persist between restarts of your bot, you only have to create a command once.

To specify a complete list of all commands you can use updateCommands() instead.

You need the OAuth2 scope "applications.commands" in order to add commands to a guild.

Parameters:

command - The CommandData for the command

Returns:

RestAction - Type: Command
The RestAction used to create or update the command

Throws:

IllegalArgumentException - If null is provided

See Also:

• Commands.slash(...)
• Commands.message(...)
• Commands.user(...)
• Guild.upsertCommand(...)

upsertCommand

@Nonnull
@CheckReturnValue
default CommandCreateAction upsertCommand(@Nonnull
 String name,
 @Nonnull
 String description)

Creates or updates a global slash command.
If a command with the same name exists, it will be replaced. This operation is idempotent. Commands will persist between restarts of your bot, you only have to create a command once.

To specify a complete list of all commands you can use updateCommands() instead.

You need the OAuth2 scope "applications.commands" in order to add commands to a guild.

Parameters:

name - The lowercase alphanumeric (with dash) name, 1-32 characters

description - The description for the command, 1-100 characters

Returns:

CommandCreateAction

Throws:

IllegalArgumentException - If null is provided or the name/description do not meet the requirements

See Also:

• Guild.upsertCommand(String, String)

updateCommands

@Nonnull
@CheckReturnValue
CommandListUpdateAction updateCommands()

Configures the complete list of global commands.
This will replace the existing command list for this bot. You should only use this once on startup!

This operation is idempotent. Commands will persist between restarts of your bot, you only have to create a command once.

You need the OAuth2 scope "applications.commands" in order to add commands to a guild.

Examples

Set list to 2 commands:

 jda.updateCommands()
   .addCommands(Commands.slash("ping", "Gives the current ping"))
   .addCommands(Commands.slash("ban", "Ban the target user")
     .setGuildOnly(true)
     .setDefaultPermissions(DefaultMemberPermissions.enabledFor(Permission.BAN_MEMBERS))
     .addOption(OptionType.USER, "user", "The user to ban", true))
   .queue();
 

Delete all commands:

 jda.updateCommands().queue();
 

Returns:

CommandListUpdateAction

See Also:

• Guild.updateCommands()

editCommandById

@Nonnull
@CheckReturnValue
CommandEditAction editCommandById(@Nonnull
 String id)

Edit an existing global command by id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

id - The id of the command to edit

Returns:

CommandEditAction used to edit the command

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

editCommandById

@Nonnull
@CheckReturnValue
default CommandEditAction editCommandById(long id)

Edit an existing global command by id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

id - The id of the command to edit

Returns:

CommandEditAction used to edit the command

deleteCommandById

@Nonnull
@CheckReturnValue
RestAction<Void> deleteCommandById(@Nonnull
 String commandId)

Delete the global command for this id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

commandId - The id of the command that should be deleted

Returns:

RestAction

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

deleteCommandById

@Nonnull
@CheckReturnValue
default RestAction<Void> deleteCommandById(long commandId)

Delete the global command for this id.

If there is no command with the provided ID, this RestAction fails with ErrorResponse.UNKNOWN_COMMAND

Parameters:

commandId - The id of the command that should be deleted

Returns:

RestAction

retrieveRoleConnectionMetadata

@Nonnull
@CheckReturnValue
RestAction<List<RoleConnectionMetadata>> retrieveRoleConnectionMetadata()

Retrieves the currently configured RoleConnectionMetadata records for this application.

Returns:

RestAction - Type: List of RoleConnectionMetadata

See Also:

• Configuring App Metadata for Linked Roles

updateRoleConnectionMetadata

@Nonnull
@CheckReturnValue
RestAction<List<RoleConnectionMetadata>> updateRoleConnectionMetadata(@Nonnull
 Collection<? extends RoleConnectionMetadata> records)

Updates the currently configured RoleConnectionMetadata records for this application.

Returns the updated connection metadata records on success.

Parameters:

records - The new records to set

Returns:

RestAction - Type: List of RoleConnectionMetadata

Throws:

IllegalArgumentException - If null is provided or more than 5 records are configured.

See Also:

• Configuring App Metadata for Linked Roles

createGuild

@Nonnull
@CheckReturnValue
GuildAction createGuild(@Nonnull
 String name)

Constructs a new Guild with the specified name
Use the returned GuildAction to provide further details and settings for the resulting Guild!

This RestAction does not provide the resulting Guild! It will be in a following GuildJoinEvent.

Parameters:

name - The name of the resulting guild

Returns:

GuildAction
Allows for setting various details for the resulting Guild

Throws:

IllegalStateException - If the currently logged in account is in 10 or more guilds

IllegalArgumentException - If the provided name is empty, null or not between 2-100 characters

createGuildFromTemplate

@Nonnull
@CheckReturnValue
RestAction<Void> createGuildFromTemplate(@Nonnull
 String code,
 @Nonnull
 String name,
 @Nullable
 Icon icon)

Constructs a new Guild from the specified template code.

This RestAction does not provide the resulting Guild! It will be in a following GuildJoinEvent.

Possible ErrorResponses include:

• Unknown Guild Template
  The template doesn't exist.

Parameters:

code - The template code to use to create a guild

name - The name of the resulting guild

icon - The Icon to use, or null to use no icon

Returns:

RestAction

Throws:

IllegalStateException - If the currently logged in account is in 10 or more guilds

IllegalArgumentException - If the provided name is empty, null or not between 2-100 characters

getAudioManagerCache

@Nonnull
CacheView<AudioManager> getAudioManagerCache()

CacheView of all cached AudioManagers created for this JDA instance.
AudioManagers are created when first retrieved via Guild.getAudioManager(). Using this will perform better than calling Guild.getAudioManager() iteratively as that would cause many useless audio managers to be created!

AudioManagers are cross-session persistent!

Returns:

CacheView

getAudioManagers

@Nonnull
default @Unmodifiable List<AudioManager> getAudioManagers()

Immutable list of all created AudioManagers for this JDA instance!

Returns:

Immutable list of all created AudioManager instances

getUserCache

@Nonnull
SnowflakeCacheView<User> getUserCache()

SnowflakeCacheView of all cached Users visible to this JDA session.

Returns:

SnowflakeCacheView

getUsers

@Nonnull
default @Unmodifiable List<User> getUsers()

An immutable list of all Users that share a Guild with the currently logged in account.
This list will never contain duplicates and represents all Users that JDA can currently see.

This will only check cached users!

If the developer is sharding, then only users from guilds connected to the specifically logged in shard will be returned in the List.

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getUserCache() and use its more efficient versions of handling these values.

Returns:

Immutable list of all Users that are visible to JDA.

getUserById

@Nullable
default User getUserById(@Nonnull
 String id)

This returns the User which has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this returns null.

This will only check cached users!

Parameters:

id - The id of the requested User.

Returns:

Possibly-null User with matching id.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

See Also:

• retrieveUserById(String)

getUserById

@Nullable
default User getUserById(long id)

This returns the User which has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this returns null.

This will only check cached users!

Parameters:

id - The id of the requested User.

Returns:

Possibly-null User with matching id.

See Also:

• retrieveUserById(long)

getUserByTag

@Nullable
default User getUserByTag(@Nonnull
 String tag)

Searches for a user that has the matching Discord Tag.
Format has to be in the form Username#Discriminator where the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.

This only checks users that are known to the currently logged in account (shard). If a user exists with the tag that is not available in the User-Cache it will not be detected.
Currently Discord does not offer a way to retrieve a user by their discord tag.

This will only check cached users!

To check users without discriminators, use username#0000 instead.

Parameters:

tag - The Discord Tag in the format Username#Discriminator

Returns:

The User for the discord tag or null if no user has the provided tag

Throws:

IllegalArgumentException - If the provided tag is null or not in the described format

getUserByTag

@Nullable
default User getUserByTag(@Nonnull
 String username,
 @Nullable
 String discriminator)

Searches for a user that has the matching Discord Tag.
Format has to be in the form Username#Discriminator where the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.

This only checks users that are known to the currently logged in account (shard). If a user exists with the tag that is not available in the User-Cache it will not be detected.
Currently Discord does not offer a way to retrieve a user by their discord tag.

This will only check cached users!

Parameters:

username - The name of the user

discriminator - The discriminator of the user

Returns:

The User for the discord tag or null if no user has the provided tag

Throws:

IllegalArgumentException - If the provided arguments are null or not in the described format

getUsersByName

@Nonnull
@Incubating
default @Unmodifiable List<User> getUsersByName(@Nonnull
 String name,
 boolean ignoreCase)

This immutable returns all Users that have the same username as the one provided.
If there are no Users with the provided name, then this returns an empty list.

This will only check cached users!

Note: This does **not** consider nicknames, it only considers User.getName()

Parameters:

name - The name of the requested Users.

ignoreCase - Whether to ignore case or not when comparing the provided name to each User.getName().

Returns:

Possibly-empty immutable list of Users that all have the same name as the provided name.

Incubating:

This will be replaced in the future when the rollout of globally unique usernames has been completed.

getMutualGuilds

@Nonnull
@Unmodifiable List<Guild> getMutualGuilds(@Nonnull
 User... users)

Gets all Guilds that contain all given users as their members.

Parameters:

users - The users which all the returned Guilds must contain.

Returns:

Immutable list of all Guild instances which have all Users in them.

See Also:

• Guild.isMember(UserSnowflake)

getMutualGuilds

@Nonnull
@Unmodifiable List<Guild> getMutualGuilds(@Nonnull
 Collection<User> users)

Gets all Guilds that contain all given users as their members.

Parameters:

users - The users which all the returned Guilds must contain.

Returns:

Immutable list of all Guild instances which have all Users in them.

retrieveUserById

@Nonnull
@CheckReturnValue
default CacheRestAction<User> retrieveUserById(@Nonnull
 String id)

Attempts to retrieve a User object based on the provided id.

If getUserById(long) is cached, this will directly return the user in a completed RestAction without making a request. When both GUILD_PRESENCES and GUILD_MEMBERS intents are disabled this will always make a request even if the user is cached. You can use action.useCache(false) to force an update.

The returned RestAction can encounter the following Discord errors:

• ErrorResponse.UNKNOWN_USER
  Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).

Parameters:

id - The id of the requested User.

Returns:

CacheRestAction - Type: User
On request, gets the User with id matching provided id from Discord.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

IllegalArgumentException -

• If the provided id String is null.
• If the provided id String is empty.

retrieveUserById

@Nonnull
@CheckReturnValue
CacheRestAction<User> retrieveUserById(long id)

Attempts to retrieve a User object based on the provided id.

If getUserById(long) is cached, this will directly return the user in a completed RestAction without making a request. When both GUILD_PRESENCES and GUILD_MEMBERS intents are disabled this will always make a request even if the user is cached. You can use action.useCache(false) to force an update.

The returned RestAction can encounter the following Discord errors:

• ErrorResponse.UNKNOWN_USER
  Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).

Parameters:

id - The id of the requested User.

Returns:

CacheRestAction - Type: User
On request, gets the User with id matching provided id from Discord.

getGuildCache

@Nonnull
SnowflakeCacheView<Guild> getGuildCache()

SnowflakeCacheView of all cached Guilds visible to this JDA session.

Returns:

SnowflakeCacheView

getGuilds

@Nonnull
default @Unmodifiable List<Guild> getGuilds()

An immutable List of all Guilds that the logged account is connected to.
If this account is not connected to any Guilds, this will return an empty list.

If the developer is sharding (JDABuilder.useSharding(int, int), then this list will only contain the Guilds that the shard is actually connected to. Discord determines which guilds a shard is connect to using the following format:
Guild connected if shardId == (guildId >> 22) % totalShards;
Source for formula: Discord Documentation

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getGuildCache() and use its more efficient versions of handling these values.

Returns:

Possibly-empty immutable list of all the Guilds that this account is connected to.

getGuildById

@Nullable
default Guild getGuildById(@Nonnull
 String id)

This returns the Guild which has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, then this returns null.

Parameters:

id - The id of the Guild.

Returns:

Possibly-null Guild with matching id.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getGuildById

@Nullable
default Guild getGuildById(long id)

This returns the Guild which has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, then this returns null.

Parameters:

id - The id of the Guild.

Returns:

Possibly-null Guild with matching id.

getGuildsByName

@Nonnull
default @Unmodifiable List<Guild> getGuildsByName(@Nonnull
 String name,
 boolean ignoreCase)

An immutable list of all Guilds that have the same name as the one provided.
If there are no Guilds with the provided name, then this returns an empty list.

Parameters:

name - The name of the requested Guilds.

ignoreCase - Whether to ignore case or not when comparing the provided name to each Guild.getName().

Returns:

Possibly-empty immutable list of all the Guilds that all have the same name as the provided name.

getUnavailableGuilds

@Nonnull
Set<String> getUnavailableGuilds()

Set of Guild IDs for guilds that were marked unavailable by the gateway.
When a guild becomes unavailable a GuildUnavailableEvent is emitted and a GuildAvailableEvent is emitted when it becomes available again. During the time a guild is unavailable it its not reachable through cache such as getGuildById(long).

Returns:

Possibly-empty set of guild IDs for unavailable guilds

isUnavailable

boolean isUnavailable(long guildId)

Whether the guild is unavailable. If this returns true, the guild id should be in getUnavailableGuilds().

Parameters:

guildId - The guild id

Returns:

True, if this guild is unavailable

getRoleCache

@Nonnull
SnowflakeCacheView<Role> getRoleCache()

Unified SnowflakeCacheView of all cached Roles visible to this JDA session.

Returns:

Unified SnowflakeCacheView

See Also:

• CacheView.allSnowflakes(...)

getRoles

@Nonnull
default @Unmodifiable List<Role> getRoles()

All Roles this JDA instance can see.
This will iterate over each Guild retrieved from getGuilds() and collect its Guild.getRoles().

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getRoleCache() and use its more efficient versions of handling these values.

Returns:

Immutable List of all visible Roles

getRoleById

@Nullable
default Role getRoleById(@Nonnull
 String id)

Retrieves the Role associated to the provided id.
This iterates over all Guilds and check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.

Parameters:

id - The id of the searched Role

Returns:

Possibly-null Role for the specified ID

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getRoleById

@Nullable
default Role getRoleById(long id)

Retrieves the Role associated to the provided id.
This iterates over all Guilds and check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.

Parameters:

id - The id of the searched Role

Returns:

Possibly-null Role for the specified ID

getRolesByName

@Nonnull
default @Unmodifiable List<Role> getRolesByName(@Nonnull
 String name,
 boolean ignoreCase)

Retrieves all Roles visible to this JDA instance.
This simply filters the Roles returned by getRoles() with the provided name, either using String.equals(Object) or String.equalsIgnoreCase(String) on Role.getName().

Parameters:

name - The name for the Roles

ignoreCase - Whether to use String.equalsIgnoreCase(String)

Returns:

Immutable List of all Roles matching the parameters provided.

getScheduledEventCache

@Nonnull
SnowflakeCacheView<ScheduledEvent> getScheduledEventCache()

SnowflakeCacheView of all cached ScheduledEvents visible to this JDA session.

This requires CacheFlag.SCHEDULED_EVENTS to be enabled.

Returns:

SnowflakeCacheView

getScheduledEvents

@Nonnull
default @Unmodifiable List<ScheduledEvent> getScheduledEvents()

An unmodifiable list of all ScheduledEvents of all connected Guilds.

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getScheduledEventCache() and use its more efficient versions of handling these values.

This requires CacheFlag.SCHEDULED_EVENTS to be enabled.

Returns:

Possibly-empty immutable list of all known ScheduledEvents.

getScheduledEventById

@Nullable
default ScheduledEvent getScheduledEventById(@Nonnull
 String id)

This returns the ScheduledEvent which has the same id as the one provided.
If there is no known ScheduledEvent with an id that matches the provided one, then this returns null.

This requires CacheFlag.SCHEDULED_EVENTS to be enabled.

Parameters:

id - The id of the ScheduledEvent.

Returns:

Possibly-null ScheduledEvent with a matching id.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getScheduledEventById

@Nullable
default ScheduledEvent getScheduledEventById(long id)

This returns the ScheduledEvent which has the same id as the one provided.
If there is no known ScheduledEvent with an id that matches the provided one, then this returns null.

This requires CacheFlag.SCHEDULED_EVENTS to be enabled.

Parameters:

id - The id of the ScheduledEvent.

Returns:

Possibly-null ScheduledEvent with a matching id.

getScheduledEventsByName

@Nonnull
default @Unmodifiable List<ScheduledEvent> getScheduledEventsByName(@Nonnull
 String name,
 boolean ignoreCase)

An unmodifiable list of all ScheduledEvents that have the same name as the one provided.
If there are no ScheduledEvents with the provided name, then this returns an empty list.

This requires CacheFlag.SCHEDULED_EVENTS to be enabled.

Parameters:

name - The name of the requested ScheduledEvent.

ignoreCase - Whether to ignore case or not when comparing the provided name to each ScheduledEvent.getName().

Returns:

Possibly-empty immutable list of all the ScheduledEvents that all have the same name as the provided name.

Throws:

IllegalArgumentException - If the provided name is null.

getPrivateChannelCache

@Nonnull
SnowflakeCacheView<PrivateChannel> getPrivateChannelCache()

SnowflakeCacheView of all cached PrivateChannels visible to this JDA session.

Returns:

SnowflakeCacheView

getPrivateChannels

@Nonnull
default @Unmodifiable List<PrivateChannel> getPrivateChannels()

An unmodifiable list of all known PrivateChannels.

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getPrivateChannelCache() and use its more efficient versions of handling these values.

Returns:

Possibly-empty list of all PrivateChannels.

getPrivateChannelById

@Nullable
default PrivateChannel getPrivateChannelById(@Nonnull
 String id)

This returns the PrivateChannel which has the same id as the one provided.
If there is no known PrivateChannel with an id that matches the provided one, then this returns null.

Parameters:

id - The id of the PrivateChannel.

Returns:

Possibly-null PrivateChannel with matching id.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getPrivateChannelById

@Nullable
default PrivateChannel getPrivateChannelById(long id)

This returns the PrivateChannel which has the same id as the one provided.
If there is no known PrivateChannel with an id that matches the provided one, then this returns null.

Parameters:

id - The id of the PrivateChannel.

Returns:

Possibly-null PrivateChannel with matching id.

openPrivateChannelById

@Nonnull
@CheckReturnValue
CacheRestAction<PrivateChannel> openPrivateChannelById(long userId)

Opens a PrivateChannel with the provided user by id.
This will fail with UNKNOWN_USER if the user does not exist.

If the channel is cached, this will directly return the channel in a completed RestAction without making a request. You can use action.useCache(false) to force an update.

Example

 public void sendMessage(JDA jda, long userId, String content) {
     jda.openPrivateChannelById(userId)
        .flatMap(channel -> channel.sendMessage(content))
        .queue();
 }
 

Parameters:

userId - The id of the target user

Returns:

CacheRestAction - Type: PrivateChannel

Throws:

UnsupportedOperationException - If the target user is the currently logged in account

See Also:

• User.openPrivateChannel()

openPrivateChannelById

@Nonnull
@CheckReturnValue
default CacheRestAction<PrivateChannel> openPrivateChannelById(@Nonnull
 String userId)

Opens a PrivateChannel with the provided user by id.
This will fail with UNKNOWN_USER if the user does not exist.

If the channel is cached, this will directly return the channel in a completed RestAction without making a request. You can use action.useCache(false) to force an update.

Example

 public void sendMessage(JDA jda, String userId, String content) {
     jda.openPrivateChannelById(userId)
        .flatMap(channel -> channel.sendMessage(content))
        .queue();
 }
 

Parameters:

userId - The id of the target user

Returns:

RestAction - Type: PrivateChannel

Throws:

UnsupportedOperationException - If the target user is the currently logged in account

IllegalArgumentException - If the provided id is not a valid snowflake

See Also:

• User.openPrivateChannel()

getEmojiCache

@Nonnull
SnowflakeCacheView<RichCustomEmoji> getEmojiCache()

Unified SnowflakeCacheView of all cached Custom Emojis visible to this JDA session.

Returns:

Unified SnowflakeCacheView

See Also:

• CacheView.allSnowflakes(...)

getEmojis

@Nonnull
default @Unmodifiable List<RichCustomEmoji> getEmojis()

A collection of all to us known custom emoji (managed/restricted included).
This will be empty if CacheFlag.EMOJI is disabled.

Hint: To check whether you can use an RichCustomEmoji in a specific context you can use RichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.Member) or RichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.User, MessageChannel)

Unicode emojis are not included as Custom Emoji!

This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use getEmojiCache() and use its more efficient versions of handling these values.

Returns:

An immutable list of Custom Emojis (which may or may not be available to usage).

getEmojiById

@Nullable
default RichCustomEmoji getEmojiById(@Nonnull
 String id)

Retrieves a custom emoji matching the specified id if one is available in our cache.
This will be null if CacheFlag.EMOJI is disabled.

Unicode emojis are not included as Custom Emoji!

Parameters:

id - The id of the requested RichCustomEmoji.

Returns:

A Custom Emoji represented by this id or null if none is found in our cache.

Throws:

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getEmojiById

@Nullable
default RichCustomEmoji getEmojiById(long id)

Retrieves a custom emoji matching the specified id if one is available in our cache.
This will be null if CacheFlag.EMOJI is disabled.

Unicode emojis are not included as Custom Emoji!

Parameters:

id - The id of the requested RichCustomEmoji.

Returns:

A Custom Emoji represented by this id or null if none is found in our cache.

getEmojisByName

@Nonnull
default @Unmodifiable List<RichCustomEmoji> getEmojisByName(@Nonnull
 String name,
 boolean ignoreCase)

An unmodifiable list of all Custom Emojis that have the same name as the one provided.
If there are no Custom Emojis with the provided name, then this returns an empty list.
This will be empty if CacheFlag.EMOJI is disabled.

Unicode emojis are not included as Custom Emoji!

Parameters:

name - The name of the requested Custom Emojis. Without colons.

ignoreCase - Whether to ignore case or not when comparing the provided name to each Emoji.getName().

Returns:

Possibly-empty list of all the Custom Emojis that all have the same name as the provided name.

createApplicationEmoji

@Nonnull
@CheckReturnValue
RestAction<ApplicationEmoji> createApplicationEmoji(@Nonnull
 String name,
 @Nonnull
 Icon icon)

Creates a new ApplicationEmoji for this bot.

Note that the bot is limited to 2000 Application Emojis (normal and animated).

Parameters:

name - The name for the new emoji (2-32 characters)

icon - The Icon for the new emoji

Returns:

RestAction - Type: ApplicationEmoji

Throws:

IllegalArgumentException - If null is provided or the name is not alphanumeric or not between 2 and 32 characters long

retrieveApplicationEmojis

@Nonnull
@CheckReturnValue
RestAction<List<ApplicationEmoji>> retrieveApplicationEmojis()

Retrieves a list of Application Emojis together with their respective creators.

Returns:

RestAction - Type: List of ApplicationEmoji

retrieveApplicationEmojiById

@Nonnull
@CheckReturnValue
default RestAction<ApplicationEmoji> retrieveApplicationEmojiById(long emojiId)

Retrieves an application emoji together with its respective creator.

Parameters:

emojiId - The emoji id

Returns:

RestAction - Type: ApplicationEmoji

retrieveApplicationEmojiById

@Nonnull
@CheckReturnValue
RestAction<ApplicationEmoji> retrieveApplicationEmojiById(@Nonnull
 String emojiId)

Retrieves an application emoji together with its respective creator.

Parameters:

emojiId - The emoji id

Returns:

RestAction - Type: ApplicationEmoji

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

retrieveSticker

@Nonnull
@CheckReturnValue
RestAction<StickerUnion> retrieveSticker(@Nonnull
 StickerSnowflake sticker)

Attempts to retrieve a Sticker object based on the provided snowflake reference.
This works for both StandardSticker and GuildSticker, and you can resolve them using the provided StickerUnion.

If the sticker is not one of the supported Types, the request fails with IllegalArgumentException.

The returned RestAction can encounter the following Discord errors:

• UNKNOWN_STICKER
  Occurs when the provided id does not refer to a sticker known by Discord.

Parameters:

sticker - The reference of the requested Sticker.
Can be RichSticker, StickerItem, or Sticker.fromId(long).

Returns:

RestAction - Type: StickerUnion
On request, gets the sticker with id matching provided id from Discord.

Throws:

IllegalArgumentException - If the provided sticker is null

retrieveNitroStickerPacks

@Nonnull
@CheckReturnValue
RestAction<@Unmodifiable List<StickerPack>> retrieveNitroStickerPacks()

Retrieves a list of all the public StickerPacks used for nitro.

Returns:

RestAction - Type: List of StickerPack

getEventManager

@Nonnull
IEventManager getEventManager()

The EventManager used by this JDA instance.

Returns:

The IEventManager

getSelfUser

@Nonnull
SelfUser getSelfUser()

Returns the currently logged in account represented by SelfUser.
Account settings cannot be modified using this object. If you wish to modify account settings please use the AccountManager which is accessible by SelfUser.getManager().

Returns:

The currently logged in account.

getPresence

@Nonnull
Presence getPresence()

The Presence controller for the current session.
Used to set Activity and OnlineStatus information.

Returns:

The never-null Presence for this session.

getShardInfo

@Nonnull
JDA.ShardInfo getShardInfo()

The shard information used when creating this instance of JDA.
Represents the information provided to JDABuilder.useSharding(int, int).

Returns:

The shard information for this shard

getToken

@Nonnull
String getToken()

The login token that is currently being used for Discord authentication.

Returns:

Never-null, 18 character length string containing the auth token.

getResponseTotal

long getResponseTotal()

This value is the total amount of JSON responses that discord has sent.
This value resets every time the websocket has to perform a full reconnect (not resume).

Returns:

Never-negative long containing total response amount.

getMaxReconnectDelay

int getMaxReconnectDelay()

This value is the maximum amount of time, in seconds, that JDA will wait between reconnect attempts.
Can be set using JDABuilder.setMaxReconnectDelay(int).

Returns:

The maximum amount of time JDA will wait between reconnect attempts in seconds.

setAutoReconnect

void setAutoReconnect(boolean reconnect)

Sets whether or not JDA should try to automatically reconnect if a connection-error is encountered.
This will use an incremental reconnect (timeouts are increased each time an attempt fails).

Default is true.

Parameters:

reconnect - If true - enables autoReconnect

setRequestTimeoutRetry

void setRequestTimeoutRetry(boolean retryOnTimeout)

Whether the Requester should retry when a SocketTimeoutException occurs.

Parameters:

retryOnTimeout - True, if the Request should retry once on a socket timeout

isAutoReconnect

boolean isAutoReconnect()

Used to determine whether or not autoReconnect is enabled for JDA.

Returns:

True if JDA will attempt to automatically reconnect when a connection-error is encountered.

isBulkDeleteSplittingEnabled

boolean isBulkDeleteSplittingEnabled()

Used to determine if JDA will process MESSAGE_DELETE_BULK messages received from Discord as a single MessageBulkDeleteEvent or split the deleted messages up and fire multiple MessageDeleteEvents, one for each deleted message.

By default, JDA will separate the bulk delete event into individual delete events, but this isn't as efficient as handling a single event would be. It is recommended that BulkDelete Splitting be disabled and that the developer should instead handle the MessageBulkDeleteEvent

Returns:

Whether or not JDA currently handles the BULK_MESSAGE_DELETE event by splitting it into individual MessageDeleteEvents or not.

shutdown

void shutdown()

Shuts down this JDA instance, closing all its connections. After this command is issued the JDA Instance can not be used anymore. Already enqueued RestActions are still going to be executed.

If you want this instance to shutdown without executing, use shutdownNow()

This will interrupt the default JDA event thread, due to the gateway connection being interrupted.

See Also:

• shutdownNow()

shutdownNow

void shutdownNow()

Shuts down this JDA instance instantly, closing all its connections. After this command is issued the JDA Instance can not be used anymore. This will also cancel all queued RestActions.

If you want this instance to shutdown without cancelling enqueued RestActions use shutdown()

This will interrupt the default JDA event thread, due to the gateway connection being interrupted.

See Also:

• shutdown()

retrieveApplicationInfo

@Nonnull
@CheckReturnValue
RestAction<ApplicationInfo> retrieveApplicationInfo()

Retrieves the ApplicationInfo for the application that owns the logged in Bot-Account.
This contains information about the owner of the currently logged in bot account!

Returns:

RestAction - Type: ApplicationInfo
The ApplicationInfo of the bot's application.

retrieveEntitlements

@Nonnull
@CheckReturnValue
EntitlementPaginationAction retrieveEntitlements()

A PaginationAction implementation which allows you to iterate over Entitlements that are applicable to the logged in application.

Returns:

EntitlementPaginationAction

retrieveEntitlementById

@Nonnull
@CheckReturnValue
default RestAction<Entitlement> retrieveEntitlementById(@Nonnull
 String entitlementId)

Retrieves an Entitlement by its id.

Parameters:

entitlementId - The id of the entitlement to retrieve

Returns:

RestAction - Type: Entitlement
The entitlement with the provided id

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

retrieveEntitlementById

@Nonnull
@CheckReturnValue
RestAction<Entitlement> retrieveEntitlementById(long entitlementId)

Retrieves an Entitlement by its id.

Parameters:

entitlementId - The id of the entitlement to retrieve

Returns:

RestAction - Type: Entitlement
The entitlement with the provided id

createTestEntitlement

@Nonnull
@CheckReturnValue
default TestEntitlementCreateAction createTestEntitlement(@Nonnull
 String skuId,
 @Nonnull
 String ownerId,
 @Nonnull
 TestEntitlementCreateAction.OwnerType ownerType)

Constructs a new Entitlement with the skuId and the type.
Use the returned TestEntitlementCreateAction to provide more details.

Parameters:

skuId - The id of the SKU the entitlement is for

ownerId - The id of the owner of the entitlement

ownerType - The type of the owner of the entitlement

Returns:

TestEntitlementCreateAction
Allows for setting various details for the resulting Entitlement

Throws:

IllegalArgumentException - If the provided skuId or ownerId is not a valid snowflake

createTestEntitlement

@Nonnull
@CheckReturnValue
TestEntitlementCreateAction createTestEntitlement(long skuId,
 long ownerId,
 @Nonnull
 TestEntitlementCreateAction.OwnerType ownerType)

Constructs a new Entitlement with the skuId and the type.
Use the returned TestEntitlementCreateAction to provide more details.

Parameters:

skuId - The id of the SKU the entitlement is for

ownerId - The id of the owner of the entitlement

ownerType - The type of the owner of the entitlement

Returns:

TestEntitlementCreateAction
Allows for setting various details for the resulting Entitlement

Throws:

IllegalArgumentException - If the provided ownerType is null

deleteTestEntitlement

@Nonnull
@CheckReturnValue
default RestAction<Void> deleteTestEntitlement(@Nonnull
 String entitlementId)

Deletes a test entitlement by its id.

Parameters:

entitlementId - The id of the entitlement to delete

Returns:

RestAction - Type: Void

Throws:

IllegalArgumentException - If the provided id is not a valid snowflake

deleteTestEntitlement

@Nonnull
@CheckReturnValue
RestAction<Void> deleteTestEntitlement(long entitlementId)

Deletes a test entitlement by its id.

Parameters:

entitlementId - The id of the entitlement to delete

Returns:

RestAction - Type: Void

setRequiredScopes

@Nonnull
default JDA setRequiredScopes(@Nonnull
 String... scopes)

Configures the required scopes applied to the getInviteUrl(Permission...) and similar methods.
To use slash commands you must add "applications.commands" to these scopes. The scope "bot" is always applied.

Parameters:

scopes - The scopes to use with getInviteUrl(Permission...) and the likes

Returns:

The current JDA instance

Throws:

IllegalArgumentException - If null is provided

setRequiredScopes

@Nonnull
JDA setRequiredScopes(@Nonnull
 Collection<String> scopes)

Configures the required scopes applied to the getInviteUrl(Permission...) and similar methods.
To use slash commands you must add "applications.commands" to these scopes. The scope "bot" is always applied.

Parameters:

scopes - The scopes to use with getInviteUrl(Permission...) and the likes

Returns:

The current JDA instance

Throws:

IllegalArgumentException - If null is provided

getInviteUrl

@Nonnull
String getInviteUrl(@Nullable
 Permission... permissions)

Creates an authorization invite url for the currently logged in Bot-Account.
Example Format: https://discord.com/oauth2/authorize?scope=bot&client_id=288202953599221761&permissions=8

Hint: To enable a pre-selected Guild of choice append the parameter &guild_id=YOUR_GUILD_ID

Parameters:

permissions - The permissions to use in your invite, these can be changed by the link user.
If no permissions are provided the permissions parameter is omitted

Returns:

A valid OAuth2 invite url for the currently logged in Bot-Account

getInviteUrl

@Nonnull
String getInviteUrl(@Nullable
 Collection<Permission> permissions)

Creates an authorization invite url for the currently logged in Bot-Account.
Example Format: https://discord.com/oauth2/authorize?scope=bot&client_id=288202953599221761&permissions=8

Hint: To enable a pre-selected Guild of choice append the parameter &guild_id=YOUR_GUILD_ID

Parameters:

permissions - The permissions to use in your invite, these can be changed by the link user.
If no permissions are provided the permissions parameter is omitted

Returns:

A valid OAuth2 invite url for the currently logged in Bot-Account

getShardManager

@Nullable
ShardManager getShardManager()

Returns the ShardManager that manages this JDA instances or null if this instance is not managed by any ShardManager.

Returns:

The corresponding ShardManager or null if there is no such manager

retrieveWebhookById

@Nonnull
@CheckReturnValue
RestAction<Webhook> retrieveWebhookById(@Nonnull
 String webhookId)

Retrieves a Webhook by its id.
If the webhook does not belong to any known guild of this JDA session, it will be partial.

Possible ErrorResponses caused by the returned RestAction include the following:

• MISSING_PERMISSIONS
  We do not have the required permissions
• UNKNOWN_WEBHOOK
  A webhook with this id does not exist

Parameters:

webhookId - The webhook id

Returns:

RestAction - Type: Webhook
The webhook object.

Throws:

IllegalArgumentException - If the webhookId is null or empty

See Also:

• Guild.retrieveWebhooks()
• IWebhookContainer.retrieveWebhooks()

retrieveWebhookById

@Nonnull
@CheckReturnValue
default RestAction<Webhook> retrieveWebhookById(long webhookId)

Retrieves a Webhook by its id.
If the webhook does not belong to any known guild of this JDA session, it will be partial.

Possible ErrorResponses caused by the returned RestAction include the following:

• MISSING_PERMISSIONS
  We do not have the required permissions
• UNKNOWN_WEBHOOK
  A webhook with this id does not exist

Parameters:

webhookId - The webhook id

Returns:

RestAction - Type: Webhook
The webhook object.

See Also:

• Guild.retrieveWebhooks()
• IWebhookContainer.retrieveWebhooks()

installAuxiliaryPort

@Nonnull
@CheckReturnValue
default AuditableRestAction<Integer> installAuxiliaryPort()

Installs an auxiliary port for audio transfer.

Returns:

AuditableRestAction - Type: int Provides the resulting used port

Throws:

IllegalStateException - If this is a headless environment or no port is available