Package net.dv8tion.jda.api.entities

Interface GuildChannel

All Superinterfaces:

AbstractChannel, java.lang.Comparable<GuildChannel>, java.util.Formattable, IMentionable, ISnowflake

All Known Subinterfaces:

Category, StageChannel, StoreChannel, TextChannel, VoiceChannel

public interface GuildChannel
extends AbstractChannel, IMentionable, java.lang.Comparable<GuildChannel>

Represents a Guild channel.

See Also:

Guild.getGuildChannelById(long), Guild.getGuildChannelById(ChannelType, long), JDA.getGuildChannelById(long), JDA.getGuildChannelById(ChannelType, long)

Method Summary

Modifier and Type	Method	Description
default ChannelAction<? extends GuildChannel>	createCopy()	Creates a copy of the specified GuildChannel.
ChannelAction<? extends GuildChannel>	createCopy(Guild guild)	Creates a copy of the specified GuildChannel in the specified Guild.
InviteAction	createInvite()	Creates a new InviteAction which can be used to create a new Invite.
PermissionOverrideAction	createPermissionOverride(IPermissionHolder permissionHolder)	Creates a PermissionOverride for the specified Member or Role in this GuildChannel.
AuditableRestAction<java.lang.Void>	delete()	Deletes this GuildChannel.
Guild	getGuild()	Returns the Guild that this GuildChannel is part of.
ChannelManager	getManager()	Returns the ChannelManager for this GuildChannel.
java.util.List<PermissionOverride>	getMemberPermissionOverrides()	Gets all of the Member PermissionOverrides that are part of this GuildChannel.
java.util.List<Member>	getMembers()	A List of all Members that are in this GuildChannel For TextChannels, this returns all Members with the Permission.MESSAGE_READ Permission.
Category	getParent()	Parent Category of this GuildChannel.
PermissionOverride	getPermissionOverride(IPermissionHolder permissionHolder)	The PermissionOverride relating to the specified Member or Role.
java.util.List<PermissionOverride>	getPermissionOverrides()	Gets all of the PermissionOverrides that are part of this GuildChannel.
int	getPosition()	The position this GuildChannel is displayed at.
int	getPositionRaw()	The actual position of the GuildChannel as stored and given by Discord.
java.util.List<PermissionOverride>	getRolePermissionOverrides()	Gets all of the Role PermissionOverrides that are part of this GuildChannel.
boolean	isSynced()	Whether or not this GuildChannel's PermissionOverrides match those of its parent category.
PermissionOverrideAction	putPermissionOverride(IPermissionHolder permissionHolder)	Creates a PermissionOverride for the specified Member or Role in this GuildChannel.
RestAction<java.util.List<Invite>>	retrieveInvites()	Returns all invites for this channel.
default PermissionOverrideAction	upsertPermissionOverride(IPermissionHolder permissionHolder)	Creates a new override or updates an existing one.

Methods inherited from interface net.dv8tion.jda.api.entities.AbstractChannel

getJDA, getName, getType

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface net.dv8tion.jda.api.entities.IMentionable

formatTo, getAsMention

Methods inherited from interface net.dv8tion.jda.api.entities.ISnowflake

getId, getIdLong, getTimeCreated

Method Detail

getGuild

@Nonnull
Guild getGuild()

Returns the Guild that this GuildChannel is part of.

Returns:

Never-null Guild that this GuildChannel is part of.

getParent

@Nullable
Category getParent()

Parent Category of this GuildChannel. Channels don't need to have a parent Category.
Note that a Category will always return null for this method as nested categories are not supported.

Returns:

Possibly-null Category for this GuildChannel

getMembers

@Nonnull
java.util.List<Member> getMembers()

A List of all Members that are in this GuildChannel
For TextChannels, this returns all Members with the Permission.MESSAGE_READ Permission.
For VoiceChannels, this returns all Members that joined that VoiceChannel.
For Categories, this returns all Members who are in its child channels.

Returns:

An immutable List of Members that are in this GuildChannel.

getPosition

int getPosition()

The position this GuildChannel is displayed at.
Higher values mean they are displayed lower in the Client. Position 0 is the top most GuildChannel Channels of a Guild do not have to have continuous positions

Returns:

Zero-based int of position of the GuildChannel.

Throws:

java.lang.IllegalStateException - If this channel is not in the guild cache

getPositionRaw

int getPositionRaw()

