net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel Maven / Gradle / Ivy
Show all versions of JDA Show documentation
/*
* Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda.api.entities.channel.middleman;
import net.dv8tion.jda.api.Permission;
import net.dv8tion.jda.api.entities.ISnowflake;
import net.dv8tion.jda.api.entities.Member;
import net.dv8tion.jda.api.entities.Message;
import net.dv8tion.jda.api.entities.User;
import net.dv8tion.jda.api.entities.channel.concrete.TextChannel;
import net.dv8tion.jda.api.entities.channel.concrete.ThreadChannel;
import net.dv8tion.jda.api.entities.emoji.Emoji;
import net.dv8tion.jda.api.entities.sticker.GuildSticker;
import net.dv8tion.jda.api.entities.sticker.Sticker;
import net.dv8tion.jda.api.entities.sticker.StickerSnowflake;
import net.dv8tion.jda.api.exceptions.InsufficientPermissionException;
import net.dv8tion.jda.api.exceptions.MissingAccessException;
import net.dv8tion.jda.api.requests.RestAction;
import net.dv8tion.jda.api.requests.restaction.MessageCreateAction;
import net.dv8tion.jda.internal.utils.Checks;
import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.stream.Collectors;
/**
* Represents all message channels present in guilds.
*
* This includes channels that are not included in {@link StandardGuildMessageChannel}, such as {@link ThreadChannel}.
*
* @see StandardGuildMessageChannel
*/
public interface GuildMessageChannel extends GuildChannel, MessageChannel
{
@Override
default boolean canTalk()
{
return canTalk(getGuild().getSelfMember());
}
/**
* Whether the specified {@link net.dv8tion.jda.api.entities.Member}
* can send messages in this channel.
*
Checks for both {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} and
* {@link net.dv8tion.jda.api.Permission#MESSAGE_SEND Permission.MESSAGE_SEND}.
*
* @param member
* The Member to check
*
* @return True, if the specified member is able to read and send messages in this channel
*/
boolean canTalk(@Nonnull Member member);
/**
* Attempts to remove the reaction from a message represented by the specified {@code messageId}
* in this MessageChannel.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the
* {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or after {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* was revoked in the {@link TextChannel TextChannel}
*
Also can happen if the account lost the {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The request was attempted after the account lost
* {@link net.dv8tion.jda.api.Permission#MESSAGE_ADD_REACTION Permission.MESSAGE_ADD_REACTION} in the
* {@link TextChannel TextChannel}.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_EMOJI}
*
The provided unicode character does not refer to a known emoji unicode character.
*
Proper unicode characters for emojis can be found here:
* Emoji Table
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The provided {@code messageId} is unknown in this MessageChannel, either due to the id being invalid, or
* the message it referred to has already been deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @param messageId
* The messageId to remove the reaction from
* @param emoji
* The emoji to remove
* @param user
* The target user of which to remove from
*
* @throws java.lang.IllegalArgumentException
*
* - If provided {@code messageId} is {@code null} or empty.
* - If provided {@code emoji} is {@code null}.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
*
* @return {@link net.dv8tion.jda.api.requests.RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction removeReactionById(@Nonnull String messageId, @Nonnull Emoji emoji, @Nonnull User user);
/**
* Attempts to remove the reaction from a message represented by the specified {@code messageId}
* in this MessageChannel.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the
* {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or after {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* was revoked in the {@link TextChannel TextChannel}
*
Also can happen if the account lost the {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The request was attempted after the account lost
* {@link net.dv8tion.jda.api.Permission#MESSAGE_ADD_REACTION Permission.MESSAGE_ADD_REACTION} in the
* {@link TextChannel TextChannel}.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_EMOJI}
*
The provided unicode character does not refer to a known emoji unicode character.
*
Proper unicode characters for emojis can be found here:
* Emoji Table
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The provided {@code messageId} is unknown in this MessageChannel, either due to the id being invalid, or
* the message it referred to has already been deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @param messageId
* The messageId to remove the reaction from
* @param emoji
* The emoji to remove
* @param user
* The target user of which to remove from
*
* @throws java.lang.IllegalArgumentException
*
* - If provided {@code messageId} is {@code null} or empty.
* - If provided {@code emoji} is {@code null}.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
*
* @return {@link net.dv8tion.jda.api.requests.RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction removeReactionById(long messageId, @Nonnull Emoji emoji, @Nonnull User user)
{
return removeReactionById(Long.toUnsignedString(messageId), emoji, user);
}
/**
* Bulk deletes a list of messages.
* This is not the same as calling {@link net.dv8tion.jda.api.entities.Message#delete()} in a loop.
*
This is much more efficient, but it has a different ratelimit. You may call this once per second per Guild.
*
* Must be at least 2 messages and not be more than 100 messages at a time.
*
If you only have 1 message, use the {@link net.dv8tion.jda.api.entities.Message#delete()} method instead.
*
*
You must have the Permission {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE MESSAGE_MANAGE} in this channel to use
* this function.
*
*
This method is best used when using {@link net.dv8tion.jda.api.entities.MessageHistory MessageHistory} to delete a large amount
* of messages. If you have a large amount of messages but only their message Ids, please use {@link #deleteMessagesByIds(Collection)}
*
*
Possible ErrorResponses include:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
if this channel was deleted
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
if any of the provided messages does not exist
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
if we were removed from the guild
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The send request was attempted after the account lost
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in the channel.
*
*
* @param messages
* The collection of messages to delete.
*
* @throws IllegalArgumentException
* If the size of the list less than 2 or more than 100 messages.
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If this account does not have {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*
* @see #deleteMessagesByIds(Collection)
* @see #purgeMessages(List)
*/
@Nonnull
@CheckReturnValue
default RestAction deleteMessages(@Nonnull Collection messages)
{
Checks.notEmpty(messages, "Messages collection");
return deleteMessagesByIds(messages.stream()
.map(ISnowflake::getId)
.collect(Collectors.toList()));
}
/**
* Bulk deletes a list of messages.
* This is not the same as calling {@link MessageChannel#deleteMessageById(String)} in a loop.
*
This is much more efficient, but it has a different ratelimit. You may call this once per second per Guild.
*
* Must be at least 2 messages and not be more than 100 messages at a time.
*
If you only have 1 message, use the {@link net.dv8tion.jda.api.entities.Message#delete()} method instead.
*
*
You must have {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel to use
* this function.
*
*
This method is best used when you have a large amount of messages but only their message Ids. If you are using
* {@link net.dv8tion.jda.api.entities.MessageHistory MessageHistory} or have {@link net.dv8tion.jda.api.entities.Message Message}
* objects, it would be easier to use {@link #deleteMessages(java.util.Collection)}.
*
*
Possible ErrorResponses include:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
if this channel was deleted
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
if any of the provided messages does not exist
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
if we were removed from the guild
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The send request was attempted after the account lost
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in the channel.
*
*
* @param messageIds
* The message ids for the messages to delete.
*
* @throws java.lang.IllegalArgumentException
* If the size of the list less than 2 or more than 100 messages.
* @throws java.lang.NumberFormatException
* If any of the provided ids cannot be parsed by {@link Long#parseLong(String)}
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If this account does not have {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*
* @see #deleteMessages(Collection)
* @see #purgeMessagesById(List)
*/
@Nonnull
@CheckReturnValue
RestAction deleteMessagesByIds(@Nonnull Collection messageIds);
/**
* Attempts to remove all reactions from a message with the specified {@code messageId} in this TextChannel
*
This is useful for moderator commands that wish to remove all reactions at once from a specific message.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The clear-reactions request was attempted after the account lost access to the {@link TextChannel TextChannel}
* due to {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} being revoked, or the
* account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The clear-reactions request was attempted after the account lost {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
* in the {@link TextChannel TextChannel} when adding the reaction.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* The clear-reactions request was attempted after the Message had been deleted.
*
*
* @param messageId
* The not-empty valid message id
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
* @throws java.lang.IllegalArgumentException
* If the provided {@code id} is {@code null} or empty.
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*/
@Nonnull
@CheckReturnValue
RestAction clearReactionsById(@Nonnull String messageId);
/**
* Attempts to remove all reactions from a message with the specified {@code messageId} in this TextChannel
*
This is useful for moderator commands that wish to remove all reactions at once from a specific message.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The clear-reactions request was attempted after the account lost access to the {@link TextChannel TextChannel}
* due to {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} being revoked, or the
* account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The clear-reactions request was attempted after the account lost {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
* in the {@link TextChannel TextChannel} when adding the reaction.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* The clear-reactions request was attempted after the Message had been deleted.
*
*
* @param messageId
* The message id
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.api.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
*
* @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction clearReactionsById(long messageId)
{
return clearReactionsById(Long.toUnsignedString(messageId));
}
/**
* Removes all reactions for the specified emoji.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The currently logged in account lost access to the channel by either being removed from the guild
* or losing the {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL VIEW_CHANNEL} permission
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_EMOJI UNKNOWN_EMOJI}
*
The provided {@link Emoji} was deleted or doesn't exist.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The message was deleted.
*
*
* @param messageId
* The id for the target message
* @param emoji
* The {@link Emoji} to remove reactions for
*
* @throws InsufficientPermissionException
* If the currently logged in account does not have {@link Permission#MESSAGE_MANAGE} in the channel
* @throws IllegalArgumentException
* If provided with null
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction clearReactionsById(@Nonnull String messageId, @Nonnull Emoji emoji);
/**
* Removes all reactions for the specified emoji.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The currently logged in account lost access to the channel by either being removed from the guild
* or losing the {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL VIEW_CHANNEL} permission
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_EMOJI UNKNOWN_EMOJI}
*
The provided {@link Emoji} was deleted or doesn't exist.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The message was deleted.
*
*
* @param messageId
* The id for the target message
* @param emoji
* The {@link Emoji} to remove reactions for
*
* @throws InsufficientPermissionException
* If the currently logged in account does not have {@link Permission#MESSAGE_MANAGE} in the channel
* @throws IllegalArgumentException
* If provided with null
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction clearReactionsById(long messageId, @Nonnull Emoji emoji)
{
return clearReactionsById(Long.toUnsignedString(messageId), emoji);
}
/**
* Send up to 3 stickers in this channel.
*
Bots can only send {@link GuildSticker GuildStickers} from the same {@link net.dv8tion.jda.api.entities.Guild}.
* Bots cannot use {@link net.dv8tion.jda.api.entities.sticker.StandardSticker StandardStickers}.
*
* @param stickers
* Collection of 1-3 stickers to send
*
* @throws MissingAccessException
* If the currently logged in account does not have {@link Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} in this channel
* @throws InsufficientPermissionException
*
* - If this is a {@link ThreadChannel} and the bot does not have {@link Permission#MESSAGE_SEND_IN_THREADS Permission.MESSAGE_SEND_IN_THREADS}
* - If this is not a {@link ThreadChannel} and the bot does not have {@link Permission#MESSAGE_SEND Permission.MESSAGE_SEND}
*
* @throws IllegalArgumentException
*
* - If any of the provided stickers is a {@link GuildSticker},
* which is either {@link GuildSticker#isAvailable() unavailable} or from a different guild.
* - If the list is empty or has more than 3 stickers
* - If null is provided
*
*
* @return {@link MessageCreateAction}
*
* @see Sticker#fromId(long)
*/
@Nonnull
@CheckReturnValue
MessageCreateAction sendStickers(@Nonnull Collection stickers);
/**
* Send up to 3 stickers in this channel.
*
Bots can only send {@link GuildSticker GuildStickers} from the same {@link net.dv8tion.jda.api.entities.Guild}.
* Bots cannot use {@link net.dv8tion.jda.api.entities.sticker.StandardSticker StandardStickers}.
*
* @param stickers
* The 1-3 stickers to send
*
* @throws MissingAccessException
* If the currently logged in account does not have {@link Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} in this channel
* @throws InsufficientPermissionException
*
* - If this is a {@link ThreadChannel} and the bot does not have {@link Permission#MESSAGE_SEND_IN_THREADS Permission.MESSAGE_SEND_IN_THREADS}
* - If this is not a {@link ThreadChannel} and the bot does not have {@link Permission#MESSAGE_SEND Permission.MESSAGE_SEND}
*
* @throws IllegalArgumentException
*
* - If any of the provided stickers is a {@link GuildSticker},
* which is either {@link GuildSticker#isAvailable() unavailable} or from a different guild.
* - If the list is empty or has more than 3 stickers
* - If null is provided
*
*
* @return {@link MessageCreateAction}
*
* @see Sticker#fromId(long)
*/
@Nonnull
@CheckReturnValue
default MessageCreateAction sendStickers(@Nonnull StickerSnowflake... stickers)
{
Checks.notEmpty(stickers, "Stickers");
return sendStickers(Arrays.asList(stickers));
}
}