Package net.dv8tion.jda.api

Interface JDA

  • public interface JDA
    The 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

    • Method Detail

      • getStatus

        @Nonnull
JDA.Status getStatus()
        Gets the current Status of the JDA instance.
        Returns:
        Current JDA status.

      • getGatewayIntents

        @Nonnull
java.util.EnumSet<GatewayIntent> getGatewayIntents()
        The GatewayIntents for this JDA session.
        Returns:
        EnumSet of active gateway intents

      • getCacheFlags

        @Nonnull
java.util.EnumSet<CacheFlag> getCacheFlags()
        The cache flags that have been enabled for this JDA session.
        Returns:
        Copy of the EnumSet of cache flags for this session

      • unloadUser

        boolean unloadUser​(long userId)
        Attempts to remove the user with the provided id from the cache.
        If you attempt to remove the SelfUser this will simply return false.

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

        Parameters:
        userId - The target user id
        Returns:
        True, if the cache was changed

      • getGatewayPing

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

        RestAction request times do not correlate to this value!

        The GatewayPingEvent indicates an update to this value.

        Returns:
        time in milliseconds between heartbeat and the heartbeat ack response
        See Also:
        Getting RestAction ping

      • getRestPing

        @Nonnull
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

        1. INITIALIZING
        2. INITIALIZED
        3. LOGGING_IN
        4. CONNECTING_TO_WEBSOCKET
        5. IDENTIFYING_SESSION
        6. AWAITING_LOGIN_CONFIRMATION
        7. LOADING_SUBSYSTEMS
        8. CONNECTED
        Parameters:
        status - The init status to wait for, once JDA has reached the specified stage of the startup cycle this method will return.
        Returns:
        The current JDA instance, for chaining convenience
        Throws:
        java.lang.InterruptedException - If this thread is interrupted while waiting
        java.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

        1. INITIALIZING
        2. INITIALIZED
        3. LOGGING_IN
        4. CONNECTING_TO_WEBSOCKET
        5. IDENTIFYING_SESSION
        6. AWAITING_LOGIN_CONFIRMATION
        7. LOADING_SUBSYSTEMS
        8. CONNECTED
        Parameters:
        status - The init status to wait for, once JDA has reached the specified stage of the startup cycle this method will return.
        failOn - Optional failure states that will force a premature return
        Returns:
        The current JDA instance, for chaining convenience
        Throws:
        java.lang.InterruptedException - If this thread is interrupted while waiting
        java.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 status JDA.Status.CONNECTED.
        This status means that JDA finished setting up its internal cache and is ready to be used.
        Returns:
        The current JDA instance, for chaining convenience
        Throws:
        java.lang.InterruptedException - If this thread is interrupted while waiting
        java.lang.IllegalStateException - If JDA is shutdown during this wait period

      • getRateLimitPool

        @Nonnull
java.util.concurrent.ScheduledExecutorService getRateLimitPool()
        ScheduledExecutorService used to handle rate-limits for RestAction executions. This is also used in other parts of JDA related to http requests.
        Returns:
        The ScheduledExecutorService used for http request handling
        Since:
        4.0.0

      • getGatewayPool

        @Nonnull
java.util.concurrent.ScheduledExecutorService getGatewayPool()
        ScheduledExecutorService used to send WebSocket messages to discord.
        This involves initial setup of guilds as well as keeping the connection alive.
        Returns:
        The ScheduledExecutorService used for WebSocket transmissions
        Since:
        4.0.0

      • getCallbackPool

        @Nonnull
java.util.concurrent.ExecutorService getCallbackPool()
        ExecutorService used to handle RestAction callbacks and completions. This is also used for handling Message.Attachment downloads when needed.
        By default this uses the CommonPool of the runtime.
        Returns:
        The ExecutorService used for callbacks
        Since:
        4.0.0

      • 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 the InterfacedEventListener by default. To switch to the AnnotatedEventManager, use setEventManager(IEventManager). Note: when using the InterfacedEventListener (default), given listener must be instance of EventListener!
        Parameters:
        listeners - The listener(s) which will react to events.
        Throws:
        java.lang.IllegalArgumentException - If either listeners or one of it's objects is null.

      • 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 is null.

      • 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.

      • retrieveCommandById

        @Nonnull
