Class GuildController
- java.lang.Object
-
- net.dv8tion.jda.core.managers.GuildController
-
public class GuildController extends java.lang.Object
A controller that allows to utilize moderation permissions and create new channels and roles.- Since:
- 3.0
-
-
Constructor Summary
Constructors Constructor Description GuildController(Guild guild)
Creates a new GuildController instance for the specified Guild instance
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description AuditableRestAction<java.lang.Void>
addRolesToMember(Member member, java.util.Collection<Role> roles)
AuditableRestAction<java.lang.Void>
addRolesToMember(Member member, Role... roles)
AuditableRestAction<java.lang.Void>
addSingleRoleToMember(Member member, Role role)
AuditableRestAction<java.lang.Void>
ban(java.lang.String userId, int delDays)
Bans the a user specified by the userId and deletes messages sent by the user based on the amount of delDays.AuditableRestAction<java.lang.Void>
ban(java.lang.String userId, int delDays, java.lang.String reason)
Bans the a user specified by the userId and deletes messages sent by the user based on the amount of delDays.AuditableRestAction<java.lang.Void>
ban(Member member, int delDays)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.AuditableRestAction<java.lang.Void>
ban(Member member, int delDays, java.lang.String reason)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.AuditableRestAction<java.lang.Void>
ban(User user, int delDays)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.AuditableRestAction<java.lang.Void>
ban(User user, int delDays, java.lang.String reason)
Bans aUser
and deletes messages sent by the user based on the amount of delDays.ChannelAction
createCategory(java.lang.String name)
Creates a newCategory
in this Guild.ChannelAction
createCopyOfChannel(Channel channel)
RoleAction
createCopyOfRole(Role role)
AuditableRestAction<Emote>
createEmote(java.lang.String name, Icon icon, Role... roles)
Creates a newEmote
in this Guild.RoleAction
createRole()
Creates a newRole
in this Guild.ChannelAction
createTextChannel(java.lang.String name)
Creates a newTextChannel
in this Guild.ChannelAction
createVoiceChannel(java.lang.String name)
Creates a newVoiceChannel
in this Guild.Guild
getGuild()
The underlyingGuild
instanceJDA
getJDA()
TheJDA
instance of this GuildControllerAuditableRestAction<java.lang.Void>
kick(java.lang.String userId)
AuditableRestAction<java.lang.Void>
kick(java.lang.String userId, java.lang.String reason)
AuditableRestAction<java.lang.Void>
kick(Member member)
AuditableRestAction<java.lang.Void>
kick(Member member, java.lang.String reason)
ChannelOrderAction<Category>
modifyCategoryPositions()
Modifies the positional order ofGuild.getCategories()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.AuditableRestAction<java.lang.Void>
modifyMemberRoles(Member member, java.util.Collection<Role> roles)
AuditableRestAction<java.lang.Void>
modifyMemberRoles(Member member, java.util.Collection<Role> rolesToAdd, java.util.Collection<Role> rolesToRemove)
AuditableRestAction<java.lang.Void>
modifyMemberRoles(Member member, Role... roles)
RoleOrderAction
modifyRolePositions()
Modifies the positional order ofGuild.getRoles()
using a specificRestAction
extension to allow moving Rolesup
/down
orto
a specific position.RoleOrderAction
modifyRolePositions(boolean useDiscordOrder)
Modifies the positional order ofGuild.getRoles()
using a specificRestAction
extension to allow moving Rolesup
/down
orto
a specific position.ChannelOrderAction<TextChannel>
modifyTextChannelPositions()
Modifies the positional order ofGuild.getTextChannels()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.CategoryOrderAction<TextChannel>
modifyTextChannelPositions(Category category)
Modifies the positional order ofCategory#getTextChannels()
using an extension ofChannelOrderAction
specialized for ordering the nestedTextChannels
of thisCategory
.ChannelOrderAction<VoiceChannel>
modifyVoiceChannelPositions()
Modifies the positional order ofGuild.getVoiceChannels()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.CategoryOrderAction<VoiceChannel>
modifyVoiceChannelPositions(Category category)
Modifies the positional order ofCategory#getVoiceChannels()
using an extension ofChannelOrderAction
specialized for ordering the nestedVoiceChannels
of thisCategory
.RestAction<java.lang.Void>
moveVoiceMember(Member member, VoiceChannel voiceChannel)
AuditableRestAction<java.lang.Integer>
prune(int days)
This method will prune (kick) all members who were offline for at least days days.AuditableRestAction<java.lang.Void>
removeRolesFromMember(Member member, java.util.Collection<Role> roles)
AuditableRestAction<java.lang.Void>
removeRolesFromMember(Member member, Role... roles)
AuditableRestAction<java.lang.Void>
removeSingleRoleFromMember(Member member, Role role)
AuditableRestAction<java.lang.Void>
setDeafen(Member member, boolean deafen)
Sets the Guild Deafened state state of theMember
based on the provided boolean.AuditableRestAction<java.lang.Void>
setMute(Member member, boolean mute)
Sets the Guild Muted state state of theMember
based on the provided boolean.AuditableRestAction<java.lang.Void>
setNickname(Member member, java.lang.String nickname)
Changes a Member's nickname in this guild.AuditableRestAction<java.lang.Void>
transferOwnership(Member newOwner)
Transfers the Guild ownership to the specifiedMember
Only available if the currently logged in account is the owner of this GuildAuditableRestAction<java.lang.Void>
unban(java.lang.String userId)
Unbans the a user specified by the userId from this Guild.AuditableRestAction<java.lang.Void>
unban(User user)
Unbans the specifiedUser
from this Guild.
-
-
-
Method Detail
-
getGuild
public Guild getGuild()
The underlyingGuild
instance- Returns:
- The underlying
Guild
instance
-
getJDA
public JDA getJDA()
TheJDA
instance of this GuildController- Returns:
- the corresponding JDA instance
-
moveVoiceMember
@CheckReturnValue public RestAction<java.lang.Void> moveVoiceMember(Member member, VoiceChannel voiceChannel)
Used to move aMember
from oneVoiceChannel
to anotherVoiceChannel
.
As a note, you cannot move a Member that isn't already in a VoiceChannel. Also they must be in a VoiceChannel in the same Guild as the one that you are moving them to.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be moved due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the taskUNKNOWN_CHANNEL
The specified channel was deleted before finishing the task
- Parameters:
member
- TheMember
that you are moving.voiceChannel
- The destinationVoiceChannel
to which the member is being moved to.- Returns:
RestAction
- Throws:
java.lang.IllegalStateException
- If the Member isn't currently in a VoiceChannel in this Guild, orCacheFlag.VOICE_STATE
is disabled.java.lang.IllegalArgumentException
-InsufficientPermissionException
-- If this account doesn't have
Permission.VOICE_MOVE_OTHERS
in the VoiceChannel that the Member is currently in. - If this account AND the Member being moved don't have
Permission.VOICE_CONNECT
for the destination VoiceChannel.
- If this account doesn't have
-
setNickname
@CheckReturnValue public AuditableRestAction<java.lang.Void> setNickname(Member member, java.lang.String nickname)
Changes a Member's nickname in this guild. The nickname is visible to all members of this guild.To change the nickname for the currently logged in account only the Permission
NICKNAME_CHANGE
is required.
To change the nickname of anyMember
for thisGuild
the PermissionNICKNAME_MANAGE
is required.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The nickname of the target Member is not modifiable due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
for which the nickname should be changed.nickname
- The new nickname of theMember
, providenull
or an empty String to reset the nickname- Returns:
AuditableRestAction
- Throws:
java.lang.IllegalArgumentException
- If the specifiedMember
is not from the sameGuild
. Or if the provided member isnull
InsufficientPermissionException
-- If attempting to set nickname for self and the logged in account has neither
Permission.NICKNAME_CHANGE
orPermission.NICKNAME_MANAGE
- If attempting to set nickname for another member and the logged in account does not have
Permission.NICKNAME_MANAGE
- If attempting to set nickname for self and the logged in account has neither
HierarchyException
- If attempting to set nickname for another member and the logged in account cannot manipulate the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
-
prune
@CheckReturnValue public AuditableRestAction<java.lang.Integer> prune(int days)
This method will prune (kick) all members who were offline for at least days days.
The RestAction returned from this method will return the amount of Members that were pruned.
You can useGuild.getPrunableMemberCount(int)
to determine how many Members would be pruned if you were to call this method.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The prune cannot finished due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
days
- Minimum number of days since a member has been offline to get affected.- Returns:
AuditableRestAction
- Type: Integer
The amount of Members that were pruned from the Guild.- Throws:
InsufficientPermissionException
- If the account doesn't haveKICK_MEMBER
Permission.java.lang.IllegalArgumentException
- If the provided days are less than1
-
kick
@CheckReturnValue public AuditableRestAction<java.lang.Void> kick(Member member, java.lang.String reason)
Kicks aMember
from theGuild
.Note:
Guild.getMembers()
will still contain theUser
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be kicked due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
to kick from the from theGuild
.reason
- The reason for this action ornull
if there is no specified reason- Returns:
AuditableRestAction
Kicks the provided Member from the current Guild- Throws:
java.lang.IllegalArgumentException
- If the provided member is not a Member of this Guild or isnull
InsufficientPermissionException
- If the logged in account does not have thePermission.KICK_MEMBERS
permission.HierarchyException
- If the logged in account cannot kick the other member due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
-
kick
@CheckReturnValue public AuditableRestAction<java.lang.Void> kick(java.lang.String userId, java.lang.String reason)
Kicks theMember
specified by the userId from the from theGuild
.Note:
Guild.getMembers()
will still contain theUser
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be kicked due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
userId
- The id of theUser
to kick from the from theGuild
.reason
- The reason for this action ornull
if there is no specified reason- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.KICK_MEMBERS
permission.HierarchyException
- If the logged in account cannot kick the other member due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
- If the userId provided does not correspond to a Member in this Guild or the provideduserId
is blank/null.
-
kick
@CheckReturnValue public AuditableRestAction<java.lang.Void> kick(Member member)
Kicks aMember
from theGuild
.Note:
Guild.getMembers()
will still contain theUser
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be kicked due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
to kick from the from theGuild
.- Returns:
AuditableRestAction
Kicks the provided Member from the current Guild- Throws:
java.lang.IllegalArgumentException
- If the provided member is not a Member of this Guild or isnull
InsufficientPermissionException
- If the logged in account does not have thePermission.KICK_MEMBERS
permission.HierarchyException
- If the logged in account cannot kick the other member due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
-
kick
@CheckReturnValue public AuditableRestAction<java.lang.Void> kick(java.lang.String userId)
Kicks theMember
specified by the userId from the from theGuild
.Note:
Guild.getMembers()
will still contain theUser
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be kicked due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
userId
- The id of theUser
to kick from the from theGuild
.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.KICK_MEMBERS
permission.HierarchyException
- If the logged in account cannot kick the other member due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
- If the userId provided does not correspond to a Member in this Guild or the provideduserId
is blank/null.
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(Member member, int delDays, java.lang.String reason)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a member without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theMember
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
to ban.delDays
- The history of messages, in days, that will be deleted.reason
- The reason for this action ornull
if there is no specified reason- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
-- If the provided amount of days (delDays) is less than 0.
- If the provided member is
null
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(User user, int delDays, java.lang.String reason)
Bans aUser
and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a user without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theUser's
Member
object (if the User was in the Guild) until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
user
- TheUser
to ban.delDays
- The history of messages, in days, that will be deleted.reason
- The reason for this action ornull
if there is no specified reason- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
-- If the provided amount of days (delDays) is less than 0.
- If the provided user is null
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(java.lang.String userId, int delDays, java.lang.String reason)
Bans the a user specified by the userId and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a user without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theUser's
Member
object (if the User was in the Guild) until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
userId
- The id of theUser
to ban.delDays
- The history of messages, in days, that will be deleted.reason
- The reason for this action ornull
if there is no specified reason- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
- If the provided amount of days (delDays) is less than 0.
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(Member member, int delDays)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a member without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theMember
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
to ban.delDays
- The history of messages, in days, that will be deleted.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
-- If the provided amount of days (delDays) is less than 0.
- If the provided member is
null
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(User user, int delDays)
Bans aMember
and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a member without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theMember
until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
user
- TheUser
to ban.delDays
- The history of messages, in days, that will be deleted.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
-- If the provided amount of days (delDays) is less than 0.
- If the provided member is
null
-
ban
@CheckReturnValue public AuditableRestAction<java.lang.Void> ban(java.lang.String userId, int delDays)
Bans the a user specified by the userId and deletes messages sent by the user based on the amount of delDays.
If you wish to ban a user without deleting any messages, provide delDays with a value of 0. This change will be applied immediately.Note:
Guild.getMembers()
will still contain theUser's
Member
object (if the User was in the Guild) until Discord sends theGuildMemberLeaveEvent
.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be banned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
userId
- The id of theUser
to ban.delDays
- The history of messages, in days, that will be deleted.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.HierarchyException
- If the logged in account cannot ban the other user due to permission hierarchy position.
SeePermissionUtil.canInteract(Member, Member)
java.lang.IllegalArgumentException
- If the provided amount of days (delDays) is less than 0.
-
unban
@CheckReturnValue public AuditableRestAction<java.lang.Void> unban(User user)
Unbans the specifiedUser
from this Guild.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be unbanned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_USER
The specified User is invalid
- Parameters:
user
- The id of theUser
to unban.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.java.lang.IllegalArgumentException
- If the provided user is null
-
unban
@CheckReturnValue public AuditableRestAction<java.lang.Void> unban(java.lang.String userId)
Unbans the a user specified by the userId from this Guild.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be unbanned due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_USER
The specified User is invalid
- Parameters:
userId
- The id of theUser
to unban.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.BAN_MEMBERS
permission.java.lang.IllegalArgumentException
- If the provided id is null or blank
-
setDeafen
@CheckReturnValue public AuditableRestAction<java.lang.Void> setDeafen(Member member, boolean deafen)
Sets the Guild Deafened state state of theMember
based on the provided boolean.Note: The Member's
GuildVoiceState.isGuildDeafened()
value won't change until JDA receives theGuildVoiceGuildDeafenEvent
event related to this change.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be deafened due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
who'sVoiceState
is being changed.deafen
- Whether thisMember
should be deafened or undeafened.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.VOICE_DEAF_OTHERS
permission.HierarchyException
- If the provided member is the Guild's owner. You cannot modify the owner of a Guild.java.lang.IllegalArgumentException
- If the provided member is not from this Guild or null.
-
setMute
@CheckReturnValue public AuditableRestAction<java.lang.Void> setMute(Member member, boolean mute)
Sets the Guild Muted state state of theMember
based on the provided boolean.Note: The Member's
GuildVoiceState.isGuildMuted()
value won't change until JDA receives theGuildVoiceGuildMuteEvent
event related to this change.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The target Member cannot be muted due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The specified Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
who'sVoiceState
is being changed.mute
- Whether thisMember
should be muted or unmuted.- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.VOICE_DEAF_OTHERS
permission.HierarchyException
- If the provided member is the Guild's owner. You cannot modify the owner of a Guild.java.lang.IllegalArgumentException
- If the provided member is not from this Guild or null.
-
addSingleRoleToMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> addSingleRoleToMember(Member member, Role role)
Atomically assigns the providedRole
to the specifiedMember
.
This can be used together with other role modification methods as it does not require an updated cache!If multiple roles should be added/removed (efficiently) in one request you may use
modifyMemberRoles(Member, Collection, Collection)
or similar methods.If the specified role is already present in the member's set of roles this does nothing.
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the taskUNKNOWN_ROLE
If the specified Role does not exist
- Parameters:
member
- The target member who will receive the new rolerole
- The role which should be assigned atomically- Returns:
AuditableRestAction
- Throws:
java.lang.IllegalArgumentException
-- If the specified member/role are not from the current Guild
- Either member or role are
null
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in account
-
removeSingleRoleFromMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> removeSingleRoleFromMember(Member member, Role role)
Atomically removes the providedRole
from the specifiedMember
.
This can be used together with other role modification methods as it does not require an updated cache!If multiple roles should be added/removed (efficiently) in one request you may use
modifyMemberRoles(Member, Collection, Collection)
or similar methods.If the specified role is not present in the member's set of roles this does nothing.
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the taskUNKNOWN_ROLE
If the specified Role does not exist
- Parameters:
member
- The target member who will lose the specified rolerole
- The role which should be removed atomically- Returns:
AuditableRestAction
- Throws:
java.lang.IllegalArgumentException
-- If the specified member/role are not from the current Guild
- Either member or role are
null
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in account
-
addRolesToMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> addRolesToMember(Member member, Role... roles)
Adds all providedRoles
to the specifiedMember
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGuildMemberRoleAddEvent
.
To add and remove Roles from a Member you should usemodifyMemberRoles(Member, Collection, Collection)
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- Not-nullMember
that will receive all provided rolesroles
- Not-null Roles that should be added to the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
addRolesToMember(Member, Collection)
,modifyMemberRoles(Member, Role...)
-
addRolesToMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> addRolesToMember(Member member, java.util.Collection<Role> roles)
Adds all providedRoles
to the specifiedMember
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGuildMemberRoleAddEvent
.
To add and remove Roles from a Member you should usemodifyMemberRoles(Member, Collection, Collection)
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- Not-nullMember
that will receive all provided rolesroles
- Not-null Roles that should be added to the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
addRolesToMember(Member, Role...)
,modifyMemberRoles(Member, Collection)
-
removeRolesFromMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> removeRolesFromMember(Member member, Role... roles)
Removes all providedRoles
from the specifiedMember
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGuildMemberRoleRemoveEvent
.
To add and remove Roles from a Member you should usemodifyMemberRoles(Member, Collection, Collection)
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- Not-nullMember
from which to remove theRoles
roles
- Not-null Roles that should be removed from the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
addRolesToMember(Member, Collection)
,modifyMemberRoles(Member, Role...)
-
removeRolesFromMember
@CheckReturnValue public AuditableRestAction<java.lang.Void> removeRolesFromMember(Member member, java.util.Collection<Role> roles)
Removes all providedRoles
from the specifiedMember
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGuildMemberRoleRemoveEvent
.
To add and remove Roles from a Member you should usemodifyMemberRoles(Member, Collection, Collection)
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- Not-nullMember
from which to remove theRoles
roles
- Not-null Roles that should be removed from the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
addRolesToMember(Member, Role...)
,modifyMemberRoles(Member, Collection)
-
modifyMemberRoles
@CheckReturnValue public AuditableRestAction<java.lang.Void> modifyMemberRoles(Member member, java.util.Collection<Role> rolesToAdd, java.util.Collection<Role> rolesToRemove)
Modifies theRoles
of the specifiedMember
by adding and removing a collection of roles.
None of the provided roles may be the Public Role of the current Guild.
If a role is both inrolesToAdd
androlesToRemove
it will be removed.None of the provided collections may be null
To only add or remove roles use eitherremoveRolesFromMember(Member, Collection)
oraddRolesToMember(Member, Collection)
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGenericGuildMemberEvent
targeting the same Member.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- TheMember
that should be modifiedrolesToAdd
- ACollection
ofRoles
to add to the current Roles the specifiedMember
already hasrolesToRemove
- ACollection
ofRoles
to remove from the current Roles the specifiedMember
already has- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- If any of the provided arguments is
null
- If any of the specified Roles is managed or is the
Public Role
of the Guild
- If any of the provided arguments is
-
modifyMemberRoles
@CheckReturnValue public AuditableRestAction<java.lang.Void> modifyMemberRoles(Member member, Role... roles)
Modifies the completeRole
set of the specifiedMember
The provided roles will replace all current Roles of the specified Member.Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGenericGuildMemberEvent
targeting the same Member.The new roles must not contain the Public Role of the Guild
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- AMember
of which to override the Roles ofroles
- New collection ofRoles
for the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
modifyMemberRoles(Member, Collection)
-
modifyMemberRoles
@CheckReturnValue public AuditableRestAction<java.lang.Void> modifyMemberRoles(Member member, java.util.Collection<Role> roles)
Modifies the completeRole
set of the specifiedMember
The provided roles will replace all current Roles of the specified Member.The new roles must not contain the Public Role of the Guild
Warning
This may not be used together with any other role add/remove/modify methods for the same Member within one event listener cycle! The changes made by this require cache updates which are triggered by lifecycle events which are received later. This may only be called again once the specific Member has been updated by aGenericGuildMemberEvent
targeting the same Member.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The Members Roles could not be modified due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
member
- AMember
of which to override the Roles ofroles
- New collection ofRoles
for the specified Member- Returns:
AuditableRestAction
- Throws:
InsufficientPermissionException
- If the currently logged in account does not havePermission.MANAGE_ROLES
HierarchyException
- If the provided roles are higher in the Guild's hierarchy and thus cannot be modified by the currently logged in accountjava.lang.IllegalArgumentException
-- See Also:
modifyMemberRoles(Member, Collection)
-
transferOwnership
@CheckReturnValue public AuditableRestAction<java.lang.Void> transferOwnership(Member newOwner)
Transfers the Guild ownership to the specifiedMember
Only available if the currently logged in account is the owner of this GuildPossible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The currently logged in account lost ownership before completing the taskMISSING_ACCESS
We were removed from the Guild before finishing the taskUNKNOWN_MEMBER
The target Member was removed from the Guild before finishing the task
- Parameters:
newOwner
- Not-null Member to transfer ownership to- Returns:
AuditableRestAction
- Throws:
PermissionException
- If the currently logged in account is not the owner of this Guildjava.lang.IllegalArgumentException
-- If the specified Member is
null
or not from the same Guild - If the specified Member already is the Guild owner
- If the specified Member is a bot account (
AccountType.BOT
)
- If the specified Member is
-
createTextChannel
@CheckReturnValue public ChannelAction createTextChannel(java.lang.String name)
Creates a newTextChannel
in this Guild. For this to be successful, the logged in account has to have theMANAGE_CHANNEL
PermissionPossible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The channel could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
name
- The name of the TextChannel to create- Returns:
- A specific
ChannelAction
This action allows to set fields for the new TextChannel before creating it - Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.MANAGE_CHANNEL
permissionjava.lang.IllegalArgumentException
- If the provided name isnull
or empty or greater than 100 characters in length
-
createVoiceChannel
@CheckReturnValue public ChannelAction createVoiceChannel(java.lang.String name)
Creates a newVoiceChannel
in this Guild. For this to be successful, the logged in account has to have theMANAGE_CHANNEL
Permission.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The channel could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
name
- The name of the VoiceChannel to create- Returns:
- A specific
ChannelAction
This action allows to set fields for the new VoiceChannel before creating it - Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.MANAGE_CHANNEL
permissionjava.lang.IllegalArgumentException
- If the provided name isnull
or empty or greater than 100 characters in length
-
createCategory
@CheckReturnValue public ChannelAction createCategory(java.lang.String name)
Creates a newCategory
in this Guild. For this to be successful, the logged in account has to have theMANAGE_CHANNEL
Permission.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The channel could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
name
- The name of the Category to create- Returns:
- A specific
ChannelAction
This action allows to set fields for the new Category before creating it - Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.MANAGE_CHANNEL
permissionjava.lang.IllegalArgumentException
- If the provided name isnull
or empty or greater than 100 characters in length
-
createCopyOfChannel
@CheckReturnValue public ChannelAction createCopyOfChannel(Channel channel)
Creates a copy of the specifiedChannel
in thisGuild
.
The provided channel need not be in the same Guild for this to work!This copies the following elements:
- Name
- Parent Category (if present)
- Voice Elements (Bitrate, Userlimit)
- Text Elements (Topic, NSFW)
- All permission overrides for Members/Roles
Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The channel could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
channel
- TheChannel
to use for the copy template- Returns:
- A specific
ChannelAction
This action allows to set fields for the new Channel before creating it! - Throws:
java.lang.IllegalArgumentException
- If the provided channel isnull
InsufficientPermissionException
- If the currently logged in account does not have theMANAGE_CHANNEL
Permission- Since:
- 3.1
- See Also:
createTextChannel(String)
,createVoiceChannel(String)
,ChannelAction
-
createRole
@CheckReturnValue public RoleAction createRole()
Creates a newRole
in this Guild.
It will be placed at the bottom (just over the Public Role) to avoid permission hierarchy conflicts.
For this to be successful, the logged in account has to have theMANAGE_ROLES
PermissionPossible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The role could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskMAX_ROLES_PER_GUILD
There are too many roles in this Guild
- Returns:
RoleAction
Creates a new role with previously selected field values- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.MANAGE_ROLES
Permission
-
createCopyOfRole
@CheckReturnValue public RoleAction createCopyOfRole(Role role)
Creates a newRole
in thisGuild
with the same settings as the givenRole
.
The position of the specified Role does not matter in this case!It will be placed at the bottom (just over the Public Role) to avoid permission hierarchy conflicts.
For this to be successful, the logged in account has to have theMANAGE_ROLES
Permission and allPermissions
the givenRole
has.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The role could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the taskMAX_ROLES_PER_GUILD
There are too many roles in this Guild
- Parameters:
role
- TheRole
that should be copied- Returns:
RoleAction
RoleAction with already copied values from the specifiedRole
- Throws:
InsufficientPermissionException
- If the logged in account does not have thePermission.MANAGE_ROLES
Permission and every Permission the provided Role hasjava.lang.IllegalArgumentException
- If the specified role isnull
-
createEmote
@CheckReturnValue public AuditableRestAction<Emote> createEmote(java.lang.String name, Icon icon, Role... roles)
Creates a newEmote
in this Guild.
If one or more Roles are specified the new Emote will only be available to Members with any of the specified Roles (seeMember.canInteract(Emote)
)
For this to be successful, the logged in account has to have theMANAGE_EMOTES
Permission.Unicode emojis are not included as
Emote
!Note that a guild is limited to 50 normal and 50 animated emotes by default. Some guilds are able to add additional emotes beyond this limitation due to the
MORE_EMOJI
feature (seeGuild.getFeatures()
).
Due to simplicity we do not check for these limits.Possible
ErrorResponses
caused by the returnedRestAction
include the following:MISSING_PERMISSIONS
The emote could not be created due to a permission discrepancyMISSING_ACCESS
We were removed from the Guild before finishing the task
- Parameters:
name
- The name for the new Emoteicon
- TheIcon
for the new Emoteroles
- TheRoles
the new Emote should be restricted to
If no roles are provided the Emote will be available to all Members of this Guild- Returns:
AuditableRestAction
- Type:Emote
- Throws:
InsufficientPermissionException
- If the logged in account does not have theMANAGE_EMOTES
Permission
-
modifyCategoryPositions
@CheckReturnValue public ChannelOrderAction<Category> modifyCategoryPositions()
Modifies the positional order ofGuild.getCategories()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.
This uses ascending order with a 0 based index.Possible
ErrorResponses
include:UNNKOWN_CHANNEL
One of the channels has been deleted before the completion of the taskMISSING_ACCESS
The currently logged in account was removed from the Guild
- Returns:
ChannelOrderAction
- Type:Category
-
modifyTextChannelPositions
@CheckReturnValue public ChannelOrderAction<TextChannel> modifyTextChannelPositions()
Modifies the positional order ofGuild.getTextChannels()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.
This uses ascending order with a 0 based index.Possible
ErrorResponses
include:UNNKOWN_CHANNEL
One of the channels has been deleted before the completion of the taskMISSING_ACCESS
The currently logged in account was removed from the Guild
- Returns:
ChannelOrderAction
- Type:TextChannel
-
modifyVoiceChannelPositions
@CheckReturnValue public ChannelOrderAction<VoiceChannel> modifyVoiceChannelPositions()
Modifies the positional order ofGuild.getVoiceChannels()
using a specificRestAction
extension to allow moving Channelsup
/down
orto
a specific position.
This uses ascending order with a 0 based index.Possible
ErrorResponses
include:UNNKOWN_CHANNEL
One of the channels has been deleted before the completion of the taskMISSING_ACCESS
The currently logged in account was removed from the Guild
- Returns:
ChannelOrderAction
- Type:VoiceChannel
-
modifyTextChannelPositions
@CheckReturnValue public CategoryOrderAction<TextChannel> modifyTextChannelPositions(Category category)
Modifies the positional order ofCategory#getTextChannels()
using an extension ofChannelOrderAction
specialized for ordering the nestedTextChannels
of thisCategory
.
LikeChannelOrderAction
, the returnedCategoryOrderAction
can be used to move TextChannelsup
,down
, orto
a specific position.
This uses ascending order with a 0 based index.Possible
ErrorResponses
include:UNNKOWN_CHANNEL
One of the channels has been deleted before the completion of the task.MISSING_ACCESS
The currently logged in account was removed from the Guild.
- Parameters:
category
- TheCategory
to orderTextChannels
from.- Returns:
CategoryOrderAction
- Type:TextChannel
-
modifyVoiceChannelPositions
@CheckReturnValue public CategoryOrderAction<VoiceChannel> modifyVoiceChannelPositions(Category category)
Modifies the positional order ofCategory#getVoiceChannels()
using an extension ofChannelOrderAction
specialized for ordering the nestedVoiceChannels
of thisCategory
.
LikeChannelOrderAction
, the returnedCategoryOrderAction
can be used to move VoiceChannelsup
,down
, orto
a specific position.
This uses ascending order with a 0 based index.Possible
ErrorResponses
include:UNNKOWN_CHANNEL
One of the channels has been deleted before the completion of the task.MISSING_ACCESS
The currently logged in account was removed from the Guild.
- Parameters:
category
- TheCategory
to orderVoiceChannels
from.- Returns:
CategoryOrderAction
- Type:VoiceChannels
-
modifyRolePositions
@CheckReturnValue public RoleOrderAction modifyRolePositions()
Modifies the positional order ofGuild.getRoles()
using a specificRestAction
extension to allow moving Rolesup
/down
orto
a specific position.This uses the ordering defined by Discord, which is descending!
This means the highest role appears at index0
and the lower role at indexn - 1
.
Providingfalse
tomodifyRolePositions(boolean)
will result in the ordering being in ascending order, with the lower role at index0
and the highest at indexn - 1
.
As a note:Member.getRoles()
andGuild.getRoles()
are both in descending order.Possible
ErrorResponses
include:UNKNOWN_ROLE
One of the roles was deleted before the completion of the taskMISSING_ACCESS
The currently logged in account was removed from the Guild
- Returns:
RoleOrderAction
-
modifyRolePositions
@CheckReturnValue public RoleOrderAction modifyRolePositions(boolean useDiscordOrder)
Modifies the positional order ofGuild.getRoles()
using a specificRestAction
extension to allow moving Rolesup
/down
orto
a specific position.Possible
ErrorResponses
include:UNKNOWN_ROLE
One of the roles was deleted before the completion of the taskMISSING_ACCESS
The currently logged in account was removed from the Guild
- Parameters:
useDiscordOrder
- Defines the ordering of the OrderAction. Iftrue
, the OrderAction will be in the ordering defined by Discord for roles, which is Descending. This means that the highest role appears at index0
and the lowest role at indexn - 1
. Providingfalse
will result in the ordering being in ascending order, with the lower role at index0
and the highest at indexn - 1
.
As a note:Member.getRoles()
andGuild.getRoles()
are both in descending order.- Returns:
RoleOrderAction
-
-