Interface JDA
- All Superinterfaces:
IGuildChannelContainer
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic classRepresents the information used to create this shard.static enumRepresents the connection status of JDA and its Main WebSocket. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddEventListener(Object... listeners) Adds all provided listeners to the event-listeners that will be used to handle events.default JDAThis method will block until JDA has reached the statusJDA.Status.CONNECTED.default JDAawaitStatus(JDA.Status status) This method will block until JDA has reached the specified connection status.awaitStatus(JDA.Status status, JDA.Status... failOn) This method will block until JDA has reached the specified connection status.intCancels all currently scheduledRestActionrequests.createGuild(String name) Constructs a newGuildwith the specified name
Use the returnedGuildActionto provide further details and settings for the resulting Guild!createGuildFromTemplate(String code, String name, Icon icon) Constructs a newGuildfrom the specified template code.default RestAction<Void>deleteCommandById(long commandId) Delete the global command for this id.deleteCommandById(String commandId) Delete the global command for this id.default CommandEditActioneditCommandById(long id) Edit an existing global command by id.Edit an existing global command by id.TheAccountTypeof the currently logged in account.CacheViewof all cachedAudioManagerscreated for this JDA instance.default List<AudioManager>Immutable list of all createdAudioManagersfor this JDA instance!Thecache flagsthat have been enabled for this JDA session.ExecutorServiceused to handleRestActioncallbacks and completions.default <T extends Channel>
TgetChannelById(Class<T> type, long id) Get a channel of the specified type by id.Direct access to audio (dis-)connect requests.default RichCustomEmojigetEmojiById(long id) Retrieves a custom emoji matching the specifiedidif one is available in our cache.default RichCustomEmojigetEmojiById(String id) Retrieves a custom emoji matching the specifiedidif one is available in our cache.UnifiedSnowflakeCacheViewof all cachedCustom Emojisvisible to this JDA session.default List<RichCustomEmoji>A collection of all to us known custom emoji (managed/restricted included).default List<RichCustomEmoji>getEmojisByName(String name, boolean ignoreCase) An unmodifiable list of allCustom Emojisthat have the same name as the one provided.The EventManager used by this JDA instance.TheGatewayIntentsfor this JDA session.longThe time in milliseconds that discord took to respond to our last heartbeat
This roughly represents the WebSocket ping of this sessionScheduledExecutorServiceused to send WebSocket messages to discord.default GuildgetGuildById(long id) This returns theGuildwhich has the same id as the one provided.default GuildgetGuildById(String id) This returns theGuildwhich has the same id as the one provided.SnowflakeCacheViewof all cachedGuildsvisible to this JDA session.An immutable List of allGuildsthat the logged account is connected to.getGuildsByName(String name, boolean ignoreCase) An immutable list of allGuildsthat have the same name as the one provided.okhttp3.OkHttpClientTheOkHttpClientused for handling http requests fromRestActions.getInviteUrl(Collection<Permission> permissions) Creates an authorization invite url for the currently logged in Bot-Account.getInviteUrl(Permission... permissions) Creates an authorization invite url for the currently logged in Bot-Account.intThis value is the maximum amount of time, in seconds, that JDA will wait between reconnect attempts.getMutualGuilds(Collection<User> users) Gets allGuildsthat contain all given users as their members.getMutualGuilds(User... users) Gets allGuildsthat contain all given users as their members.ThePresencecontroller for the current session.default PrivateChannelgetPrivateChannelById(long id) This returns thePrivateChannelwhich has the same id as the one provided.default PrivateChannelThis returns thePrivateChannelwhich has the same id as the one provided.SnowflakeCacheViewof all cachedPrivateChannelsvisible to this JDA session.default List<PrivateChannel>An unmodifiable list of all knownPrivateChannels.ScheduledExecutorServiceused to handle rate-limits forRestActionexecutions.Immutable List of Objects that have been registered as EventListeners.longThis value is the total amount of JSON responses that discord has sent.default RestAction<Long>The time in milliseconds that discord took to respond to a REST request.default RolegetRoleById(long id) Retrieves theRoleassociated to the provided id.default RolegetRoleById(String id) Retrieves theRoleassociated to the provided id.UnifiedSnowflakeCacheViewof all cachedRolesvisible to this JDA session.getRoles()AllRolesthis JDA instance can see.getRolesByName(String name, boolean ignoreCase) Retrieves allRolesvisible to this JDA instance.Returns the currently logged in account represented bySelfUser.The shard information used when creating this instance of JDA.Returns theShardManagerthat manages this JDA instances or null if this instance is not managed by anyShardManager.Gets the currentStatusof the JDA instance.getToken()The login token that is currently being used for Discord authentication.Set ofGuildIDs for guilds that were marked unavailable by the gateway.default UsergetUserById(long id) This returns theUserwhich has the same id as the one provided.default UsergetUserById(String id) This returns theUserwhich has the same id as the one provided.default UsergetUserByTag(String tag) Searches for a user that has the matching Discord Tag.default UsergetUserByTag(String username, String discriminator) Searches for a user that has the matching Discord Tag.SnowflakeCacheViewof all cachedUsersvisible to this JDA session.getUsers()getUsersByName(String name, boolean ignoreCase) This immutable returns allUsersthat have the same username as the one provided.default AuditableRestAction<Integer>Installs an auxiliary port for audio transfer.booleanUSed to determine whether or not autoReconnect is enabled for JDA.booleanUsed to determine if JDA will process MESSAGE_DELETE_BULK messages received from Discord as a singleMessageBulkDeleteEventor split the deleted messages up and fire multipleMessageDeleteEvents, one for each deleted message.booleanisUnavailable(long guildId) Whether the guild is unavailable.openPrivateChannelById(long userId) Opens aPrivateChannelwith the provided user by id.default RestAction<PrivateChannel>openPrivateChannelById(String userId) Opens aPrivateChannelwith the provided user by id.voidremoveEventListener(Object... listeners) Removes all provided listeners from the event-listeners and no longer uses them to handle events.Retrieves theApplicationInfofor the application that owns the logged in Bot-Account.default RestAction<Command>retrieveCommandById(long id) Retrieves the existingCommandinstance by id.Retrieves the existingCommandinstance by id.default RestAction<List<Command>>Retrieves the list of global commands.retrieveCommands(boolean withLocalizations) Retrieves the list of global commands.Retrieves a list of all the publicStickerPacksused for nitro.retrieveSticker(StickerSnowflake sticker) Attempts to retrieve aStickerobject based on the provided snowflake reference.retrieveUserById(long id) Attempts to retrieve aUserobject based on the provided id.default CacheRestAction<User>Attempts to retrieve aUserobject based on the provided id.default RestAction<Webhook>retrieveWebhookById(long webhookId) Retrieves aWebhookby its id.retrieveWebhookById(String webhookId) Retrieves aWebhookby its id.voidsetAutoReconnect(boolean reconnect) Sets whether or not JDA should try to automatically reconnect if a connection-error is encountered.voidsetEventManager(IEventManager manager) Changes the internal EventManager.voidsetRequestTimeoutRetry(boolean retryOnTimeout) Whether the Requester should retry when aSocketTimeoutExceptionoccurs.default JDAsetRequiredScopes(String... scopes) Configures the required scopes applied to thegetInviteUrl(Permission...)and similar methods.setRequiredScopes(Collection<String> scopes) Configures the required scopes applied to thegetInviteUrl(Permission...)and similar methods.voidshutdown()Shuts down this JDA instance, closing all its connections.voidShuts down this JDA instance instantly, closing all its connections.booleanunloadUser(long userId) Attempts to remove the user with the provided id from the cache.Configures the complete list of global commands.default CommandCreateActionupsertCommand(String name, String description) Creates or updates a global slash command.upsertCommand(CommandData command) Creates or updates a global command.Methods inherited from interface net.dv8tion.jda.api.entities.channel.IGuildChannelContainer
getCategories, getCategoriesByName, getCategoryById, getCategoryById, getCategoryCache, getChannelById, getGuildChannelById, getGuildChannelById, getGuildChannelById, getGuildChannelById, 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
Gets the currentStatusof the JDA instance.- Returns:
- Current JDA status.
-
getGatewayIntents
TheGatewayIntentsfor this JDA session.- Returns:
EnumSetof active gateway intents
-
getCacheFlags
Thecache flagsthat 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 theSelfUserthis will simply returnfalse.This should be used by an implementation of
MemberCachePolicyas 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 sessionRestActionrequest times do not correlate to this value!The
GatewayPingEventindicates an update to this value.- Returns:
- time in milliseconds between heartbeat and the heartbeat ack response
- See Also:
-
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:
-
awaitStatus
This method will block until JDA has reached the specified connection status.Login Cycle
- 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 waitingIllegalArgumentException- 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
- 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 waitingIllegalArgumentException- If the provided status is null or not an init status (JDA.Status.isInit())IllegalStateException- If JDA is shutdown during this wait period
-
awaitReady
This method will block until JDA has reached the statusJDA.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 waitingIllegalStateException- If JDA is shutdown during this wait period
-
cancelRequests
int cancelRequests()Cancels all currently scheduledRestActionrequests.
When aRestActionis cancelled, aCancellationExceptionwill be provided to the failure callback. This meansRestAction.queue(Consumer, Consumer)will invoke the second callback andRestAction.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:
-
getRateLimitPool
ScheduledExecutorServiceused to handle rate-limits forRestActionexecutions. This is also used in other parts of JDA related to http requests.- Returns:
- The
ScheduledExecutorServiceused for http request handling - Since:
- 4.0.0
-
getGatewayPool
ScheduledExecutorServiceused to send WebSocket messages to discord.
This involves initial setup of guilds as well as keeping the connection alive.- Returns:
- The
ScheduledExecutorServiceused for WebSocket transmissions - Since:
- 4.0.0
-
getCallbackPool
ExecutorServiceused to handleRestActioncallbacks and completions. This is also used for handlingMessage.Attachmentdownloads when needed.
By default this uses theCommonPoolof the runtime.- Returns:
- The
ExecutorServiceused for callbacks - Since:
- 4.0.0
-
getHttpClient
TheOkHttpClientused for handling http requests fromRestActions.- Returns:
- The http client
- Since:
- 4.0.0
-
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'sAudioManager.- Returns:
- The
DirectAudioControllerfor this JDA instance - Throws:
IllegalStateException- IfGatewayIntent.GUILD_VOICE_STATESis disabled- Since:
- 4.0.0
-
setEventManager
Changes the internal EventManager.The default EventManager is
InterfacedEventListener.
There is also anAnnotatedEventManageravailable.- Parameters:
manager- The new EventManager to use
-
addEventListener
Adds all provided listeners to the event-listeners that will be used to handle events. This uses theInterfacedEventListenerby default. To switch to theAnnotatedEventManager, usesetEventManager(IEventManager). Note: when using theInterfacedEventListener(default), given listener must be instance ofEventListener!- Parameters:
listeners- The listener(s) which will react to events.- Throws:
IllegalArgumentException- If either listeners or one of it's objects isnull.
-
removeEventListener
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 isnull.
-
getRegisteredListeners
Immutable List of Objects that have been registered as EventListeners.- Returns:
- List of currently registered Objects acting as EventListeners.
-
retrieveCommands
Retrieves the list of global commands.
This list does not include guild commands! UseGuild.retrieveCommands()for guild commands.
This list does not include localization data. UseretrieveCommands(boolean)to get localization data- Returns:
RestAction- Type:ListofCommand
-
retrieveCommands
Retrieves the list of global commands.
This list does not include guild commands! UseGuild.retrieveCommands()for guild commands.- Parameters:
withLocalizations-trueif the localization data (such as name and description) should be included- Returns:
RestAction- Type:ListofCommand
-
retrieveCommandById
Retrieves the existingCommandinstance 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
Retrieves the existingCommandinstance 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
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- TheCommandDatafor the command- Returns:
RestAction- Type:Command
The RestAction used to create or update the command- Throws:
IllegalArgumentException- If null is provided- See Also:
-
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 charactersdescription- 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:
-
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:
-
editCommandById
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:
CommandEditActionused to edit the command- Throws:
IllegalArgumentException- If the provided id is not a valid snowflake
-
editCommandById
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:
CommandEditActionused to edit the command
-
deleteCommandById
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
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
-
createGuild
Constructs a newGuildwith the specified name
Use the returnedGuildActionto 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 guildsIllegalArgumentException- If the provided name is empty,nullor not between 2-100 characters
-
createGuildFromTemplate
@Nonnull @CheckReturnValue RestAction<Void> createGuildFromTemplate(@Nonnull String code, @Nonnull String name, @Nullable Icon icon) Constructs a newGuildfrom the specified template code.This RestAction does not provide the resulting Guild! It will be in a following
GuildJoinEvent.Possible
ErrorResponsesinclude:Unknown Guild Template
The template doesn't exist.
- Parameters:
code- The template code to use to create a guildname- The name of the resulting guildicon- TheIconto use, or null to use no icon- Returns:
RestAction- Throws:
IllegalStateException- If the currently logged in account is in 10 or more guildsIllegalArgumentException- If the provided name is empty,nullor not between 2-100 characters
-
getAudioManagerCache
CacheViewof all cachedAudioManagerscreated for this JDA instance.
AudioManagers are created when first retrieved viaGuild.getAudioManager(). Using this will perform better than callingGuild.getAudioManager()iteratively as that would cause many useless audio managers to be created!AudioManagers are cross-session persistent!
- Returns:
CacheView
-
getAudioManagers
Immutable list of all createdAudioManagersfor this JDA instance!- Returns:
- Immutable list of all created AudioManager instances
-
getUserCache
SnowflakeCacheViewof all cachedUsersvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getUsers
An immutable list of allUsersthat share aGuildwith the currently logged in account.
This list will never contain duplicates and represents allUsersthat 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
Usersthat are visible to JDA.
-
getUserById
This returns theUserwhich has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this returnsnull.This will only check cached users!
- Parameters:
id- The id of the requestedUser.- Returns:
- Possibly-null
Userwith matching id. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)- See Also:
-
getUserById
This returns theUserwhich has the same id as the one provided.
If there is no visible user with an id that matches the provided one, this returnsnull.This will only check cached users!
-
getUserByTag
Searches for a user that has the matching Discord Tag.
Format has to be in the formUsername#Discriminatorwhere 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-Cacheit 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:
tag- The Discord Tag in the formatUsername#Discriminator- Returns:
- The
Userfor 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
Searches for a user that has the matching Discord Tag.
Format has to be in the formUsername#Discriminatorwhere 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-Cacheit 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 userdiscriminator- The discriminator of the user- Returns:
- The
Userfor 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
This immutable returns allUsersthat have the same username as the one provided.
If there are noUserswith 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 requestedUsers.ignoreCase- Whether to ignore case or not when comparing the provided name to eachUser.getName().- Returns:
- Possibly-empty immutable list of
Usersthat all have the same name as the provided name.
-
getMutualGuilds
Gets allGuildsthat contain all given users as their members. -
getMutualGuilds
Gets allGuildsthat contain all given users as their members. -
retrieveUserById
Attempts to retrieve aUserobject based on the provided id.If
getUserById(long)is cached, this will directly return the user in a completedRestActionwithout making a request. When bothGUILD_PRESENCESandGUILD_MEMBERSintents are disabled this will always make a request even if the user is cached. You can useaction.useCache(false)to force an update.The returned
RestActioncan encounter the following Discord errors:ErrorResponse.UNKNOWN_USER
Occurs when the provided id does not refer to aUserknown by Discord. Typically occurs when developers provide an incomplete id (cut short).
- Parameters:
id- The id of the requestedUser.- Returns:
CacheRestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)IllegalArgumentException-- If the provided id String is null.
- If the provided id String is empty.
-
retrieveUserById
Attempts to retrieve aUserobject based on the provided id.If
getUserById(long)is cached, this will directly return the user in a completedRestActionwithout making a request. When bothGUILD_PRESENCESandGUILD_MEMBERSintents are disabled this will always make a request even if the user is cached. You can useaction.useCache(false)to force an update.The returned
RestActioncan encounter the following Discord errors:ErrorResponse.UNKNOWN_USER
Occurs when the provided id does not refer to aUserknown by Discord. Typically occurs when developers provide an incomplete id (cut short).
- Parameters:
id- The id of the requestedUser.- Returns:
CacheRestAction- Type:User
On request, gets the User with id matching provided id from Discord.
-
getGuildCache
SnowflakeCacheViewof all cachedGuildsvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getGuilds
An immutable List of allGuildsthat the logged account is connected to.
If this account is not connected to anyGuilds, this will return an empty list.If the developer is sharding (
JDABuilder.useSharding(int, int), then this list will only contain theGuildsthat 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 DocumentationThis 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
Guildsthat this account is connected to.
-
getGuildById
This returns theGuildwhich has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of theGuild.- Returns:
- Possibly-null
Guildwith matching id. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getGuildById
This returns theGuildwhich has the same id as the one provided.
If there is no connected guild with an id that matches the provided one, then this returnsnull. -
getGuildsByName
An immutable list of allGuildsthat have the same name as the one provided.
If there are noGuildswith the provided name, then this returns an empty list.- Parameters:
name- The name of the requestedGuilds.ignoreCase- Whether to ignore case or not when comparing the provided name to eachGuild.getName().- Returns:
- Possibly-empty immutable list of all the
Guildsthat all have the same name as the provided name.
-
getRoleCache
UnifiedSnowflakeCacheViewof all cachedRolesvisible to this JDA session.- Returns:
- Unified
SnowflakeCacheView - See Also:
-
getRoles
AllRolesthis JDA instance can see.
This will iterate over eachGuildretrieved fromgetGuilds()and collect itsGuild.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
Retrieves theRoleassociated to the provided id.
This iterates over allGuildsand 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
Rolefor the specified ID - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getRoleById
Retrieves theRoleassociated to the provided id.
This iterates over allGuildsand 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
Rolefor the specified ID
-
getRolesByName
Retrieves allRolesvisible to this JDA instance.
This simply filters the Roles returned bygetRoles()with the provided name, either usingString.equals(Object)orString.equalsIgnoreCase(String)onRole.getName().- Parameters:
name- The name for the RolesignoreCase- Whether to useString.equalsIgnoreCase(String)- Returns:
- Immutable List of all Roles matching the parameters provided.
-
getChannelById
Description copied from interface:IGuildChannelContainerGet a channel of the specified type by id.This will automatically check for all channel types and cast to the specified class. If a channel with the specified id does not exist, or exists but is not an instance of the provided class, this returns null.
- Specified by:
getChannelByIdin interfaceIGuildChannelContainer- Type Parameters:
T- The type argument for the class- Parameters:
type-Classof a channel typeid- The snowflake id of the channel- Returns:
- The casted channel, if it exists and is assignable to the provided class, or null
-
getPrivateChannelCache
SnowflakeCacheViewof all cachedPrivateChannelsvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getPrivateChannels
An unmodifiable list of all knownPrivateChannels.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
This returns thePrivateChannelwhich has the same id as the one provided.
If there is no knownPrivateChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of thePrivateChannel.- Returns:
- Possibly-null
PrivateChannelwith matching id. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getPrivateChannelById
This returns thePrivateChannelwhich has the same id as the one provided.
If there is no knownPrivateChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of thePrivateChannel.- Returns:
- Possibly-null
PrivateChannelwith matching id.
-
openPrivateChannelById
Opens aPrivateChannelwith the provided user by id.
This will fail withUNKNOWN_USERif the user does not exist.If the channel is cached, this will directly return the channel in a completed
RestActionwithout making a request. You can useaction.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:
-
openPrivateChannelById
@Nonnull @CheckReturnValue default RestAction<PrivateChannel> openPrivateChannelById(@Nonnull String userId) Opens aPrivateChannelwith the provided user by id.
This will fail withUNKNOWN_USERif the user does not exist.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 accountIllegalArgumentException- If the provided id is not a valid snowflake- See Also:
-
getEmojiCache
UnifiedSnowflakeCacheViewof all cachedCustom Emojisvisible to this JDA session.- Returns:
- Unified
SnowflakeCacheView - See Also:
-
getEmojis
A collection of all to us known custom emoji (managed/restricted included).
This will be empty ifCacheFlag.EMOJIis disabled.Hint: To check whether you can use an
RichCustomEmojiin a specific context you can useRichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.Member)orRichCustomEmoji.canInteract(net.dv8tion.jda.api.entities.User, net.dv8tion.jda.api.entities.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
Retrieves a custom emoji matching the specifiedidif one is available in our cache.
This will be null ifCacheFlag.EMOJIis disabled.Unicode emojis are not included as
Custom Emoji!- Parameters:
id- The id of the requestedRichCustomEmoji.- Returns:
- A
Custom Emojirepresented by this id or null if none is found in our cache. - Throws:
NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getEmojiById
Retrieves a custom emoji matching the specifiedidif one is available in our cache.
This will be null ifCacheFlag.EMOJIis disabled.Unicode emojis are not included as
Custom Emoji!- Parameters:
id- The id of the requestedRichCustomEmoji.- Returns:
- A
Custom Emojirepresented by this id or null if none is found in our cache.
-
getEmojisByName
An unmodifiable list of allCustom Emojisthat have the same name as the one provided.
If there are noCustom Emojiswith the provided name, then this returns an empty list.
This will be empty ifCacheFlag.EMOJIis disabled.Unicode emojis are not included as
Custom Emoji!- Parameters:
name- The name of the requestedCustom Emojis. Without colons.ignoreCase- Whether to ignore case or not when comparing the provided name to eachEmoji.getName().- Returns:
- Possibly-empty list of all the
Custom Emojisthat all have the same name as the provided name.
-
retrieveSticker
@Nonnull @CheckReturnValue RestAction<StickerUnion> retrieveSticker(@Nonnull StickerSnowflake sticker) Attempts to retrieve aStickerobject based on the provided snowflake reference.
This works for bothStandardStickerandGuildSticker, and you can resolve them using the providedStickerUnion.If the sticker is not one of the supported
Types, the request fails withIllegalArgumentException.The returned
RestActioncan 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 requestedSticker.
Can beRichSticker,StickerItem, orSticker.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
Retrieves a list of all the publicStickerPacksused for nitro.- Returns:
RestAction- Type: List ofStickerPack
-
getEventManager
The EventManager used by this JDA instance.- Returns:
- The
IEventManager
-
getSelfUser
Returns the currently logged in account represented bySelfUser.
Account settings cannot be modified using this object. If you wish to modify account settings please use the AccountManager which is accessible bySelfUser.getManager().- Returns:
- The currently logged in account.
-
getPresence
- Returns:
- The never-null
Presencefor this session.
-
getShardInfo
The shard information used when creating this instance of JDA.
Represents the information provided toJDABuilder.useSharding(int, int).- Returns:
- The shard information for this shard
-
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 usingJDABuilder.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 aSocketTimeoutExceptionoccurs.- 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 singleMessageBulkDeleteEventor split the deleted messages up and fire multipleMessageDeleteEvents, 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 enqueuedRestActionsare 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
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 queuedRestActions.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:
-
getAccountType
TheAccountTypeof the currently logged in account.
Used when determining functions that are restricted based on the type of account.- Returns:
- The current AccountType.
-
retrieveApplicationInfo
Retrieves theApplicationInfofor 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
TheApplicationInfoof the bot's application.- Throws:
AccountTypeException- If the currently logged in account is not fromAccountType.BOT
-
setRequiredScopes
Configures the required scopes applied to thegetInviteUrl(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 withgetInviteUrl(Permission...)and the likes- Returns:
- The current JDA instance
- Throws:
IllegalArgumentException- If null is provided
-
setRequiredScopes
Configures the required scopes applied to thegetInviteUrl(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 withgetInviteUrl(Permission...)and the likes- Returns:
- The current JDA instance
- Throws:
IllegalArgumentException- If null is provided
-
getInviteUrl
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=8Hint: 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 thepermissionsparameter is omitted- Returns:
- A valid OAuth2 invite url for the currently logged in Bot-Account
- Throws:
AccountTypeException- If the currently logged in account is not fromAccountType.BOT
-
getInviteUrl
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=8Hint: 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 thepermissionsparameter is omitted- Returns:
- A valid OAuth2 invite url for the currently logged in Bot-Account
- Throws:
AccountTypeException- If the currently logged in account is not fromAccountType.BOT
-
getShardManager
Returns theShardManagerthat manages this JDA instances or null if this instance is not managed by anyShardManager.- Returns:
- The corresponding ShardManager or
nullif there is no such manager
-
retrieveWebhookById
Retrieves aWebhookby its id.Possible
ErrorResponsescaused by the returnedRestActioninclude the following:MISSING_PERMISSIONS
We do not have the required permissionsUNKNOWN_WEBHOOK
A webhook with this id does not exist
- Parameters:
webhookId- The webhook id- Returns:
RestAction- Type:Webhook
The webhook object.- Throws:
IllegalArgumentException- If thewebhookIdis null or empty- See Also:
-
retrieveWebhookById
Retrieves aWebhookby its id.Possible
ErrorResponsescaused by the returnedRestActioninclude the following:MISSING_PERMISSIONS
We do not have the required permissionsUNKNOWN_WEBHOOK
A webhook with this id does not exist
- Parameters:
webhookId- The webhook id- Returns:
RestAction- Type:Webhook
The webhook object.- See Also:
-
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
-