@CheckReturnValue
RestAction<Command> retrieveCommandById​(@Nonnull
                                        java.lang.String id)
        Retrieves the existing Command instance by id.

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

        Parameters:
        id - The command id
        Returns:
        RestAction - Type: Command
        Throws:
        java.lang.IllegalArgumentException - If the provided id is not a valid snowflake

      • 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 - The CommandData for 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 characters
        description - 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_COMMAND

        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:
        id - The id of the command to edit
        Returns:
        CommandEditAction used 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_COMMAND

        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:
        id - The id of the command to edit
        Returns:
        CommandEditAction used 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_COMMAND

        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:
        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_COMMAND

        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:
        commandId - The id of the command that should be deleted
        Returns:
        RestAction

      • createGuild

        @Nonnull
@CheckReturnValue
GuildAction createGuild​(@Nonnull
                        java.lang.String name)
        Constructs a new Guild with the specified name
        Use the returned GuildAction to provide further details and settings for the resulting Guild!

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

        Parameters:
        name - The name of the resulting guild
        Returns:
        GuildAction
        Allows for setting various details for the resulting Guild
        Throws:
        java.lang.IllegalStateException - If the currently logged in account is in 10 or more guilds
        java.lang.IllegalArgumentException - If the provided name is empty, null or 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 new Guild from the specified template code.

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

        Possible ErrorResponses include:

        Parameters:
        code - The template code to use to create a guild
        name - The name of the resulting guild
        icon - The Icon to use, or null to use no icon
        Returns:
        RestAction
        Throws:
        java.lang.IllegalStateException - If the currently logged in account is in 10 or more guilds
        java.lang.IllegalArgumentException - If the provided name is empty, null or not between 2-100 characters

      • getAudioManagerCache

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

        AudioManagers are cross-session persistent!

        Returns:
        CacheView

      • getAudioManagers

        @Nonnull
default java.util.List<AudioManager> getAudioManagers()
        Immutable list of all created AudioManagers for this JDA instance!
        Returns:
        Immutable list of all created AudioManager instances

      • getUsers

        @Nonnull
default java.util.List<User> getUsers()
        An immutable list of all Users that share a Guild with the currently logged in account.
        This list will never contain duplicates and represents all Users that JDA can currently see.

        This will only check cached users!

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

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

        Returns:
        Immutable list of all Users that are visible to JDA.

      • getUserById

        @Nullable
default User getUserById​(@Nonnull
                         java.lang.String id)
        This returns the User which has the same id as the one provided.
        If there is no visible user with an id that matches the provided one, this returns null.

        This will only check cached users!

        Parameters:
        id - The id of the requested User.
        Returns:
        Possibly-null User with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)
        See Also:
        retrieveUserById(String)

      • getUserById

        @Nullable
default User getUserById​(long id)
        This returns the User which has the same id as the one provided.
        If there is no visible user with an id that matches the provided one, this returns null.

        This will only check cached users!

        Parameters:
        id - The id of the requested User.
        Returns:
        Possibly-null User with matching id.
        See Also:
        retrieveUserById(long)

      • getUserByTag

        @Nullable