The actual position of the GuildChannel as stored and given by Discord. Channel positions are actually based on a pairing of the creation time (as stored in the snowflake id) and the position. If 2 or more channels share the same position then they are sorted based on their creation date. The more recent a channel was created, the lower it is in the hierarchy. This is handled by getPosition() and it is most likely the method you want. If, for some reason, you want the actual position of the channel then this method will give you that value.

Returns:

The true, Discord stored, position of the GuildChannel.

getPermissionOverride

@Nullable
PermissionOverride getPermissionOverride(@Nonnull
                                         IPermissionHolder permissionHolder)

The PermissionOverride relating to the specified Member or Role. If there is no PermissionOverride for this GuildChannel relating to the provided Member or Role, then this returns null.

Parameters:

permissionHolder - The Member or Role whose PermissionOverride is requested.

Returns:

Possibly-null PermissionOverride relating to the provided Member or Role.

Throws:

java.lang.IllegalArgumentException - If the provided permission holder is null, or from a different guild

getPermissionOverrides

@Nonnull
java.util.List<PermissionOverride> getPermissionOverrides()

Gets all of the PermissionOverrides that are part of this GuildChannel.
This combines Member and Role overrides. If you would like only Member overrides or only Role overrides, use getMemberPermissionOverrides() or getRolePermissionOverrides() respectively.

This requires CacheFlag.MEMBER_OVERRIDES to be enabled! Without that CacheFlag, this list will only contain overrides for the currently logged in account and roles.

Returns:

Possibly-empty immutable list of all PermissionOverrides for this GuildChannel.

getMemberPermissionOverrides

@Nonnull
java.util.List<PermissionOverride> getMemberPermissionOverrides()

Gets all of the Member PermissionOverrides that are part of this GuildChannel.

This requires CacheFlag.MEMBER_OVERRIDES to be enabled!

Returns:

Possibly-empty immutable list of all PermissionOverrides for Member for this GuildChannel.

getRolePermissionOverrides

@Nonnull
java.util.List<PermissionOverride> getRolePermissionOverrides()

Gets all of the Role PermissionOverrides that are part of this GuildChannel.

Returns:

Possibly-empty immutable list of all PermissionOverrides for Roles for this GuildChannel.

isSynced

boolean isSynced()

Whether or not this GuildChannel's PermissionOverrides match those of its parent category. If the channel doesn't have a parent category, this will return true.

This requires CacheFlag.MEMBER_OVERRIDES to be enabled.
createLight(String) disables this CacheFlag by default.

Returns:

True, if this channel is synced with its parent category

Since:

4.2.1

createCopy

@Nonnull
@CheckReturnValue
ChannelAction<? extends GuildChannel> createCopy(@Nonnull
                                                 Guild guild)

Creates a copy of the specified GuildChannel in the specified Guild.
If the provided target guild is not the same Guild this channel is in then the parent category and permissions will not be copied due to technical difficulty and ambiguity.

This copies the following elements:

1. Name
2. Parent Category (if present)
3. Voice Elements (Bitrate, Userlimit)
4. Text Elements (Topic, NSFW, Slowmode)
5. All permission overrides for Members/Roles

Possible ErrorResponses caused by the returned RestAction include the following:

• MISSING_PERMISSIONS
  The channel could not be created due to a permission discrepancy
• MISSING_ACCESS
  The VIEW_CHANNEL permission was removed

Parameters:

guild - The Guild to create the channel in

Returns:

A specific ChannelAction
This action allows to set fields for the new GuildChannel before creating it!

Throws:

java.lang.IllegalArgumentException - If the provided guild is null

PermissionException - If the currently logged in account does not have the MANAGE_CHANNEL Permission

createCopy

@Nonnull
@CheckReturnValue
default ChannelAction<? extends GuildChannel> createCopy()

Creates a copy of the specified GuildChannel.

This copies the following elements:

1. Name
2. Parent Category (if present)
3. Voice Elements (Bitrate, Userlimit)
4. Text Elements (Topic, NSFW, Slowmode)
5. All permission overrides for Members/Roles

Possible ErrorResponses caused by the returned RestAction include the following:

• MISSING_PERMISSIONS
  The channel could not be created due to a permission discrepancy
• MISSING_ACCESS
  The VIEW_CHANNEL permission was removed

Returns:

A specific ChannelAction
This action allows to set fields for the new GuildChannel before creating it!

