Interface JDA
-
public interface JDAThe core of JDA. Acts as a registry system of JDA. All parts of the the API can be accessed starting from this class.- See Also:
JDABuilder
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static classJDA.ShardInfoRepresents the information used to create this shard.static classJDA.StatusRepresents the connection status of JDA and its Main WebSocket.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description voidaddEventListener(java.lang.Object... listeners)Adds all provided listeners to the event-listeners that will be used to handle events.default JDAawaitReady()This 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.JDAawaitStatus(JDA.Status status, JDA.Status... failOn)This method will block until JDA has reached the specified connection status.intcancelRequests()Cancels all currently scheduledRestActionrequests.GuildActioncreateGuild(java.lang.String name)Constructs a newGuildwith the specified name
Use the returnedGuildActionto provide further details and settings for the resulting Guild!RestAction<java.lang.Void>createGuildFromTemplate(java.lang.String code, java.lang.String name, Icon icon)Constructs a newGuildfrom the specified template code.default RestAction<java.lang.Void>deleteCommandById(long commandId)Delete the global command for this id.RestAction<java.lang.Void>deleteCommandById(java.lang.String commandId)Delete the global command for this id.default CommandEditActioneditCommandById(long id)Edit an existing global command by id.CommandEditActioneditCommandById(java.lang.String id)Edit an existing global command by id.AccountTypegetAccountType()TheAccountTypeof the currently logged in account.CacheView<AudioManager>getAudioManagerCache()CacheViewof all cachedAudioManagerscreated for this JDA instance.default java.util.List<AudioManager>getAudioManagers()Immutable list of all createdAudioManagersfor this JDA instance!java.util.EnumSet<CacheFlag>getCacheFlags()Thecache flagsthat have been enabled for this JDA session.java.util.concurrent.ExecutorServicegetCallbackPool()ExecutorServiceused to handleRestActioncallbacks and completions.default java.util.List<Category>getCategories()Gets allCategoriesvisible to the currently logged in account.default java.util.List<Category>getCategoriesByName(java.lang.String name, boolean ignoreCase)Gets a list of allCategoriesthat have the same name as the one provided.default CategorygetCategoryById(long id)Gets theCategorythat matches the provided id.default CategorygetCategoryById(java.lang.String id)Gets theCategorythat matches the provided id.SnowflakeCacheView<Category>getCategoryCache()SnowflakeCacheViewof all cachedCategoriesvisible to this JDA session.DirectAudioControllergetDirectAudioController()Direct access to audio (dis-)connect requests.default EmotegetEmoteById(long id)Retrieves an emote matching the specifiedidif one is available in our cache.default EmotegetEmoteById(java.lang.String id)Retrieves an emote matching the specifiedidif one is available in our cache.SnowflakeCacheView<Emote>getEmoteCache()UnifiedSnowflakeCacheViewof all cachedEmotesvisible to this JDA session.default java.util.List<Emote>getEmotes()A collection of all to us known emotes (managed/restricted included).default java.util.List<Emote>getEmotesByName(java.lang.String name, boolean ignoreCase)An unmodifiable list of allEmotesthat have the same name as the one provided.IEventManagergetEventManager()The EventManager used by this JDA instance.java.util.EnumSet<GatewayIntent>getGatewayIntents()TheGatewayIntentsfor this JDA session.longgetGatewayPing()The time in milliseconds that discord took to respond to our last heartbeat
This roughly represents the WebSocket ping of this sessionjava.util.concurrent.ScheduledExecutorServicegetGatewayPool()ScheduledExecutorServiceused to send WebSocket messages to discord.default GuildgetGuildById(long id)This returns theGuildwhich has the same id as the one provided.default GuildgetGuildById(java.lang.String id)This returns theGuildwhich has the same id as the one provided.SnowflakeCacheView<Guild>getGuildCache()SnowflakeCacheViewof all cachedGuildsvisible to this JDA session.default GuildChannelgetGuildChannelById(long id)GetGuildChannelfor the provided ID.default GuildChannelgetGuildChannelById(java.lang.String id)GetGuildChannelfor the provided ID.default GuildChannelgetGuildChannelById(ChannelType type, long id)GetGuildChannelfor the provided ID.default GuildChannelgetGuildChannelById(ChannelType type, java.lang.String id)GetGuildChannelfor the provided ID.default java.util.List<Guild>getGuilds()An immutable List of allGuildsthat the logged account is connected to.default java.util.List<Guild>getGuildsByName(java.lang.String name, boolean ignoreCase)An immutable list of allGuildsthat have the same name as the one provided.OkHttpClientgetHttpClient()TheOkHttpClientused for handling http requests fromRestActions.java.lang.StringgetInviteUrl(java.util.Collection<Permission> permissions)Creates an authorization invite url for the currently logged in Bot-Account.java.lang.StringgetInviteUrl(Permission... permissions)Creates an authorization invite url for the currently logged in Bot-Account.intgetMaxReconnectDelay()This value is the maximum amount of time, in seconds, that JDA will wait between reconnect attempts.java.util.List<Guild>getMutualGuilds(java.util.Collection<User> users)Gets allGuildsthat contain all given users as their members.java.util.List<Guild>getMutualGuilds(User... users)Gets allGuildsthat contain all given users as their members.PresencegetPresence()ThePresencecontroller for the current session.default PrivateChannelgetPrivateChannelById(long id)This returns thePrivateChannelwhich has the same id as the one provided.default PrivateChannelgetPrivateChannelById(java.lang.String id)This returns thePrivateChannelwhich has the same id as the one provided.SnowflakeCacheView<PrivateChannel>getPrivateChannelCache()SnowflakeCacheViewof all cachedPrivateChannelsvisible to this JDA session.default java.util.List<PrivateChannel>getPrivateChannels()An unmodifiable list of all knownPrivateChannels.java.util.concurrent.ScheduledExecutorServicegetRateLimitPool()ScheduledExecutorServiceused to handle rate-limits forRestActionexecutions.java.util.List<java.lang.Object>getRegisteredListeners()Immutable List of Objects that have been registered as EventListeners.longgetResponseTotal()This value is the total amount of JSON responses that discord has sent.default RestAction<java.lang.Long>getRestPing()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(java.lang.String id)Retrieves theRoleassociated to the provided id.SnowflakeCacheView<Role>getRoleCache()UnifiedSnowflakeCacheViewof all cachedRolesvisible to this JDA session.default java.util.List<Role>getRoles()AllRolesthis JDA instance can see.default java.util.List<Role>getRolesByName(java.lang.String name, boolean ignoreCase)Retrieves allRolesvisible to this JDA instance.SelfUsergetSelfUser()Returns the currently logged in account represented bySelfUser.JDA.ShardInfogetShardInfo()The shard information used when creating this instance of JDA.ShardManagergetShardManager()Returns theShardManagerthat manages this JDA instances or null if this instance is not managed by anyShardManager.default StageChannelgetStageChannelById(long id)This returns theStageChannelwhich has the same id as the one provided.default StageChannelgetStageChannelById(java.lang.String id)This returns theStageChannelwhich has the same id as the one provided.default java.util.List<StageChannel>getStageChannels()An unmodifiable list of allStageChannelsof all connectedGuilds.default java.util.List<StageChannel>getStageChannelsByName(java.lang.String name, boolean ignoreCase)An unmodifiable list of allStageChannelsthat have the same name as the one provided.JDA.StatusgetStatus()Gets the currentStatusof the JDA instance.default StoreChannelgetStoreChannelById(long id)Gets aStoreChannelthat has the same id as the one provided.default StoreChannelgetStoreChannelById(java.lang.String id)Gets aStoreChannelthat has the same id as the one provided.SnowflakeCacheView<StoreChannel>getStoreChannelCache()SnowflakeCacheViewof all cachedStoreChannelsvisible to this JDA session.default java.util.List<StoreChannel>getStoreChannels()Gets allStoreChannelsof all connectedGuilds.default java.util.List<StoreChannel>getStoreChannelsByName(java.lang.String name, boolean ignoreCase)An unmodifiable list of allStoreChannelsthat have the same name as the one provided.default TextChannelgetTextChannelById(long id)This returns theTextChannelwhich has the same id as the one provided.default TextChannelgetTextChannelById(java.lang.String id)This returns theTextChannelwhich has the same id as the one provided.SnowflakeCacheView<TextChannel>getTextChannelCache()SnowflakeCacheViewof all cachedTextChannelsvisible to this JDA session.default java.util.List<TextChannel>getTextChannels()An unmodifiable List of allTextChannelsof all connectedGuilds.default java.util.List<TextChannel>getTextChannelsByName(java.lang.String name, boolean ignoreCase)An unmodifiable list of allTextChannelsthat have the same name as the one provided.java.lang.StringgetToken()The login token that is currently being used for Discord authentication.java.util.Set<java.lang.String>getUnavailableGuilds()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(java.lang.String id)This returns theUserwhich has the same id as the one provided.default UsergetUserByTag(java.lang.String tag)Searches for a user that has the matching Discord Tag.default UsergetUserByTag(java.lang.String username, java.lang.String discriminator)Searches for a user that has the matching Discord Tag.SnowflakeCacheView<User>getUserCache()SnowflakeCacheViewof all cachedUsersvisible to this JDA session.default java.util.List<User>getUsers()default java.util.List<User>getUsersByName(java.lang.String name, boolean ignoreCase)This immutable returns allUsersthat have the same username as the one provided.default VoiceChannelgetVoiceChannelById(long id)This returns theVoiceChannelwhich has the same id as the one provided.default VoiceChannelgetVoiceChannelById(java.lang.String id)This returns theVoiceChannelwhich has the same id as the one provided.SnowflakeCacheView<VoiceChannel>getVoiceChannelCache()SnowflakeCacheViewof all cachedVoiceChannelsvisible to this JDA session.default java.util.List<VoiceChannel>getVoiceChannels()An unmodifiable list of allVoiceChannelsof all connectedGuilds.default java.util.List<VoiceChannel>getVoiceChannelsByName(java.lang.String name, boolean ignoreCase)An unmodifiable list of allVoiceChannelsthat have the same name as the one provided.default AuditableRestAction<java.lang.Integer>installAuxiliaryPort()Installs an auxiliary port for audio transfer.booleanisAutoReconnect()USed to determine whether or not autoReconnect is enabled for JDA.booleanisBulkDeleteSplittingEnabled()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.booleanisUnavailable(long guildId)Whether the guild is unavailable.RestAction<PrivateChannel>openPrivateChannelById(long userId)Opens aPrivateChannelwith the provided user by id.default RestAction<PrivateChannel>openPrivateChannelById(java.lang.String userId)Opens aPrivateChannelwith the provided user by id.voidremoveEventListener(java.lang.Object... listeners)Removes all provided listeners from the event-listeners and no longer uses them to handle events.RestAction<ApplicationInfo>retrieveApplicationInfo()Retrieves theApplicationInfofor the application that owns the logged in Bot-Account.default RestAction<Command>retrieveCommandById(long id)Retrieves the existingCommandinstance by id.RestAction<Command>retrieveCommandById(java.lang.String id)Retrieves the existingCommandinstance by id.RestAction<java.util.List<Command>>retrieveCommands()Retrieves the list of global commands.default RestAction<User>retrieveUserById(long id)Attempts to retrieve aUserobject based on the provided id.RestAction<User>retrieveUserById(long id, boolean update)Attempts to retrieve aUserobject based on the provided id.default RestAction<User>retrieveUserById(java.lang.String id)Attempts to retrieve aUserobject based on the provided id.default RestAction<User>retrieveUserById(java.lang.String id, boolean update)Attempts to retrieve aUserobject based on the provided id.default RestAction<Webhook>retrieveWebhookById(long webhookId)Retrieves aWebhookby its id.RestAction<Webhook>retrieveWebhookById(java.lang.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(java.lang.String... scopes)Configures the required scopes applied to thegetInviteUrl(Permission...)and similar methods.JDAsetRequiredScopes(java.util.Collection<java.lang.String> scopes)Configures the required scopes applied to thegetInviteUrl(Permission...)and similar methods.voidshutdown()Shuts down this JDA instance, closing all its connections.voidshutdownNow()Shuts down this JDA instance instantly, closing all its connections.booleanunloadUser(long userId)Attempts to remove the user with the provided id from the cache.CommandListUpdateActionupdateCommands()Configures the complete list of global commands.default CommandCreateActionupsertCommand(java.lang.String name, java.lang.String description)Creates or updates a global command.CommandCreateActionupsertCommand(CommandData command)Creates or updates a global command.
-
-
-
Method Detail
-
getStatus
@Nonnull JDA.Status getStatus()
Gets the currentStatusof the JDA instance.- Returns:
- Current JDA status.
-
getGatewayIntents
@Nonnull java.util.EnumSet<GatewayIntent> getGatewayIntents()
TheGatewayIntentsfor this JDA session.- Returns:
EnumSetof active gateway intents
-
getCacheFlags
@Nonnull java.util.EnumSet<CacheFlag> 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:
Getting RestAction ping
-
getRestPing
@Nonnull default RestAction<java.lang.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 java.lang.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.- Returns:
- The current JDA instance, for chaining convenience
- Throws:
java.lang.InterruptedException- If this thread is interrupted while waitingjava.lang.IllegalArgumentException- If the provided status is null or not an init status (JDA.Status.isInit())java.lang.IllegalStateException- If JDA is shutdown during this wait period
-
awaitStatus
@Nonnull JDA awaitStatus(@Nonnull JDA.Status status, @Nonnull JDA.Status... failOn) throws java.lang.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:
java.lang.InterruptedException- If this thread is interrupted while waitingjava.lang.IllegalArgumentException- If the provided status is null or not an init status (JDA.Status.isInit())java.lang.IllegalStateException- If JDA is shutdown during this wait period
-
awaitReady
@Nonnull default JDA awaitReady() throws java.lang.InterruptedException
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:
java.lang.InterruptedException- If this thread is interrupted while waitingjava.lang.IllegalStateException- 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:
RestAction.setCheck(BooleanSupplier)
-
getRateLimitPool
@Nonnull java.util.concurrent.ScheduledExecutorService 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
@Nonnull java.util.concurrent.ScheduledExecutorService 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
@Nonnull java.util.concurrent.ExecutorService 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
@Nonnull OkHttpClient getHttpClient()
TheOkHttpClientused for handling http requests fromRestActions.- 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'sAudioManager.- Returns:
- The
DirectAudioControllerfor this JDA instance - Throws:
java.lang.IllegalStateException- IfGatewayIntent.GUILD_VOICE_STATESis disabled- Since:
- 4.0.0
-
setEventManager
void setEventManager(@Nullable IEventManager manager)Changes the internal EventManager.The default EventManager is
InterfacedEventListener.
There is also anAnnotatedEventManageravailable.- Parameters:
manager- The new EventManager to use
-
addEventListener
void addEventListener(@Nonnull java.lang.Object... listeners)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:
java.lang.IllegalArgumentException- If either listeners or one of it's objects isnull.
-
removeEventListener
void removeEventListener(@Nonnull java.lang.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:
java.lang.IllegalArgumentException- If either listeners or one of it's objects isnull.
-
getRegisteredListeners
@Nonnull java.util.List<java.lang.Object> getRegisteredListeners()
Immutable List of Objects that have been registered as EventListeners.- Returns:
- List of currently registered Objects acting as EventListeners.
-
retrieveCommands
@Nonnull @CheckReturnValue RestAction<java.util.List<Command>> retrieveCommands()
Retrieves the list of global commands.
This list does not include guild commands! UseGuild.retrieveCommands()for guild commands.- Returns:
RestAction- Type:ListofCommand
-
retrieveCommandById
@Nonnull @CheckReturnValue RestAction<Command> retrieveCommandById(@Nonnull java.lang.String id)
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:
java.lang.IllegalArgumentException- If the provided id is not a valid snowflake
-
retrieveCommandById
@Nonnull @CheckReturnValue default RestAction<Command> retrieveCommandById(long id)
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
@Nonnull @CheckReturnValue CommandCreateAction upsertCommand(@Nonnull CommandData command)
Creates or updates a global command.
If a command with the same name exists, it will be replaced.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.Global commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
command- TheCommandDatafor the command- Returns:
CommandCreateAction- Throws:
java.lang.IllegalArgumentException- If null is provided- See Also:
Guild.upsertCommand(CommandData)
-
upsertCommand
@Nonnull @CheckReturnValue default CommandCreateAction upsertCommand(@Nonnull java.lang.String name, @Nonnull java.lang.String description)
Creates or updates a global command.
If a command with the same name exists, it will be replaced.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.Global commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
name- The lowercase alphanumeric (with dash) name, 1-32 charactersdescription- The description for the command, 1-100 characters- Returns:
CommandCreateAction- Throws:
java.lang.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!You need the OAuth2 scope
"applications.commands"in order to add commands to a guild.Global commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
Examples
// Set list to 2 commands jda.updateCommands() .addCommands(new CommandData("ping", "Gives the current ping")) .addCommands(new CommandData("ban", "Ban the target user") .addOption(OptionType.USER, "user", "The user to ban", true)) .queue(); // Delete all commands jda.updateCommands().queue();- Returns:
CommandListUpdateAction
-
editCommandById
@Nonnull @CheckReturnValue CommandEditAction editCommandById(@Nonnull java.lang.String id)
Edit an existing global command by id.If there is no command with the provided ID, this RestAction fails with
ErrorResponse.UNKNOWN_COMMANDGlobal commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
id- The id of the command to edit- Returns:
CommandEditActionused to edit the command- Throws:
java.lang.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_COMMANDGlobal commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
id- The id of the command to edit- Returns:
CommandEditActionused to edit the command
-
deleteCommandById
@Nonnull @CheckReturnValue RestAction<java.lang.Void> deleteCommandById(@Nonnull java.lang.String commandId)
Delete the global command for this id.If there is no command with the provided ID, this RestAction fails with
ErrorResponse.UNKNOWN_COMMANDGlobal commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
commandId- The id of the command that should be deleted- Returns:
RestAction- Throws:
java.lang.IllegalArgumentException- If the provided id is not a valid snowflake
-
deleteCommandById
@Nonnull @CheckReturnValue default RestAction<java.lang.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_COMMANDGlobal commands can take up to 1 hour to propagate to the clients. For testing, it is recommended to use a test guild with guild commands.
- Parameters:
commandId- The id of the command that should be deleted- Returns:
RestAction
-
createGuild
@Nonnull @CheckReturnValue GuildAction createGuild(@Nonnull java.lang.String name)
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:
java.lang.IllegalStateException- If the currently logged in account is in 10 or more guildsjava.lang.IllegalArgumentException- If the provided name is empty,nullor not between 2-100 characters
-
createGuildFromTemplate
@Nonnull @CheckReturnValue RestAction<java.lang.Void> createGuildFromTemplate(@Nonnull java.lang.String code, @Nonnull java.lang.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:
java.lang.IllegalStateException- If the currently logged in account is in 10 or more guildsjava.lang.IllegalArgumentException- If the provided name is empty,nullor not between 2-100 characters
-
getAudioManagerCache
@Nonnull CacheView<AudioManager> 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
@Nonnull default java.util.List<AudioManager> getAudioManagers()
Immutable list of all createdAudioManagersfor this JDA instance!- Returns:
- Immutable list of all created AudioManager instances
-
getUserCache
@Nonnull SnowflakeCacheView<User> getUserCache()
SnowflakeCacheViewof all cachedUsersvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getUsers
@Nonnull default java.util.List<User> 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
@Nullable default User getUserById(@Nonnull java.lang.String id)
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:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)- See Also:
retrieveUserById(String)
-
getUserById
@Nullable default User getUserById(long id)
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. - See Also:
retrieveUserById(long)
-
getUserByTag
@Nullable default User getUserByTag(@Nonnull java.lang.String tag)
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:
java.lang.IllegalArgumentException- If the provided tag is null or not in the described format
-
getUserByTag
@Nullable default User getUserByTag(@Nonnull java.lang.String username, @Nonnull java.lang.String discriminator)
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:
java.lang.IllegalArgumentException- If the provided arguments are null or not in the described format
-
getUsersByName
@Nonnull default java.util.List<User> getUsersByName(@Nonnull java.lang.String name, boolean ignoreCase)
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
@Nonnull java.util.List<Guild> getMutualGuilds(@Nonnull User... users)
Gets allGuildsthat contain all given users as their members.- Parameters:
users- The users which all the returnedGuildsmust contain.- Returns:
- Immutable list of all
Guildinstances which have allUsersin them. - See Also:
Guild.isMember(net.dv8tion.jda.api.entities.User)
-
getMutualGuilds
@Nonnull java.util.List<Guild> getMutualGuilds(@Nonnull java.util.Collection<User> users)
Gets allGuildsthat contain all given users as their members.
-
retrieveUserById
@Nonnull @CheckReturnValue default RestAction<User> retrieveUserById(@Nonnull java.lang.String id)
Attempts to retrieve aUserobject based on the provided id.
This first callsgetUserById(long), and if that returnsnullor the cache is inconsistent due to disabled intents then a request is made to the Discord servers.When the both
GUILD_PRESENCESandGUILD_MEMBERSintents are disabled this will always make a request even if the user is cached. You can useretrieveUserById(String, boolean)to disable this behavior.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:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
AccountTypeException- This endpoint isAccountType.BOTonly.java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)java.lang.IllegalArgumentException-- If the provided id String is null.
- If the provided id String is empty.
-
retrieveUserById
@Nonnull @CheckReturnValue default RestAction<User> retrieveUserById(long id)
Attempts to retrieve aUserobject based on the provided id.
This first callsgetUserById(long), and if that returnsnullor the cache is inconsistent due to disabled intents then a request is made to the Discord servers.When the both
GUILD_PRESENCESandGUILD_MEMBERSintents are disabled this will always make a request even if the user is cached. You can useretrieveUserById(String, boolean)to disable this behavior.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:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
AccountTypeException- This endpoint isAccountType.BOTonly.
-
retrieveUserById
@Nonnull @CheckReturnValue default RestAction<User> retrieveUserById(@Nonnull java.lang.String id, boolean update)
Attempts to retrieve aUserobject based on the provided id.
If bothGUILD_MEMBERSandGUILD_PRESENCESintents are disabled this method will update the cached user unless theupdateparameter isfalse.
If either of those intents is enabled, this will immediately provide the cached user if possible.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.update- Whether JDA should perform a request even if the member is already cached to update properties such as the name- Returns:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
AccountTypeException- This endpoint isAccountType.BOTonly.java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)java.lang.IllegalArgumentException-- If the provided id String is null.
- If the provided id String is empty.
-
retrieveUserById
@Nonnull @CheckReturnValue RestAction<User> retrieveUserById(long id, boolean update)
Attempts to retrieve aUserobject based on the provided id.
If bothGUILD_MEMBERSandGUILD_PRESENCESintents are disabled this method will update the cached user unless theupdateparameter isfalse.
If either of those intents is enabled, this will immediately provide the cached user if possible.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.update- Whether JDA should perform a request even if the member is already cached to update properties such as the name- Returns:
RestAction- Type:User
On request, gets the User with id matching provided id from Discord.- Throws:
AccountTypeException- This endpoint isAccountType.BOTonly.
-
getGuildCache
@Nonnull SnowflakeCacheView<Guild> getGuildCache()
SnowflakeCacheViewof all cachedGuildsvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getGuilds
@Nonnull default java.util.List<Guild> 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
@Nullable default Guild getGuildById(@Nonnull java.lang.String id)
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.
-
getGuildById
@Nullable default Guild getGuildById(long id)
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
@Nonnull default java.util.List<Guild> getGuildsByName(@Nonnull java.lang.String name, boolean ignoreCase)
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.
-
getUnavailableGuilds
@Nonnull java.util.Set<java.lang.String> getUnavailableGuilds()
Set ofGuildIDs for guilds that were marked unavailable by the gateway.
When a guild becomes unavailable aGuildUnavailableEventis emitted and aGuildAvailableEventis emitted when it becomes available again. During the time a guild is unavailable it its not reachable through cache such asgetGuildById(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 ingetUnavailableGuilds().- Parameters:
guildId- The guild id- Returns:
- True, if this guild is unavailable
-
getRoleCache
@Nonnull SnowflakeCacheView<Role> getRoleCache()
UnifiedSnowflakeCacheViewof all cachedRolesvisible to this JDA session.- Returns:
- Unified
SnowflakeCacheView - See Also:
CacheView.allSnowflakes(...)
-
getRoles
@Nonnull default java.util.List<Role> 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
@Nullable default Role getRoleById(@Nonnull java.lang.String id)
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:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getRoleById
@Nullable default Role getRoleById(long id)
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
@Nonnull default java.util.List<Role> getRolesByName(@Nonnull java.lang.String name, boolean ignoreCase)
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.
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(@Nonnull java.lang.String id)
GetGuildChannelfor the provided ID.
This checks if any of the channel types in this guild have the provided ID and returns the first match.
To get more specific channel types you can use one of the following:- Parameters:
id- The ID of the channel- Returns:
- The GuildChannel or null
- Throws:
java.lang.IllegalArgumentException- If the provided ID is nulljava.lang.NumberFormatException- If the provided ID is not a snowflake
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(long id)
GetGuildChannelfor the provided ID.
This checks if any of the channel types in this guild have the provided ID and returns the first match.
To get more specific channel types you can use one of the following:- Parameters:
id- The ID of the channel- Returns:
- The GuildChannel or null
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(@Nonnull ChannelType type, @Nonnull java.lang.String id)
GetGuildChannelfor the provided ID.
This is meant for systems that use a dynamicChannelTypeand can profit from a simple function to get the channel instance. To get more specific channel types you can use one of the following:- Parameters:
type- TheChannelTypeid- The ID of the channel- Returns:
- The GuildChannel or null
- Throws:
java.lang.IllegalArgumentException- If the provided ID is nulljava.lang.NumberFormatException- If the provided ID is not a snowflakejava.lang.IllegalArgumentException- If the providedChannelTypeis null
-
getGuildChannelById
@Nullable default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
GetGuildChannelfor the provided ID.
This is meant for systems that use a dynamicChannelTypeand can profit from a simple function to get the channel instance. To get more specific channel types you can use one of the following:- Parameters:
type- TheChannelTypeid- The ID of the channel- Returns:
- The GuildChannel or null
- Throws:
java.lang.IllegalArgumentException- If the providedChannelTypeis null
-
getStageChannelsByName
@Nonnull default java.util.List<StageChannel> getStageChannelsByName(@Nonnull java.lang.String name, boolean ignoreCase)
An unmodifiable list of allStageChannelsthat have the same name as the one provided.
If there are noStageChannelswith the provided name, then this returns an empty list.- Parameters:
name- The name of the requestedStageChannels.ignoreCase- Whether to ignore case or not when comparing the provided name to eachAbstractChannel.getName().- Returns:
- Possibly-empty list of all the
StageChannelsthat all have the same name as the provided name.
-
getStageChannelById
@Nullable default StageChannel getStageChannelById(@Nonnull java.lang.String id)
This returns theStageChannelwhich has the same id as the one provided.
If there is no knownStageChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of theStageChannel.- Returns:
- Possibly-null
StageChannelwith matching id. - Throws:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getStageChannelById
@Nullable default StageChannel getStageChannelById(long id)
This returns theStageChannelwhich has the same id as the one provided.
If there is no knownStageChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of theStageChannel.- Returns:
- Possibly-null
StageChannelwith matching id.
-
getStageChannels
@Nonnull default java.util.List<StageChannel> getStageChannels()
An unmodifiable list of allStageChannelsof all connectedGuilds.This copies the backing store into a list. This means every call creates a new list with O(n) complexity.
- Returns:
- Possible-empty list of all known
StageChannels.
-
getCategoryCache
@Nonnull SnowflakeCacheView<Category> getCategoryCache()
SnowflakeCacheViewof all cachedCategoriesvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getCategoryById
@Nullable default Category getCategoryById(@Nonnull java.lang.String id)
- Parameters:
id- The snowflake ID of the wanted Category- Returns:
- Possibly-null
Categoryfor the provided ID. - Throws:
java.lang.IllegalArgumentException- If the provided ID is not a validlong
-
getCategoryById
@Nullable default Category getCategoryById(long id)
- Parameters:
id- The snowflake ID of the wanted Category- Returns:
- Possibly-null
Categoryfor the provided ID.
-
getCategories
@Nonnull default java.util.List<Category> getCategories()
Gets allCategoriesvisible to the currently logged in account.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
getCategoryCache()and use its more efficient versions of handling these values.- Returns:
- An immutable list of all visible
Categories.
-
getCategoriesByName
@Nonnull default java.util.List<Category> getCategoriesByName(@Nonnull java.lang.String name, boolean ignoreCase)
Gets a list of allCategoriesthat have the same name as the one provided.
If there are no matching categories this will return an empty list.- Parameters:
name- The name to checkignoreCase- Whether to ignore case on name checking- Returns:
- Immutable list of all categories matching the provided name
- Throws:
java.lang.IllegalArgumentException- If the provided name isnull
-
getStoreChannelCache
@Nonnull SnowflakeCacheView<StoreChannel> getStoreChannelCache()
SnowflakeCacheViewof all cachedStoreChannelsvisible to this JDA session.
TextChannels are sorted according to their position.- Returns:
SnowflakeCacheView
-
getStoreChannelById
@Nullable default StoreChannel getStoreChannelById(@Nonnull java.lang.String id)
Gets aStoreChannelthat has the same id as the one provided.
If there is noStoreChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of theStoreChannel.- Returns:
- Possibly-null
StoreChannelwith matching id. - Throws:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getStoreChannelById
@Nullable default StoreChannel getStoreChannelById(long id)
Gets aStoreChannelthat has the same id as the one provided.
If there is noStoreChannelwith an id that matches the provided one, then this returnsnull.- Parameters:
id- The id of theStoreChannel.- Returns:
- Possibly-null
StoreChannelwith matching id.
-
getStoreChannels
@Nonnull default java.util.List<StoreChannel> getStoreChannels()
Gets allStoreChannelsof all connectedGuilds.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
getStoreChannelCache()and use its more efficient versions of handling these values.- Returns:
- Possibly-empty immutable List of all known
StoreChannel.
-
getStoreChannelsByName
@Nonnull default java.util.List<StoreChannel> getStoreChannelsByName(@Nonnull java.lang.String name, boolean ignoreCase)
An unmodifiable list of allStoreChannelsthat have the same name as the one provided.
If there are noStoreChannelswith the provided name, then this returns an empty list.- Parameters:
name- The name used to filter the returnedStoreChannels.ignoreCase- Determines if the comparison ignores case when comparing. True - case insensitive.- Returns:
- Possibly-empty immutable list of all StoreChannels with names that match the provided name.
-
getTextChannelCache
@Nonnull SnowflakeCacheView<TextChannel> getTextChannelCache()
SnowflakeCacheViewof all cachedTextChannelsvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getTextChannels
@Nonnull default java.util.List<TextChannel> getTextChannels()
An unmodifiable List of allTextChannelsof all connectedGuilds.Note: just because a
TextChannelis present in this list does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is possible that you will see fewer channels than this returns. This is because the discord client hides anyTextChannelthat you don't have thePermission.MESSAGE_READpermission in.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
getTextChannelCache()and use its more efficient versions of handling these values.- Returns:
- Possibly-empty list of all known
TextChannels.
-
getTextChannelById
@Nullable default TextChannel getTextChannelById(@Nonnull java.lang.String id)
This returns theTextChannelwhich has the same id as the one provided.
If there is no knownTextChannelwith an id that matches the provided one, then this returnsnull.Note: just because a
TextChannelis present does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is you will not see the channel that this returns. This is because the discord client hides anyTextChannelthat you don't have thePermission.MESSAGE_READpermission in.- Parameters:
id- The id of theTextChannel.- Returns:
- Possibly-null
TextChannelwith matching id. - Throws:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getTextChannelById
@Nullable default TextChannel getTextChannelById(long id)
This returns theTextChannelwhich has the same id as the one provided.
If there is no knownTextChannelwith an id that matches the provided one, then this returnsnull.Note: just because a
TextChannelis present does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is you will not see the channel that this returns. This is because the discord client hides anyTextChannelthat you don't have thePermission.MESSAGE_READpermission in.- Parameters:
id- The id of theTextChannel.- Returns:
- Possibly-null
TextChannelwith matching id.
-
getTextChannelsByName
@Nonnull default java.util.List<TextChannel> getTextChannelsByName(@Nonnull java.lang.String name, boolean ignoreCase)
An unmodifiable list of allTextChannelsthat have the same name as the one provided.
If there are noTextChannelswith the provided name, then this returns an empty list.Note: just because a
TextChannelis present in this list does not mean that you will be able to send messages to it. Furthermore, if you log into this account on the discord client, it is possible that you will see fewer channels than this returns. This is because the discord client hides anyTextChannelthat you don't have thePermission.MESSAGE_READpermission in.- Parameters:
name- The name of the requestedTextChannels.ignoreCase- Whether to ignore case or not when comparing the provided name to eachAbstractChannel.getName().- Returns:
- Possibly-empty list of all the
TextChannelsthat all have the same name as the provided name.
-
getVoiceChannelCache
@Nonnull SnowflakeCacheView<VoiceChannel> getVoiceChannelCache()
SnowflakeCacheViewof all cachedVoiceChannelsvisible to this JDA session.This may also contain
StageChannels!- Returns:
SnowflakeCacheView
-
getVoiceChannels
@Nonnull default java.util.List<VoiceChannel> getVoiceChannels()
An unmodifiable list of allVoiceChannelsof all connectedGuilds.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
getVoiceChannelCache()and use its more efficient versions of handling these values.This may also contain
StageChannels!- Returns:
- Possible-empty list of all known
VoiceChannels.
-
getVoiceChannelById
@Nullable default VoiceChannel getVoiceChannelById(@Nonnull java.lang.String id)
This returns theVoiceChannelwhich has the same id as the one provided.
If there is no knownVoiceChannelwith an id that matches the provided one, then this returnsnull.This may also contain
StageChannels!- Parameters:
id- The id of theVoiceChannel.- Returns:
- Possibly-null
VoiceChannelwith matching id. - Throws:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getVoiceChannelById
@Nullable default VoiceChannel getVoiceChannelById(long id)
This returns theVoiceChannelwhich has the same id as the one provided.
If there is no knownVoiceChannelwith an id that matches the provided one, then this returnsnull.This may also contain
StageChannels!- Parameters:
id- The id of theVoiceChannel.- Returns:
- Possibly-null
VoiceChannelwith matching id.
-
getVoiceChannelsByName
@Nonnull default java.util.List<VoiceChannel> getVoiceChannelsByName(@Nonnull java.lang.String name, boolean ignoreCase)
An unmodifiable list of allVoiceChannelsthat have the same name as the one provided.
If there are noVoiceChannelswith the provided name, then this returns an empty list.This may also contain
StageChannels!- Parameters:
name- The name of the requestedVoiceChannels.ignoreCase- Whether to ignore case or not when comparing the provided name to eachAbstractChannel.getName().- Returns:
- Possibly-empty list of all the
VoiceChannelsthat all have the same name as the provided name.
-
getPrivateChannelCache
@Nonnull SnowflakeCacheView<PrivateChannel> getPrivateChannelCache()
SnowflakeCacheViewof all cachedPrivateChannelsvisible to this JDA session.- Returns:
SnowflakeCacheView
-
getPrivateChannels
@Nonnull default java.util.List<PrivateChannel> 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
@Nullable default PrivateChannel getPrivateChannelById(@Nonnull java.lang.String id)
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:
java.lang.NumberFormatException- If the providedidcannot be parsed byLong.parseLong(String)
-
getPrivateChannelById
@Nullable default PrivateChannel getPrivateChannelById(long id)
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
@Nonnull @CheckReturnValue RestAction<PrivateChannel> openPrivateChannelById(long userId)
Opens aPrivateChannelwith the provided user by id.
This will fail withUNKNOWN_USERif the user does not exist.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:
RestAction- Type:PrivateChannel- Throws:
java.lang.UnsupportedOperationException- If the target user is the currently logged in account- See Also:
User.openPrivateChannel()
-
openPrivateChannelById
@Nonnull @CheckReturnValue default RestAction<PrivateChannel> openPrivateChannelById(@Nonnull java.lang.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:
java.lang.UnsupportedOperationException- If the target user is the currently logged in accountjava.lang.IllegalArgumentException- If the provided id is not a valid snowflake- See Also:
User.openPrivateChannel()
-
getEmoteCache
@Nonnull SnowflakeCacheView<Emote> getEmoteCache()
UnifiedSnowflakeCacheViewof all cachedEmotesvisible to this JDA session.- Returns:
- Unified
SnowflakeCacheView - See Also:
CacheView.allSnowflakes(...)
-
getEmotes
@Nonnull default java.util.List<Emote> getEmotes()
A collection of all to us known emotes (managed/restricted included).
This will be empty ifCacheFlag.EMOTEis disabled.Hint: To check whether you can use an
Emotein a specific context you can useEmote.canInteract(net.dv8tion.jda.api.entities.Member)orEmote.canInteract(net.dv8tion.jda.api.entities.User, net.dv8tion.jda.api.entities.MessageChannel)Unicode emojis are not included as
Emote!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
getEmoteCache()and use its more efficient versions of handling these values.- Returns:
- An immutable list of Emotes (which may or may not be available to usage).
-
getEmoteById
@Nullable default Emote getEmoteById(@Nonnull java.lang.String id)
Retrieves an emote matching the specifiedidif one is available in our cache.
This will be null ifCacheFlag.EMOTEis disabled.Unicode emojis are not included as
Emote!
-
getEmoteById
@Nullable default Emote getEmoteById(long id)
Retrieves an emote matching the specifiedidif one is available in our cache.
This will be null ifCacheFlag.EMOTEis disabled.Unicode emojis are not included as
Emote!
-
getEmotesByName
@Nonnull default java.util.List<Emote> getEmotesByName(@Nonnull java.lang.String name, boolean ignoreCase)
An unmodifiable list of allEmotesthat have the same name as the one provided.
If there are noEmoteswith the provided name, then this returns an empty list.
This will be empty ifCacheFlag.EMOTEis disabled.Unicode emojis are not included as
Emote!- Parameters:
name- The name of the requestedEmotes. Without colons.ignoreCase- Whether to ignore case or not when comparing the provided name to eachEmote.getName().- Returns:
- Possibly-empty list of all the
Emotesthat all have the same name as the provided name.
-
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 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.
-
getShardInfo
@Nonnull JDA.ShardInfo 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
@Nonnull java.lang.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 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()
-
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:
shutdown()
-
getAccountType
@Nonnull AccountType 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
@Nonnull @CheckReturnValue RestAction<ApplicationInfo> 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
@Nonnull default JDA setRequiredScopes(@Nonnull java.lang.String... scopes)
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:
java.lang.IllegalArgumentException- If null is provided
-
setRequiredScopes
@Nonnull JDA setRequiredScopes(@Nonnull java.util.Collection<java.lang.String> scopes)
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:
java.lang.IllegalArgumentException- If null is provided
-
getInviteUrl
@Nonnull java.lang.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=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
@Nonnull java.lang.String getInviteUrl(@Nullable java.util.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=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
@Nullable ShardManager 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
@Nonnull @CheckReturnValue RestAction<Webhook> retrieveWebhookById(@Nonnull java.lang.String webhookId)
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:
java.lang.IllegalArgumentException- If thewebhookIdis null or empty- See Also:
Guild.retrieveWebhooks(),TextChannel.retrieveWebhooks()
-
retrieveWebhookById
@Nonnull @CheckReturnValue default RestAction<Webhook> retrieveWebhookById(long webhookId)
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:
Guild.retrieveWebhooks(),TextChannel.retrieveWebhooks()
-
installAuxiliaryPort
@Nonnull @CheckReturnValue default AuditableRestAction<java.lang.Integer> installAuxiliaryPort()
Installs an auxiliary port for audio transfer.- Returns:
AuditableRestAction- Type: int Provides the resulting used port- Throws:
java.lang.IllegalStateException- If this is a headless environment or no port is available
-
-