default User getUserByTag​(@Nonnull
                          java.lang.String tag)
        Searches for a user that has the matching Discord Tag.
        Format has to be in the form Username#Discriminator where the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.

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

        This will only check cached users!

        Parameters:
        tag - The Discord Tag in the format Username#Discriminator
        Returns:
        The User for the discord tag or null if no user has the provided tag
        Throws:
        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 form Username#Discriminator where the username must be between 2 and 32 characters (inclusive) matching the exact casing and the discriminator must be exactly 4 digits.

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

        This will only check cached users!

        Parameters:
        username - The name of the user
        discriminator - The discriminator of the user
        Returns:
        The User for the discord tag or null if no user has the provided tag
        Throws:
        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 all Users that have the same username as the one provided.
        If there are no Users with the provided name, then this returns an empty list.

        This will only check cached users!

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

        Parameters:
        name - The name of the requested Users.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each User.getName().
        Returns:
        Possibly-empty immutable list of Users that all have the same name as the provided name.

      • getMutualGuilds

        @Nonnull
java.util.List<Guild> getMutualGuilds​(@Nonnull
                                      java.util.Collection<User> users)
        Gets all Guilds that contain all given users as their members.
        Parameters:
        users - The users which all the returned Guilds must contain.
        Returns:
        Immutable list of all Guild instances which have all Users in them.

      • retrieveUserById

        @Nonnull
@CheckReturnValue
default RestAction<User> retrieveUserById​(@Nonnull
                                          java.lang.String id)
        Attempts to retrieve a User object based on the provided id.
        This first calls getUserById(long), and if that returns null or the cache is inconsistent due to disabled intents then a request is made to the Discord servers.

        When the both GUILD_PRESENCES and GUILD_MEMBERS intents are disabled this will always make a request even if the user is cached. You can use retrieveUserById(String, boolean) to disable this behavior.

        The returned RestAction can encounter the following Discord errors:

        • ErrorResponse.UNKNOWN_USER
          Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).
        Parameters:
        id - The id of the requested User.
        Returns:
        RestAction - Type: User
        On request, gets the User with id matching provided id from Discord.
        Throws:
        AccountTypeException - This endpoint is AccountType.BOT only.
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.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 a User object based on the provided id.
        This first calls getUserById(long), and if that returns null or the cache is inconsistent due to disabled intents then a request is made to the Discord servers.

        When the both GUILD_PRESENCES and GUILD_MEMBERS intents are disabled this will always make a request even if the user is cached. You can use retrieveUserById(String, boolean) to disable this behavior.

        The returned RestAction can encounter the following Discord errors:

        • ErrorResponse.UNKNOWN_USER
          Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).
        Parameters:
        id - The id of the requested User.
        Returns:
        RestAction - Type: User
        On request, gets the User with id matching provided id from Discord.
        Throws:
        AccountTypeException - This endpoint is AccountType.BOT only.

      • retrieveUserById

        @Nonnull
@CheckReturnValue
default RestAction<User> retrieveUserById​(@Nonnull
                                          java.lang.String id,
                                          boolean update)
        Attempts to retrieve a User object based on the provided id.
        If both GUILD_MEMBERS and GUILD_PRESENCES intents are disabled this method will update the cached user unless the update parameter is false.
        If either of those intents is enabled, this will immediately provide the cached user if possible.

        The returned RestAction can encounter the following Discord errors:

        • ErrorResponse.UNKNOWN_USER
          Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).
        Parameters:
        id - The id of the requested User.
        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 is AccountType.BOT only.
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.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 a User object based on the provided id.
        If both GUILD_MEMBERS and GUILD_PRESENCES intents are disabled this method will update the cached user unless the update parameter is false.
        If either of those intents is enabled, this will immediately provide the cached user if possible.

        The returned RestAction can encounter the following Discord errors:

        • ErrorResponse.UNKNOWN_USER
          Occurs when the provided id does not refer to a User known by Discord. Typically occurs when developers provide an incomplete id (cut short).
        Parameters:
        id - The id of the requested User.
        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 is AccountType.BOT only.

      • getGuilds

        @Nonnull
default java.util.List<Guild> getGuilds()
        An immutable List of all Guilds that the logged account is connected to.
        If this account is not connected to any Guilds, this will return an empty list.

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

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

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

      • getGuildById

        @Nullable