Throws:

PermissionException - If the currently logged in account does not have the MANAGE_CHANNEL Permission

getManager

@Nonnull
ChannelManager getManager()

Returns the ChannelManager for this GuildChannel.
In the ChannelManager, you can modify the name, topic and position of this GuildChannel. You modify multiple fields in one request by chaining setters before calling RestAction.queue().

This is a lazy idempotent getter. The manager is retained after the first call. This getter is not thread-safe and would require guards by the user.

Returns:

The ChannelManager of this GuildChannel

Throws:

InsufficientPermissionException - If the currently logged in account does not have Permission.MANAGE_CHANNEL

delete

@Nonnull
@CheckReturnValue
AuditableRestAction<java.lang.Void> delete()

Deletes this GuildChannel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  If this channel was already deleted
• MISSING_PERMISSIONS
  The send request was attempted after the account lost Permission.MANAGE_CHANNEL in the channel.
• MISSING_ACCESS
  If we were removed from the Guild

Returns:

AuditableRestAction

Throws:

InsufficientPermissionException - if the currently logged in account doesn't have MANAGE_CHANNEL for the channel.

createPermissionOverride

@Nonnull
@CheckReturnValue
PermissionOverrideAction createPermissionOverride(@Nonnull
                                                  IPermissionHolder permissionHolder)

Creates a PermissionOverride for the specified Member or Role in this GuildChannel. You can use putPermissionOverride(IPermissionHolder) to replace existing overrides.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  If this channel was already deleted
• MISSING_ACCESS
  If we were removed from the Guild

Parameters:

permissionHolder - The Member or Role to create an override for

Returns:

PermissionOverrideAction Provides the newly created PermissionOverride for the specified permission holder

Throws:

InsufficientPermissionException - if we don't have the permission to MANAGE_PERMISSIONS

java.lang.IllegalArgumentException - if the specified permission holder is null or is not from getGuild()

java.lang.IllegalStateException - If the specified permission holder already has a PermissionOverride. Use getPermissionOverride(IPermissionHolder) to retrieve it. You can use putPermissionOverride(IPermissionHolder) to replace existing overrides.

putPermissionOverride

@Nonnull
@CheckReturnValue
PermissionOverrideAction putPermissionOverride(@Nonnull
                                               IPermissionHolder permissionHolder)

Creates a PermissionOverride for the specified Member or Role in this GuildChannel.
If the permission holder already has an existing override it will be replaced.

Parameters:

permissionHolder - The Member or Role to create the override for

Returns:

PermissionOverrideAction Provides the newly created PermissionOverride for the specified permission holder

Throws:

InsufficientPermissionException - if we don't have the permission to MANAGE_PERMISSIONS

java.lang.IllegalArgumentException - If the provided permission holder is null or from a different guild

upsertPermissionOverride

@Nonnull
@CheckReturnValue
default PermissionOverrideAction upsertPermissionOverride(@Nonnull
                                                          IPermissionHolder permissionHolder)

Creates a new override or updates an existing one.
This is similar to calling PermissionOverride.getManager() if an override exists.

Parameters:

permissionHolder - The Member/Role for the override

Returns:

PermissionOverrideAction
With the current settings of an existing override or a fresh override with no permissions set

Throws:

InsufficientPermissionException - If we don't have the permission to MANAGE_PERMISSIONS

java.lang.IllegalArgumentException - If the provided permission holder is null or not from this guild

Since:

4.0.0

createInvite

@Nonnull
@CheckReturnValue
InviteAction createInvite()

Creates a new InviteAction which can be used to create a new Invite.
Requires CREATE_INSTANT_INVITE in this channel.

Returns:

A new InviteAction

Throws:

InsufficientPermissionException - If the account does not have CREATE_INSTANT_INVITE in this channel

java.lang.IllegalArgumentException - If this is an instance of a Category

See Also:

InviteAction

retrieveInvites

@Nonnull
@CheckReturnValue
RestAction<java.util.List<Invite>> retrieveInvites()

Returns all invites for this channel.
Requires MANAGE_CHANNEL in this channel. Will throw an InsufficientPermissionException otherwise.

Returns:

RestAction - Type: List<Invite>
The list of expanded Invite objects

Throws:

InsufficientPermissionException - if the account does not have MANAGE_CHANNEL in this channel

See Also:

Guild.retrieveInvites()