default Guild getGuildById​(@Nonnull
                           java.lang.String id)
        This returns the Guild which has the same id as the one provided.
        If there is no connected guild with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the Guild.
        Returns:
        Possibly-null Guild with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getGuildById

        @Nullable
default Guild getGuildById​(long id)
        This returns the Guild which has the same id as the one provided.
        If there is no connected guild with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the Guild.
        Returns:
        Possibly-null Guild with matching id.

      • getGuildsByName

        @Nonnull
default java.util.List<Guild> getGuildsByName​(@Nonnull
                                              java.lang.String name,
                                              boolean ignoreCase)
        An immutable list of all Guilds that have the same name as the one provided.
        If there are no Guilds with the provided name, then this returns an empty list.
        Parameters:
        name - The name of the requested Guilds.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each Guild.getName().
        Returns:
        Possibly-empty immutable list of all the Guilds that all have the same name as the provided name.

      • getUnavailableGuilds

        @Nonnull
java.util.Set<java.lang.String> getUnavailableGuilds()
        Set of Guild IDs for guilds that were marked unavailable by the gateway.
        When a guild becomes unavailable a GuildUnavailableEvent is emitted and a GuildAvailableEvent is emitted when it becomes available again. During the time a guild is unavailable it its not reachable through cache such as getGuildById(long).
        Returns:
        Possibly-empty set of guild IDs for unavailable guilds

      • isUnavailable

        boolean isUnavailable​(long guildId)
        Whether the guild is unavailable. If this returns true, the guild id should be in getUnavailableGuilds().
        Parameters:
        guildId - The guild id
        Returns:
        True, if this guild is unavailable

      • getRoles

        @Nonnull
default java.util.List<Role> getRoles()
        All Roles this JDA instance can see.
        This will iterate over each Guild retrieved from getGuilds() and collect its Guild.getRoles().

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

        Returns:
        Immutable List of all visible Roles

      • getRoleById

        @Nullable
default Role getRoleById​(@Nonnull
                         java.lang.String id)
        Retrieves the Role associated to the provided id.
        This iterates over all Guilds and check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.
        Parameters:
        id - The id of the searched Role
        Returns:
        Possibly-null Role for the specified ID
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getRoleById

        @Nullable
default Role getRoleById​(long id)
        Retrieves the Role associated to the provided id.
        This iterates over all Guilds and check whether a Role from that Guild is assigned to the specified ID and will return the first that can be found.
        Parameters:
        id - The id of the searched Role
        Returns:
        Possibly-null Role for the specified ID

      • getRolesByName

        @Nonnull
default java.util.List<Role> getRolesByName​(@Nonnull
                                            java.lang.String name,
                                            boolean ignoreCase)
        Retrieves all Roles visible to this JDA instance.
        This simply filters the Roles returned by getRoles() with the provided name, either using String.equals(Object) or String.equalsIgnoreCase(String) on Role.getName().
        Parameters:
        name - The name for the Roles
        ignoreCase - Whether to use String.equalsIgnoreCase(String)
        Returns:
        Immutable List of all Roles matching the parameters provided.

      • getGuildChannelById

        @Nullable
default GuildChannel getGuildChannelById​(@Nonnull
                                         java.lang.String id)
        Get GuildChannel for 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 null
        java.lang.NumberFormatException - If the provided ID is not a snowflake

      • getStageChannelsByName

        @Nonnull
default java.util.List<StageChannel> getStageChannelsByName​(@Nonnull
                                                            java.lang.String name,
                                                            boolean ignoreCase)
        An unmodifiable list of all StageChannels that have the same name as the one provided.
        If there are no StageChannels with the provided name, then this returns an empty list.
        Parameters:
        name - The name of the requested StageChannels.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each AbstractChannel.getName().
        Returns:
        Possibly-empty list of all the StageChannels that all have the same name as the provided name.

      • getStageChannelById

        @Nullable
default StageChannel getStageChannelById​(@Nonnull
                                         java.lang.String id)
        This returns the StageChannel which has the same id as the one provided.
        If there is no known StageChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the StageChannel.
        Returns:
        Possibly-null StageChannel with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getStageChannelById

        @Nullable
default StageChannel getStageChannelById​(long id)
        This returns the StageChannel which has the same id as the one provided.
        If there is no known StageChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the StageChannel.
        Returns:
        Possibly-null StageChannel with matching id.

      • getStageChannels

        @Nonnull
default java.util.List<StageChannel> getStageChannels()
        An unmodifiable list of all StageChannels of all connected Guilds.

        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.

      • getCategoryById

        @Nullable
default Category getCategoryById​(@Nonnull
                                 java.lang.String id)
        Gets the Category that matches the provided id.
        If there is no matching Category this returns null.
        Parameters:
        id - The snowflake ID of the wanted Category
        Returns:
        Possibly-null Category for the provided ID.
        Throws:
        java.lang.IllegalArgumentException - If the provided ID is not a valid long

      • getCategoryById

        @Nullable
default Category getCategoryById​(long id)
        Gets the Category that matches the provided id.
        If there is no matching Category this returns null.
        Parameters:
        id - The snowflake ID of the wanted Category
        Returns:
        Possibly-null Category for the provided ID.

      • getCategories

        @Nonnull
default java.util.List<Category> getCategories()
        Gets all Categories visible 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 all Categories that 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 check
        ignoreCase - 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 is null

      • getStoreChannelById

        @Nullable
default StoreChannel getStoreChannelById​(@Nonnull
                                         java.lang.String id)
        Gets a StoreChannel that has the same id as the one provided.
        If there is no StoreChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the StoreChannel.
        Returns:
        Possibly-null StoreChannel with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getStoreChannelById

        @Nullable
default StoreChannel getStoreChannelById​(long id)
        Gets a StoreChannel that has the same id as the one provided.
        If there is no StoreChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the StoreChannel.
        Returns:
        Possibly-null StoreChannel with matching id.

      • getStoreChannels

        @Nonnull
default java.util.List<StoreChannel> getStoreChannels()
        Gets all StoreChannels of all connected Guilds.

        This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use 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 all StoreChannels that have the same name as the one provided.
        If there are no StoreChannels with the provided name, then this returns an empty list.
        Parameters:
        name - The name used to filter the returned StoreChannels.
        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.

      • getTextChannels

        @Nonnull
default java.util.List<TextChannel> getTextChannels()
        An unmodifiable List of all TextChannels of all connected Guilds.

        Note: just because a TextChannel is 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 any TextChannel that you don't have the Permission.MESSAGE_READ permission 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 the TextChannel which has the same id as the one provided.
        If there is no known TextChannel with an id that matches the provided one, then this returns null.

        Note: just because a TextChannel is 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 any TextChannel that you don't have the Permission.MESSAGE_READ permission in.

        Parameters:
        id - The id of the TextChannel.
        Returns:
        Possibly-null TextChannel with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getTextChannelById

        @Nullable
default TextChannel getTextChannelById​(long id)
        This returns the TextChannel which has the same id as the one provided.
        If there is no known TextChannel with an id that matches the provided one, then this returns null.

        Note: just because a TextChannel is 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 any TextChannel that you don't have the Permission.MESSAGE_READ permission in.

        Parameters:
        id - The id of the TextChannel.
        Returns:
        Possibly-null TextChannel with matching id.

      • getTextChannelsByName

        @Nonnull
default java.util.List<TextChannel> getTextChannelsByName​(@Nonnull
                                                          java.lang.String name,
                                                          boolean ignoreCase)
        An unmodifiable list of all TextChannels that have the same name as the one provided.
        If there are no TextChannels with the provided name, then this returns an empty list.

        Note: just because a TextChannel is 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 any TextChannel that you don't have the Permission.MESSAGE_READ permission in.

        Parameters:
        name - The name of the requested TextChannels.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each AbstractChannel.getName().
        Returns:
        Possibly-empty list of all the TextChannels that all have the same name as the provided name.

      • getVoiceChannels

        @Nonnull
default java.util.List<VoiceChannel> getVoiceChannels()
        An unmodifiable list of all VoiceChannels of all connected Guilds.

        This copies the backing store into a list. This means every call creates a new list with O(n) complexity. It is recommended to store this into a local variable or use 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 the VoiceChannel which has the same id as the one provided.
        If there is no known VoiceChannel with an id that matches the provided one, then this returns null.

        This may also contain StageChannels!

        Parameters:
        id - The id of the VoiceChannel.
        Returns:
        Possibly-null VoiceChannel with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getVoiceChannelById

        @Nullable
default VoiceChannel getVoiceChannelById​(long id)
        This returns the VoiceChannel which has the same id as the one provided.
        If there is no known VoiceChannel with an id that matches the provided one, then this returns null.

        This may also contain StageChannels!

        Parameters:
        id - The id of the VoiceChannel.
        Returns:
        Possibly-null VoiceChannel with matching id.

      • getVoiceChannelsByName

        @Nonnull
default java.util.List<VoiceChannel> getVoiceChannelsByName​(@Nonnull
                                                            java.lang.String name,
                                                            boolean ignoreCase)
        An unmodifiable list of all VoiceChannels that have the same name as the one provided.
        If there are no VoiceChannels with the provided name, then this returns an empty list.

        This may also contain StageChannels!

        Parameters:
        name - The name of the requested VoiceChannels.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each AbstractChannel.getName().
        Returns:
        Possibly-empty list of all the VoiceChannels that all have the same name as the provided name.

      • getPrivateChannels

        @Nonnull
default java.util.List<PrivateChannel> getPrivateChannels()
        An unmodifiable list of all known PrivateChannels.

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

        Returns:
        Possibly-empty list of all PrivateChannels.

      • getPrivateChannelById

        @Nullable
default PrivateChannel getPrivateChannelById​(@Nonnull
                                             java.lang.String id)
        This returns the PrivateChannel which has the same id as the one provided.
        If there is no known PrivateChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the PrivateChannel.
        Returns:
        Possibly-null PrivateChannel with matching id.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getPrivateChannelById

        @Nullable
default PrivateChannel getPrivateChannelById​(long id)
        This returns the PrivateChannel which has the same id as the one provided.
        If there is no known PrivateChannel with an id that matches the provided one, then this returns null.
        Parameters:
        id - The id of the PrivateChannel.
        Returns:
        Possibly-null PrivateChannel with matching id.

      • openPrivateChannelById

        @Nonnull
@CheckReturnValue
RestAction<PrivateChannel> openPrivateChannelById​(long userId)
        Opens a PrivateChannel with the provided user by id.
        This will fail with UNKNOWN_USER if the user does not exist.

        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 a PrivateChannel with the provided user by id.
        This will fail with UNKNOWN_USER if 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 account
        java.lang.IllegalArgumentException - If the provided id is not a valid snowflake
        See Also:
        User.openPrivateChannel()

      • getEmoteById

        @Nullable
default Emote getEmoteById​(@Nonnull
                           java.lang.String id)
        Retrieves an emote matching the specified id if one is available in our cache.
        This will be null if CacheFlag.EMOTE is disabled.

        Unicode emojis are not included as Emote!

        Parameters:
        id - The id of the requested Emote.
        Returns:
        An Emote represented by this id or null if none is found in our cache.
        Throws:
        java.lang.NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

      • getEmoteById

        @Nullable
default Emote getEmoteById​(long id)
        Retrieves an emote matching the specified id if one is available in our cache.
        This will be null if CacheFlag.EMOTE is disabled.

        Unicode emojis are not included as Emote!

        Parameters:
        id - The id of the requested Emote.
        Returns:
        An Emote represented by this id or null if none is found in our cache.

      • getEmotesByName

        @Nonnull
default java.util.List<Emote> getEmotesByName​(@Nonnull
                                              java.lang.String name,
                                              boolean ignoreCase)
        An unmodifiable list of all Emotes that have the same name as the one provided.
        If there are no Emotes with the provided name, then this returns an empty list.
        This will be empty if CacheFlag.EMOTE is disabled.

        Unicode emojis are not included as Emote!

        Parameters:
        name - The name of the requested Emotes. Without colons.
        ignoreCase - Whether to ignore case or not when comparing the provided name to each Emote.getName().
        Returns:
        Possibly-empty list of all the Emotes that 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 by SelfUser.
        Account settings cannot be modified using this object. If you wish to modify account settings please use the AccountManager which is accessible by SelfUser.getManager().
        Returns:
        The currently logged in account.

      • getShardInfo

        @Nonnull
JDA.ShardInfo getShardInfo()
        The shard information used when creating this instance of JDA.
        Represents the information provided to JDABuilder.useSharding(int, int).
        Returns:
        The shard information for this shard

      • getToken

        @Nonnull
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 using JDABuilder.setMaxReconnectDelay(int).
        Returns:
        The maximum amount of time JDA will wait between reconnect attempts in seconds.

      • setAutoReconnect

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

        Default is true.

        Parameters:
        reconnect - If true - enables autoReconnect

      • setRequestTimeoutRetry

        void setRequestTimeoutRetry​(boolean retryOnTimeout)
        Whether the Requester should retry when a SocketTimeoutException occurs.
        Parameters:
        retryOnTimeout - True, if the Request should retry once on a socket timeout

      • isAutoReconnect

        boolean isAutoReconnect()
        USed to determine whether or not autoReconnect is enabled for JDA.
        Returns:
        True if JDA will attempt to automatically reconnect when a connection-error is encountered.

      • isBulkDeleteSplittingEnabled

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

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

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

      • shutdown

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

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

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

        See Also:
        shutdownNow()

      • shutdownNow

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

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

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

        See Also:
        shutdown()

      • getAccountType

        @Nonnull
AccountType getAccountType()
        The AccountType of the currently logged in account.
        Used when determining functions that are restricted based on the type of account.
        Returns:
        The current AccountType.

      • setRequiredScopes

        @Nonnull
default JDA setRequiredScopes​(@Nonnull
                              java.lang.String... scopes)
        Configures the required scopes applied to the getInviteUrl(Permission...) and similar methods.
        To use slash commands you must add "applications.commands" to these scopes. The scope "bot" is always applied.
        Parameters:
        scopes - The scopes to use with getInviteUrl(Permission...) and the likes
        Returns:
        The current JDA instance
        Throws:
        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 the getInviteUrl(Permission...) and similar methods.
        To use slash commands you must add "applications.commands" to these scopes. The scope "bot" is always applied.
        Parameters:
        scopes - The scopes to use with getInviteUrl(Permission...) and the likes
        Returns:
        The current JDA instance
        Throws:
        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=8

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

        Parameters:
        permissions - The permissions to use in your invite, these can be changed by the link user.
        If no permissions are provided the permissions parameter is omitted
        Returns:
        A valid OAuth2 invite url for the currently logged in Bot-Account
        Throws:
        AccountTypeException - If the currently logged in account is not from AccountType.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=8

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

        Parameters:
        permissions - The permissions to use in your invite, these can be changed by the link user.
        If no permissions are provided the permissions parameter is omitted
        Returns:
        A valid OAuth2 invite url for the currently logged in Bot-Account
        Throws:
        AccountTypeException - If the currently logged in account is not from AccountType.BOT

      • getShardManager

        @Nullable
ShardManager getShardManager()
        Returns the ShardManager that manages this JDA instances or null if this instance is not managed by any ShardManager.
        Returns:
        The corresponding ShardManager or null if there is no such manager

      • 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