Package net.dv8tion.jda.api.entities.channel.middleman

Interface MessageChannel

All Superinterfaces:

Channel, Formattable, IDetachableEntity, IMentionable, ISnowflake

All Known Subinterfaces:

GroupChannel, GuildMessageChannel, GuildMessageChannelUnion, MessageChannelUnion, NewsChannel, PrivateChannel, StageChannel, StandardGuildMessageChannel, TextChannel, ThreadChannel, VoiceChannel

public interface MessageChannel
extends Channel, Formattable

Represents a Discord channel that can have Messages and files sent to it.

Formattable
This interface extends Formattable and can be used with a Formatter such as used by String.format(String, Object...) or PrintStream.printf(String, Object...).

This will use Channel.getName() rather than Object.toString()!
Supported Features:

• Alternative
  - Prepends the name with # (Example: %#s - results in #Channel.getName())
• Width/Left-Justification
  - Ensures the size of a format (Example: %20s - uses at minimum 20 chars; %-10s - uses left-justified padding)
• Precision
  - Cuts the content to the specified size (Example: %.20s)

More information on formatting syntax can be found in the format syntax documentation!
GuildMessageChannel is a special case which uses IMentionable.getAsMention() by default and uses the #Channel.getName() format as alternative

See Also:

• TextChannel
• PrivateChannel

Field Summary

Fields inherited from interface net.dv8tion.jda.api.entities.channel.Channel

MAX_NAME_LENGTH

Method Summary

Modifier and Type	Method	Description
default RestAction<Void>	addReactionById(long messageId, Emoji emoji)	Attempts to react to a message represented by the specified messageId in this MessageChannel.
default RestAction<Void>	addReactionById(String messageId, Emoji emoji)	Attempts to react to a message represented by the specified messageId in this MessageChannel.
boolean	canTalk()	Whether the currently logged in user can send messages in this channel or not.
default AuditableRestAction<Void>	deleteMessageById(long messageId)	Attempts to delete a Message from the Discord servers that has the same id as the id provided.
default AuditableRestAction<Void>	deleteMessageById(String messageId)	Attempts to delete a Message from the Discord servers that has the same id as the id provided.
default MessageEditAction	editMessageAttachmentsById(long messageId, Collection<? extends AttachedFile> attachments)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageAttachmentsById(long messageId, AttachedFile... attachments)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageAttachmentsById(String messageId, Collection<? extends AttachedFile> attachments)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageAttachmentsById(String messageId, AttachedFile... attachments)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageById(long messageId, CharSequence newContent)	Attempts to edit a message by its id in this channel.
default MessageEditAction	editMessageById(long messageId, MessageEditData data)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageById(String messageId, CharSequence newContent)	Attempts to edit a message by its id in this channel.
default MessageEditAction	editMessageById(String messageId, MessageEditData data)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(long messageId, Collection<? extends MessageTopLevelComponent> components)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(long messageId, MessageTopLevelComponent... components)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(long messageId, ComponentTree<? extends MessageTopLevelComponent> tree)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(String messageId, Collection<? extends MessageTopLevelComponent> components)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(String messageId, MessageTopLevelComponent... components)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageComponentsById(String messageId, ComponentTree<? extends MessageTopLevelComponent> tree)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageEmbedsById(long messageId, Collection<? extends MessageEmbed> newEmbeds)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageEmbedsById(long messageId, MessageEmbed... newEmbeds)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageEmbedsById(String messageId, Collection<? extends MessageEmbed> newEmbeds)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageEmbedsById(String messageId, MessageEmbed... newEmbeds)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageFormatById(long messageId, String format, Object... args)	Attempts to edit a message by its id in this MessageChannel.
default MessageEditAction	editMessageFormatById(String messageId, String format, Object... args)	Attempts to edit a message by its id in this MessageChannel.
default AuditableRestAction<Message>	endPollById(long messageId)	End the poll attached to this message.
default AuditableRestAction<Message>	endPollById(String messageId)	End the poll attached to this message.
default MessageHistory	getHistory()	Creates a new MessageHistory object for each call of this method.
default MessageHistory.MessageRetrieveAction	getHistoryAfter(long messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages sent after the marker ID.
default MessageHistory.MessageRetrieveAction	getHistoryAfter(String messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages sent after the marker ID.
default MessageHistory.MessageRetrieveAction	getHistoryAfter(Message message, int limit)	Uses the provided message as a marker and retrieves messages sent after the marker.
default MessageHistory.MessageRetrieveAction	getHistoryAround(long messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages around the marker.
default MessageHistory.MessageRetrieveAction	getHistoryAround(String messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages sent around the marker.
default MessageHistory.MessageRetrieveAction	getHistoryAround(Message message, int limit)	Uses the provided Message as a marker and retrieves messages around the marker.
default MessageHistory.MessageRetrieveAction	getHistoryBefore(long messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages sent before the marker ID.
default MessageHistory.MessageRetrieveAction	getHistoryBefore(String messageId, int limit)	Uses the provided id of a message as a marker and retrieves messages sent before the marker ID.
default MessageHistory.MessageRetrieveAction	getHistoryBefore(Message message, int limit)	Uses the provided message as a marker and retrieves messages sent before the marker.
default MessageHistory.MessageRetrieveAction	getHistoryFromBeginning(int limit)	Retrieves messages from the beginning of this MessageChannel.
default MessagePaginationAction	getIterableHistory()	A PaginationAction implementation that allows to iterate over recent Messages of this MessageChannel.
default String	getLatestMessageId()	The id for the most recent message sent in this current MessageChannel.
long	getLatestMessageIdLong()	The id for the most recent message sent in this current MessageChannel.
default AuditableRestAction<Void>	pinMessageById(long messageId)	Used to pin a message.
default AuditableRestAction<Void>	pinMessageById(String messageId)	Used to pin a message.
default List<CompletableFuture<Void>>	purgeMessages(List<? extends Message> messages)	Convenience method to delete messages in the most efficient way available.
default List<CompletableFuture<Void>>	purgeMessages(Message... messages)	Convenience method to delete messages in the most efficient way available.
default List<CompletableFuture<Void>>	purgeMessagesById(long... messageIds)	Convenience method to delete messages in the most efficient way available.
default List<CompletableFuture<Void>>	purgeMessagesById(String... messageIds)	Convenience method to delete messages in the most efficient way available.
default List<CompletableFuture<Void>>	purgeMessagesById(List<String> messageIds)	Convenience method to delete messages in the most efficient way available.
default RestAction<Void>	removeReactionById(long messageId, Emoji emoji)	Attempts to remove the reaction from a message represented by the specified messageId in this MessageChannel.
default RestAction<Void>	removeReactionById(String messageId, Emoji emoji)	Attempts to remove the reaction from a message represented by the specified messageId in this MessageChannel.
default RestAction<Message>	retrieveMessageById(long messageId)	Attempts to get a Message from the Discord's servers that has the same id as the id provided.
default RestAction<Message>	retrieveMessageById(String messageId)	Attempts to get a Message from the Discord's servers that has the same id as the id provided.
default PinnedMessagePaginationAction	retrievePinnedMessages()	Retrieves a List of Messages that have been pinned in this channel.
default PollVotersPaginationAction	retrievePollVotersById(long messageId, long answerId)	Paginate the users who voted for a poll answer.
default PollVotersPaginationAction	retrievePollVotersById(String messageId, long answerId)	Paginate the users who voted for a poll answer.
default ReactionPaginationAction	retrieveReactionUsersById(long messageId, Emoji emoji)	This obtains the users who reacted to a message using the given Emoji.
default ReactionPaginationAction	retrieveReactionUsersById(long messageId, Emoji emoji, MessageReaction.ReactionType type)	This obtains the users who reacted to a message using the given Emoji.
default ReactionPaginationAction	retrieveReactionUsersById(String messageId, Emoji emoji)	This obtains the users who reacted to a message using the given Emoji.
default ReactionPaginationAction	retrieveReactionUsersById(String messageId, Emoji emoji, MessageReaction.ReactionType type)	This obtains the users who reacted to a message using the given Emoji.
default MessageCreateAction	sendFiles(Collection<? extends FileUpload> files)	Send a message to this channel.
default MessageCreateAction	sendFiles(FileUpload... files)	Send a message to this channel.
default MessageCreateAction	sendMessage(CharSequence text)	Send a message to this channel.
default MessageCreateAction	sendMessage(MessageCreateData msg)	Send a message to this channel.
default MessageCreateAction	sendMessageComponents(Collection<? extends MessageTopLevelComponent> components)	Send a message to this channel.
default MessageCreateAction	sendMessageComponents(MessageTopLevelComponent component, MessageTopLevelComponent... other)	Send a message to this channel.
default MessageCreateAction	sendMessageComponents(ComponentTree<? extends MessageTopLevelComponent> tree)	Send a message to this channel.
default MessageCreateAction	sendMessageEmbeds(Collection<? extends MessageEmbed> embeds)	Send a message to this channel.
default MessageCreateAction	sendMessageEmbeds(MessageEmbed embed, MessageEmbed... other)	Send a message to this channel.
default MessageCreateAction	sendMessageFormat(String format, Object... args)	Send a message to this channel.
default MessageCreateAction	sendMessagePoll(MessagePollData poll)	Send a message to this channel.
default RestAction<Void>	sendTyping()	Sends the typing status to discord.
default AuditableRestAction<Void>	unpinMessageById(long messageId)	Used to unpin a message.
default AuditableRestAction<Void>	unpinMessageById(String messageId)	Used to unpin a message.

Methods inherited from interface net.dv8tion.jda.api.entities.channel.Channel

delete, formatTo, getAsMention, getFlags, getJDA, getName, getType

Methods inherited from interface net.dv8tion.jda.api.entities.detached.IDetachableEntity

isDetached

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

getId, getIdLong, getTimeCreated

Method Details

getLatestMessageId

@Nonnull
default String getLatestMessageId()

The id for the most recent message sent in this current MessageChannel.

This value is updated on each MessageReceivedEvent and the value might point to an already deleted message since the ID is not cleared when the message is deleted, so calling retrieveMessageById(long) with this id can result in an UNKNOWN_MESSAGE error

Returns:

The most recent message's id or "0" if no messages are present

getLatestMessageIdLong

long getLatestMessageIdLong()

The id for the most recent message sent in this current MessageChannel.

This value is updated on each MessageReceivedEvent and the value might point to an already deleted message since the value is not cleared when the message is deleted, so calling retrieveMessageById(long) with this id can result in an UNKNOWN_MESSAGE error

Returns:

The most recent message's id or 0 if no messages are present

canTalk

boolean canTalk()

Whether the currently logged in user can send messages in this channel or not.
For GuildMessageChannel this method checks for both Permission.VIEW_CHANNEL and Permission.MESSAGE_SEND.
For ThreadChannel this method checks for Permission.MESSAGE_SEND_IN_THREADS instead of Permission.MESSAGE_SEND.
For PrivateChannel this method checks if the user that this PrivateChannel communicates with is not a bot, but it does not check if the said user blocked the currently logged in user or have their DMs disabled.
For GroupChannel this method returns false.

Returns:

True, if we are able to read and send messages in this channel

Throws:

DetachedEntityException - If this entity is detached

purgeMessagesById

@Nonnull
default List<CompletableFuture<Void>> purgeMessagesById(@Nonnull
 List<String> messageIds)

Convenience method to delete messages in the most efficient way available.
This combines both GuildMessageChannel.deleteMessagesByIds(Collection) as well as deleteMessageById(long) to delete all messages provided. No checks will be done to prevent failures, use CompletionStage.exceptionally(Function) to handle failures.

For possible ErrorResponses see purgeMessagesById(long...).

Parameters:

messageIds - The message ids to delete

Returns:

List of futures representing all deletion tasks

Throws:

DetachedEntityException - If this entity is detached

See Also:

• CompletableFuture.allOf(java.util.concurrent.CompletableFuture[])

purgeMessagesById

@Nonnull
default List<CompletableFuture<Void>> purgeMessagesById(@Nonnull
 String... messageIds)

Convenience method to delete messages in the most efficient way available.
This combines both GuildMessageChannel.deleteMessagesByIds(Collection) as well as deleteMessageById(long) to delete all messages provided. No checks will be done to prevent failures, use CompletionStage.exceptionally(Function) to handle failures.

For possible ErrorResponses see purgeMessagesById(long...).

Parameters:

messageIds - The message ids to delete

Returns:

List of futures representing all deletion tasks

Throws:

DetachedEntityException - If this entity is detached

See Also:

• CompletableFuture.allOf(java.util.concurrent.CompletableFuture[])

purgeMessages

@Nonnull
default List<CompletableFuture<Void>> purgeMessages(@Nonnull
 Message... messages)

Convenience method to delete messages in the most efficient way available.
This combines both GuildMessageChannel.deleteMessagesByIds(Collection) as well as Message.delete() to delete all messages provided. No checks will be done to prevent failures, use CompletionStage.exceptionally(Function) to handle failures.

For possible ErrorResponses see purgeMessagesById(long...).

Parameters:

messages - The messages to delete

Returns:

List of futures representing all deletion tasks

Throws:

InsufficientPermissionException - If one of the provided messages is from another user and cannot be deleted due to permissions

IllegalArgumentException - If one of the provided messages is from another user and cannot be deleted because this is not in a guild

DetachedEntityException - If this entity is detached

See Also:

• CompletableFuture.allOf(java.util.concurrent.CompletableFuture[])

purgeMessages

@Nonnull
default List<CompletableFuture<Void>> purgeMessages(@Nonnull
 List<? extends Message> messages)

Convenience method to delete messages in the most efficient way available.
This combines both GuildMessageChannel.deleteMessagesByIds(Collection) as well as Message.delete() to delete all messages provided. No checks will be done to prevent failures, use CompletionStage.exceptionally(Function) to handle failures.

Any messages that cannot be deleted, as suggested by MessageType.canDelete(), will be filtered out before making any requests.

For possible ErrorResponses see purgeMessagesById(long...).

Parameters:

messages - The messages to delete

Returns:

List of futures representing all deletion tasks

Throws:

InsufficientPermissionException - If one of the provided messages is from another user and cannot be deleted due to permissions

IllegalArgumentException - If one of the provided messages is from another user and cannot be deleted because this is not in a guild

DetachedEntityException - If this entity is detached

See Also:

• CompletableFuture.allOf(java.util.concurrent.CompletableFuture[])

purgeMessagesById

@Nonnull
default List<CompletableFuture<Void>> purgeMessagesById(@Nonnull
 long... messageIds)

Convenience method to delete messages in the most efficient way available.
This combines both GuildMessageChannel.deleteMessagesByIds(Collection) as well as deleteMessageById(long) to delete all messages provided. No checks will be done to prevent failures, use CompletionStage.exceptionally(Function) to handle failures.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• UNKNOWN_MESSAGE
  if any of the provided messages does not exist
• MISSING_ACCESS
  if we were removed from the channel
• MISSING_PERMISSIONS
  The send request was attempted after the account lost Permission.MESSAGE_MANAGE in the channel.

Parameters:

messageIds - The message ids to delete

Returns:

List of futures representing all deletion tasks

Throws:

DetachedEntityException - If this entity is detached

See Also:

• CompletableFuture.allOf(java.util.concurrent.CompletableFuture[])

sendMessage

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessage(@Nonnull
 CharSequence text)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

text - The message content

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If the content is null or longer than 2000 characters

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

sendMessage

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessage(@Nonnull
 MessageCreateData msg)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

msg - The MessageCreateData to send

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If null is provided

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• MessageCreateBuilder

sendMessageFormat

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageFormat(@Nonnull
 String format,
 @Nonnull
 Object... args)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

format - Format string for the message content

args - Format arguments for the content

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If the format string is null or the resulting content is longer than 2000 characters

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.

DetachedEntityException - If this entity is detached

sendMessageEmbeds

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageEmbeds(@Nonnull
 MessageEmbed embed,
 @Nonnull
 MessageEmbed... other)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Example: Attachment Images

 // Make a file upload instance which refers to a local file called "myFile.png"
 // The second parameter "image.png" is the filename we tell discord to use for the attachment
 FileUpload file = FileUpload.fromData(new File("myFile.png"), "image.png");

 // Build a message embed which refers to this attachment by the given name.
 // Note that this must be the same name as configured for the attachment, not your local filename.
 MessageEmbed embed = new EmbedBuilder()
   .setDescription("This is my cute cat :)")
   .setImage("attachment://image.png") // refer to the file by using the "attachment://" schema with the filename we gave it above
   .build();

 channel.sendMessageEmbeds(embed) // send the embed
        .addFiles(file) // add the file as attachment
        .queue();
 

Parameters:

embed - MessageEmbed to send

other - Additional MessageEmbeds to use (up to 10)

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If any of the embeds are null, more than 10, or longer than MessageEmbed.EMBED_MAX_LENGTH_BOT.

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

sendMessageEmbeds

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageEmbeds(@Nonnull
 Collection<? extends MessageEmbed> embeds)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Example: Attachment Images

 // Make a file upload instance which refers to a local file called "myFile.png"
 // The second parameter "image.png" is the filename we tell discord to use for the attachment
 FileUpload file = FileUpload.fromData(new File("myFile.png"), "image.png");

 // Build a message embed which refers to this attachment by the given name.
 // Note that this must be the same name as configured for the attachment, not your local filename.
 MessageEmbed embed = new EmbedBuilder()
   .setDescription("This is my cute cat :)")
   .setImage("attachment://image.png") // refer to the file by using the "attachment://" schema with the filename we gave it above
   .build();

 channel.sendMessageEmbeds(Collections.singleton(embed)) // send the embeds
        .addFiles(file) // add the file as attachment
        .queue();
 

Parameters:

embeds - MessageEmbeds to use (up to 10)

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If any of the embeds are null, more than 10, or longer than MessageEmbed.EMBED_MAX_LENGTH_BOT.

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

sendMessageComponents

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageComponents(@Nonnull
 Collection<? extends MessageTopLevelComponent> components)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

components - The MessageTopLevelComponents to send, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

sendMessageComponents

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageComponents(@Nonnull
 MessageTopLevelComponent component,
 @Nonnull
 MessageTopLevelComponent... other)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

component - The MessageTopLevelComponent to send

other - Additional MessageTopLevelComponents to send, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

sendMessageComponents

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessageComponents(@Nonnull
 ComponentTree<? extends MessageTopLevelComponent> tree)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

tree - The ComponentTree to send, containing up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• MessageComponentTree

sendMessagePoll

@Nonnull
@CheckReturnValue
default MessageCreateAction sendMessagePoll(@Nonnull
 MessagePollData poll)

Send a message to this channel.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter
• POLL_INVALID_CHANNEL_TYPE
  This channel does not allow polls
• POLL_WITH_UNUSABLE_EMOJI
  This poll uses an external emoji that the bot is not allowed to use

Parameters:

poll - The poll to send

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If the poll is null

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

sendFiles

@Nonnull
@CheckReturnValue
default MessageCreateAction sendFiles(@Nonnull
 Collection<? extends FileUpload> files)

Send a message to this channel.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter
• REQUEST_ENTITY_TOO_LARGE
  If the total sum of uploaded bytes exceeds the guild's upload limit

Example: Attachment Images

 // Make a file upload instance which refers to a local file called "myFile.png"
 // The second parameter "image.png" is the filename we tell discord to use for the attachment
 FileUpload file = FileUpload.fromData(new File("myFile.png"), "image.png");

 // Build a message embed which refers to this attachment by the given name.
 // Note that this must be the same name as configured for the attachment, not your local filename.
 MessageEmbed embed = new EmbedBuilder()
   .setDescription("This is my cute cat :)")
   .setImage("attachment://image.png") // refer to the file by using the "attachment://" schema with the filename we gave it above
   .build();

 channel.sendFiles(Collections.singleton(file)) // send the file upload
        .addEmbeds(embed) // add the embed you want to reference the file with
        .queue();
 

Parameters:

files - The FileUploads to attach to the message

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If null is provided

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• FileUpload.fromData(InputStream, String)

sendFiles

@Nonnull
@CheckReturnValue
default MessageCreateAction sendFiles(@Nonnull
 FileUpload... files)

Send a message to this channel.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Possible ErrorResponses include:

• UNKNOWN_CHANNEL
  if this channel was deleted
• CANNOT_SEND_TO_USER
  If this is a PrivateChannel and the currently logged in account does not share any Guilds with the recipient User
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter
• REQUEST_ENTITY_TOO_LARGE
  If the total sum of uploaded bytes exceeds the guild's upload limit

Example: Attachment Images

 // Make a file upload instance which refers to a local file called "myFile.png"
 // The second parameter "image.png" is the filename we tell discord to use for the attachment
 FileUpload file = FileUpload.fromData(new File("myFile.png"), "image.png");

 // Build a message embed which refers to this attachment by the given name.
 // Note that this must be the same name as configured for the attachment, not your local filename.
 MessageEmbed embed = new EmbedBuilder()
   .setDescription("This is my cute cat :)")
   .setImage("attachment://image.png") // refer to the file by using the "attachment://" schema with the filename we gave it above
   .build();

 channel.sendFiles(file) // send the file upload
        .addEmbeds(embed) // add the embed you want to reference the file with
        .queue();
 

Parameters:

files - The FileUploads to attach to the message

Returns:

MessageCreateAction

Throws:

UnsupportedOperationException - If this is a PrivateChannel and the recipient is a bot

IllegalArgumentException - If null is provided

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• FileUpload.fromData(InputStream, String)

retrieveMessageById

@Nonnull
@CheckReturnValue
default RestAction<Message> retrieveMessageById(@Nonnull
 String messageId)

Attempts to get a Message from the Discord's servers that has the same id as the id provided.
Note: when retrieving a Message, you must retrieve it from the channel it was sent in!

The Message.getMember() method will always return null for the resulting message. To retrieve the member you can use getGuild().retrieveMember(message.getAuthor()).

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided id does not refer to a message sent in this channel or the message has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the sought after Message

Returns:

RestAction - Type: Message
The Message defined by the provided id.

Throws:

IllegalArgumentException - if the provided messageId is null or empty.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

retrieveMessageById

@Nonnull
@CheckReturnValue
default RestAction<Message> retrieveMessageById(long messageId)

Attempts to get a Message from the Discord's servers that has the same id as the id provided.
Note: when retrieving a Message, you must retrieve it from the channel it was sent in!

The Message.getMember() method will always return null for the resulting message. To retrieve the member you can use getGuild().retrieveMember(message.getAuthor()).

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided id does not refer to a message sent in this channel or the message has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the sought after Message

Returns:

RestAction - Type: Message
The Message defined by the provided id.

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

deleteMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> deleteMessageById(@Nonnull
 String messageId)

Attempts to delete a Message from the Discord servers that has the same id as the id provided.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request attempted to delete a Message in a GuildMessageChannel that was not sent by the currently logged in account.
• INVALID_DM_ACTION
  Attempted to delete a Message in a PrivateChannel that was not sent by the currently logged in account.
• UNKNOWN_MESSAGE
  The provided id does not refer to a message sent in this channel or the message has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the Message that should be deleted

Returns:

RestAction - Type: Void

Throws:

IllegalArgumentException - if the provided messageId is null

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.VIEW_CHANNEL.

DetachedEntityException - If this entity is detached

deleteMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> deleteMessageById(long messageId)

Attempts to delete a Message from the Discord servers that has the same id as the id provided.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request attempted to delete a Message in a GuildMessageChannel that was not sent by the currently logged in account.
• INVALID_DM_ACTION
  Attempted to delete a Message in a PrivateChannel that was not sent by the currently logged in account.
• UNKNOWN_MESSAGE
  The provided id does not refer to a message sent in this channel or the message has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the Message that should be deleted

Returns:

RestAction - Type: Void

Throws:

IllegalArgumentException - if the provided messageId is not positive

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.VIEW_CHANNEL.

DetachedEntityException - If this entity is detached

endPollById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Message> endPollById(@Nonnull
 String messageId)

End the poll attached to this message.

A bot cannot expire the polls of other users.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  If the poll was sent by another user
• CANNOT_EXPIRE_MISSING_POLL
  The message did not have a poll attached
• UNKNOWN_MESSAGE
  The message no longer exists

Parameters:

messageId - The ID for the poll message

Returns:

AuditableRestAction - Type: Message

Throws:

IllegalArgumentException - If the provided messageId is not a valid snowflake

endPollById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Message> endPollById(long messageId)

End the poll attached to this message.

A bot cannot expire the polls of other users.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  If the poll was sent by another user
• CANNOT_EXPIRE_MISSING_POLL
  The message did not have a poll attached
• UNKNOWN_MESSAGE
  The message no longer exists

Parameters:

messageId - The ID for the poll message

Returns:

AuditableRestAction - Type: Message

retrievePollVotersById

@Nonnull
@CheckReturnValue
default PollVotersPaginationAction retrievePollVotersById(@Nonnull
 String messageId,
 long answerId)

Paginate the users who voted for a poll answer.

Parameters:

messageId - The message id for the poll

answerId - The id of the poll answer, usually the ordinal position of the answer (first is 1)

Returns:

PollVotersPaginationAction

Throws:

IllegalArgumentException - If the message id is not a valid snowflake

retrievePollVotersById

@Nonnull
@CheckReturnValue
default PollVotersPaginationAction retrievePollVotersById(long messageId,
 long answerId)

Paginate the users who voted for a poll answer.

Parameters:

messageId - The message id for the poll

answerId - The id of the poll answer, usually the ordinal position of the answer (first is 1)

Returns:

PollVotersPaginationAction

getHistory

@Nonnull
default MessageHistory getHistory()

Creates a new MessageHistory object for each call of this method.
MessageHistory is NOT an internal message cache, but rather it queries the Discord servers for previously sent messages.

Returns:

A MessageHistory related to this channel.

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the currently logged in account does not have the permission MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

getIterableHistory

@Nonnull
@CheckReturnValue
default MessagePaginationAction getIterableHistory()

A PaginationAction implementation that allows to iterate over recent Messages of this MessageChannel.
This is not a cache for received messages and it can only view messages that were sent before. This iterates chronologically backwards (from present to past).

It is recommended not to use this in an enhanced for-loop without end conditions as it might cause memory overflows in channels with a long message history.

Examples

 public CompletableFuture<List<Message>> getMessagesByUser(MessageChannel channel, User user) {
     return channel.getIterableHistory()
         .takeAsync(1000) // Collect 1000 messages
         .thenApply(list ->
             list.stream()
                 .filter(m -> m.getAuthor().equals(user)) // Filter messages by author
                 .collect(Collectors.toList())
         );
 }
 

Returns:

MessagePaginationAction

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the currently logged in account does not have the permission MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

getHistoryAround

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAround(@Nonnull
 String messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages sent around the marker. The limit determines the amount of messages retrieved near the marker. Discord will attempt to evenly split the limit between before and after the marker, however in the case that the marker is set near the beginning or near the end of the channel's history the amount of messages on each side of the marker may be different, and their total count may not equal the provided limit.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAround(messageId, 100) - This will retrieve 100 messages from history, 50 before the marker and 50 after the marker.

Retrieve 10 messages near the end of history. Provided id is for a message that is the 3rd most recent message.
getHistoryAround(messageId, 10) - This will retrieve 10 messages from history, 8 before the marker and 2 after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker.

limit - The amount of messages to be retrieved around the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages around the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided messageId is null or empty.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAround(MessageChannel, String)

getHistoryAround

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAround(long messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages around the marker. The limit determines the amount of messages retrieved near the marker. Discord will attempt to evenly split the limit between before and after the marker, however in the case that the marker is set near the beginning or near the end of the channel's history the amount of messages on each side of the marker may be different, and their total count may not equal the provided limit.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAround(messageId, 100) - This will retrieve 100 messages from history, 50 before the marker and 50 after the marker.

Retrieve 10 messages near the end of history. Provided id is for a message that is the 3rd most recent message.
getHistoryAround(messageId, 10) - This will retrieve 10 messages from history, 8 before the marker and 2 after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker. The id must refer to a message from this MessageChannel.

limit - The amount of messages to be retrieved around the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages around the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided messageId is not positive.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAround(MessageChannel, String)

getHistoryAround

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAround(@Nonnull
 Message message,
 int limit)

Uses the provided Message as a marker and retrieves messages around the marker. The limit determines the amount of messages retrieved near the marker. Discord will attempt to evenly split the limit between before and after the marker, however in the case that the marker is set near the beginning or near the end of the channel's history the amount of messages on each side of the marker may be different, and their total count may not equal the provided limit.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAround(message, 100) - This will retrieve 100 messages from history, 50 before the marker and 50 after the marker.

Retrieve 10 messages near the end of history. Provided message is the 3rd most recent message.
getHistoryAround(message, 10) - This will retrieve 10 messages from history, 8 before the marker and 2 after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided message has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

message - The Message that will act as a marker. The provided Message must be from this MessageChannel.

limit - The amount of messages to be retrieved around the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages around the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided message is null.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAround(MessageChannel, String)

getHistoryAfter

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAfter(@Nonnull
 String messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages sent after the marker ID. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAfter(messageId, 100) - This will retrieve 100 messages from history sent after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages after the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided messageId is null or empty.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAfter(MessageChannel, String)

getHistoryAfter

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAfter(long messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages sent after the marker ID. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAfter(messageId, 100) - This will retrieve 100 messages from history sent after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages after the provided message loaded into it.

Throws:

IllegalArgumentException - Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAfter(MessageChannel, String)

getHistoryAfter

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryAfter(@Nonnull
 Message message,
 int limit)

Uses the provided message as a marker and retrieves messages sent after the marker. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAfter(message, 100) - This will retrieve 100 messages from history sent after the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

message - The message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages after the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided message is null.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryAfter(MessageChannel, String)

getHistoryBefore

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryBefore(@Nonnull
 String messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages sent before the marker ID. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryBefore(messageId, 100) - This will retrieve 100 messages from history sent before the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages before the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided messageId is null or empty.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryBefore(MessageChannel, String)

getHistoryBefore

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryBefore(long messageId,
 int limit)

Uses the provided id of a message as a marker and retrieves messages sent before the marker ID. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryBefore(messageId, 100) - This will retrieve 100 messages from history sent before the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The id of the message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages before the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided messageId is null or empty.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryBefore(MessageChannel, String)

getHistoryBefore

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryBefore(@Nonnull
 Message message,
 int limit)

Uses the provided message as a marker and retrieves messages sent before the marker. The limit determines the amount of messages retrieved near the marker.

Examples:
Retrieve 100 messages from the middle of history. >100 message exist in history and the marker is >50 messages from the edge of history.
getHistoryAfter(message, 100) - This will retrieve 100 messages from history sent before the marker.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted, thus could not be used as a marker.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

message - The message that will act as a marker.

limit - The amount of messages to be retrieved after the marker. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with messages before the provided message loaded into it.

Throws:

IllegalArgumentException -

• Provided message is null.
• Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.getHistoryBefore(MessageChannel, String)

getHistoryFromBeginning

@Nonnull
@CheckReturnValue
default MessageHistory.MessageRetrieveAction getHistoryFromBeginning(int limit)

Retrieves messages from the beginning of this MessageChannel. The limit determines the amount of messages being retrieved.

Example

 public void resendFirstMessage(MessageChannel channel)
 {
     channel.getHistoryFromBeginning(1).queue(history ->
     {
         if (!history.isEmpty())
         {
             Message firstMsg = history.getRetrievedHistory().get(0);
             channel.sendMessage(firstMsg).queue();
         }
         else
             channel.sendMessage("No history for this channel!").queue();
     });
 }
 

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_HISTORY in the GuildMessageChannel.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

limit - The amount of messages to be retrieved. Minimum: 1, Max: 100.

Returns:

MessageHistory.MessageRetrieveAction
Provides a MessageHistory object with the first messages of this channel loaded into it.
Note: The messages are ordered from the most recent to oldest!

Throws:

IllegalArgumentException - Provided limit is less than 1 or greater than 100.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

See Also:

• MessageHistory.retrieveFuture(int)
• MessageHistory.getHistoryAfter(MessageChannel, String)

sendTyping

@Nonnull
@CheckReturnValue
default RestAction<Void> sendTyping()

Sends the typing status to discord. This is what is used to make the message "X is typing..." appear.
The typing status only lasts for 10 seconds or until a message is sent.
So if you wish to show continuous typing you will need to call this method once every 10 seconds.

The official discord client sends this every 5 seconds even though the typing status lasts 10.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND was revoked in the GuildMessageChannel
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Returns:

RestAction - Type: Void

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

addReactionById

@Nonnull
@CheckReturnValue
default RestAction<Void> addReactionById(@Nonnull
 String messageId,
 @Nonnull
 Emoji emoji)

Attempts to react to a message represented by the specified messageId in this MessageChannel.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_ADD_REACTION in the GuildMessageChannel.
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The messageId to attach the reaction to

emoji - The not-null Emoji to react with

Returns:

RestAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided emoji is null.

InsufficientPermissionException - If the MessageChannel this message was sent in was a GuildMessageChannel and the logged in account does not have

• Permission.MESSAGE_ADD_REACTION
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

addReactionById

@Nonnull
@CheckReturnValue
default RestAction<Void> addReactionById(long messageId,
 @Nonnull
 Emoji emoji)

Attempts to react to a message represented by the specified messageId in this MessageChannel.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_ADD_REACTION in the GuildMessageChannel.
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The messageId to attach the reaction to

emoji - The Emoji to react with

Returns:

RestAction

Throws:

IllegalArgumentException -

• If provided messageId is not a valid snowflake.
• If provided emoji is null

InsufficientPermissionException - If the MessageChannel this message was sent in was a GuildMessageChannel and the logged in account does not have

• Permission.MESSAGE_ADD_REACTION
• Permission.MESSAGE_HISTORY

DetachedEntityException - If this entity is detached

removeReactionById

@Nonnull
@CheckReturnValue
default RestAction<Void> removeReactionById(@Nonnull
 String messageId,
 @Nonnull
 Emoji emoji)

Attempts to remove the reaction from a message represented by the specified messageId in this MessageChannel.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_ADD_REACTION in the GuildMessageChannel.
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The messageId to remove the reaction from

emoji - The emoji to remove

Returns:

RestAction

Throws:

IllegalArgumentException -

• If provided messageId is null or not a valid snowflake.
• If provided emoji is null.

DetachedEntityException - If this entity is detached

removeReactionById

@Nonnull
@CheckReturnValue
default RestAction<Void> removeReactionById(long messageId,
 @Nonnull
 Emoji emoji)

Attempts to remove the reaction from a message represented by the specified messageId in this MessageChannel.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.MESSAGE_ADD_REACTION in the GuildMessageChannel.
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The messageId to remove the reaction from

emoji - The emoji to remove

Returns:

RestAction

Throws:

IllegalArgumentException -

• If provided messageId is not a valid snowflake.
• If provided emoji is null.

DetachedEntityException - If this entity is detached

retrieveReactionUsersById

@Nonnull
@CheckReturnValue
default ReactionPaginationAction retrieveReactionUsersById(@Nonnull
 String messageId,
 @Nonnull
 Emoji emoji)

This obtains the users who reacted to a message using the given Emoji.
By default, this only includes users that reacted with MessageReaction.ReactionType.NORMAL. Use retrieveReactionUsersById(messageId, emoji, ReactionType.SUPER) to retrieve the users that used a super reaction instead.

Messages maintain a list of reactions, alongside a list of users who added them.

Using this data, we can obtain a ReactionPaginationAction of the users who've reacted to the given message.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The retrieve request was attempted after the account lost access to the GuildMessageChannel due to Permission.VIEW_CHANNEL being revoked
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.

Parameters:

messageId - The messageId to retrieve the users from.

emoji - The Emoji to retrieve users for.

Returns:

The ReactionPaginationAction of the emoji's users.

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.MESSAGE_HISTORY.

IllegalArgumentException -

• If provided messageId is null or not a valid snowflake.
• If provided emoji is null.

DetachedEntityException - If this entity is detached

retrieveReactionUsersById

@Nonnull
@CheckReturnValue
default ReactionPaginationAction retrieveReactionUsersById(long messageId,
 @Nonnull
 Emoji emoji)

This obtains the users who reacted to a message using the given Emoji.
By default, this only includes users that reacted with MessageReaction.ReactionType.NORMAL. Use retrieveReactionUsersById(messageId, emoji, ReactionType.SUPER) to retrieve the users that used a super reaction instead.

Messages maintain a list of reactions, alongside a list of users who added them.

Using this data, we can obtain a ReactionPaginationAction of the users who've reacted to the given message.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The retrieve request was attempted after the account lost access to the GuildMessageChannel due to Permission.VIEW_CHANNEL being revoked
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.

Parameters:

messageId - The messageId to retrieve the users from.

emoji - The Emoji to retrieve users for.

Returns:

The ReactionPaginationAction of the emoji's users.

Throws:

UnsupportedOperationException - If this is not a Received Message from MessageType.DEFAULT

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.MESSAGE_HISTORY.

IllegalArgumentException -

• If provided messageId is not a valid snowflake.
• If provided emoji is null.

DetachedEntityException - If this entity is detached

Since:

4.2.0

retrieveReactionUsersById

@Nonnull
@CheckReturnValue
default ReactionPaginationAction retrieveReactionUsersById(@Nonnull
 String messageId,
 @Nonnull
 Emoji emoji,
 @Nonnull
 MessageReaction.ReactionType type)

This obtains the users who reacted to a message using the given Emoji.

Messages maintain a list of reactions, alongside a list of users who added them.

Using this data, we can obtain a ReactionPaginationAction of the users who've reacted to the given message.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The retrieve request was attempted after the account lost access to the GuildMessageChannel due to Permission.VIEW_CHANNEL being revoked
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.

Parameters:

messageId - The messageId to retrieve the users from.

emoji - The Emoji to retrieve users for.

type - The specific type of reaction

Returns:

The ReactionPaginationAction of the emoji's users.

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.MESSAGE_HISTORY.

IllegalArgumentException -

• If provided messageId is null or not a valid snowflake.
• If provided emoji is null.
• If provided type is null.

retrieveReactionUsersById

@Nonnull
@CheckReturnValue
default ReactionPaginationAction retrieveReactionUsersById(long messageId,
 @Nonnull
 Emoji emoji,
 @Nonnull
 MessageReaction.ReactionType type)

This obtains the users who reacted to a message using the given Emoji.

Messages maintain a list of reactions, alongside a list of users who added them.

Using this data, we can obtain a ReactionPaginationAction of the users who've reacted to the given message.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The retrieve request was attempted after the account lost access to the GuildMessageChannel due to Permission.VIEW_CHANNEL being revoked
  Also can happen if the account lost the Permission.MESSAGE_HISTORY
• UNKNOWN_EMOJI
  The provided emoji was deleted, doesn't exist, or is not available to the currently logged-in account in this channel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.

Parameters:

messageId - The messageId to retrieve the users from.

emoji - The Emoji to retrieve users for.

type - The specific type of reaction

Returns:

The ReactionPaginationAction of the emoji's users.

Throws:

UnsupportedOperationException - If this is not a Received Message from MessageType.DEFAULT

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have Permission.MESSAGE_HISTORY.

IllegalArgumentException -

• If provided messageId is not a valid snowflake.
• If provided emoji is null.
• If provided type is null.

pinMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> pinMessageById(@Nonnull
 String messageId)

Used to pin a message. Pinned messages are retrievable via retrievePinnedMessages().

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.PIN_MESSAGES in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The message to pin.

Returns:

AuditableRestAction

Throws:

IllegalArgumentException - if the provided messageId is null or empty.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.PIN_MESSAGES

DetachedEntityException - If this entity is detached

pinMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> pinMessageById(long messageId)

Used to pin a message. Pinned messages are retrievable via retrievePinnedMessages().

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.PIN_MESSAGES in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The message to pin.

Returns:

AuditableRestAction

Throws:

IllegalArgumentException - if the provided messageId is not a valid snowflake.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.PIN_MESSAGES

DetachedEntityException - If this entity is detached

unpinMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> unpinMessageById(@Nonnull
 String messageId)

Used to unpin a message. Pinned messages are retrievable via retrievePinnedMessages().

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.PIN_MESSAGES in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The message to unpin.

Returns:

AuditableRestAction

Throws:

IllegalArgumentException - if the provided messageId is null or empty.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.PIN_MESSAGES

DetachedEntityException - If this entity is detached

unpinMessageById

@Nonnull
@CheckReturnValue
default AuditableRestAction<Void> unpinMessageById(long messageId)

Used to unpin a message. Pinned messages are retrievable via retrievePinnedMessages().

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• MISSING_PERMISSIONS
  The request was attempted after the account lost Permission.PIN_MESSAGES in the GuildMessageChannel.
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Parameters:

messageId - The message to unpin.

Returns:

AuditableRestAction

Throws:

IllegalArgumentException - if the provided messageId is not positive.

InsufficientPermissionException - If this is a GuildMessageChannel and the logged in account does not have

• Permission.VIEW_CHANNEL
• Permission.PIN_MESSAGES

DetachedEntityException - If this entity is detached

retrievePinnedMessages

@Nonnull
@CheckReturnValue
default PinnedMessagePaginationAction retrievePinnedMessages()

Retrieves a List of Messages that have been pinned in this channel.
If no messages have been pinned, this retrieves an empty List.

The following ErrorResponses are possible:

• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.

Returns:

PinnedMessagePaginationAction

Throws:

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

DetachedEntityException - If this entity is detached

editMessageById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageById(@Nonnull
 String messageId,
 @Nonnull
 CharSequence newContent)

Attempts to edit a message by its id in this channel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newContent - The new content for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided newContent is null or empty.
• If provided newContent length is greater than 2000 characters.

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

DetachedEntityException - If this entity is detached

editMessageById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageById(long messageId,
 @Nonnull
 CharSequence newContent)

Attempts to edit a message by its id in this channel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newContent - The new content for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided newContent is null or empty.
• If provided newContent length is greater than 2000 characters.

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

DetachedEntityException - If this entity is detached

editMessageById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageById(@Nonnull
 String messageId,
 @Nonnull
 MessageEditData data)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

data - The new content for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided newContent is null.
• If provided Message contains a MessageEmbed which is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

DetachedEntityException - If this entity is detached

editMessageById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageById(long messageId,
 @Nonnull
 MessageEditData data)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

data - The new content for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided newContent is null.
• If provided Message contains a MessageEmbed which is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

DetachedEntityException - If this entity is detached

editMessageFormatById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageFormatById(@Nonnull
 String messageId,
 @Nonnull
 String format,
 @Nonnull
 Object... args)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

format - Format String used to generate new Content

args - The arguments which should be used to format the given format String

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided format is null or blank.

IllegalStateException - If the resulting message is either empty or too long to be sent

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.

DetachedEntityException - If this entity is detached

editMessageFormatById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageFormatById(long messageId,
 @Nonnull
 String format,
 @Nonnull
 Object... args)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

format - Format String used to generate new Content

args - The arguments which should be used to format the given format String

Returns:

MessageEditAction

Throws:

IllegalArgumentException - If provided format is null or blank.

IllegalStateException - If the resulting message is either empty or too long to be sent

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL

IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.

DetachedEntityException - If this entity is detached

editMessageEmbedsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageEmbedsById(@Nonnull
 String messageId,
 @Nonnull
 MessageEmbed... newEmbeds)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newEmbeds - Up to 10 new MessageEmbeds for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided MessageEmbed is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageEmbedsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageEmbedsById(long messageId,
 @Nonnull
 MessageEmbed... newEmbeds)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newEmbeds - Up to 10 new MessageEmbeds for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided MessageEmbed is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageEmbedsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageEmbedsById(@Nonnull
 String messageId,
 @Nonnull
 Collection<? extends MessageEmbed> newEmbeds)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newEmbeds - Up to 10 new MessageEmbeds for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided MessageEmbed is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageEmbedsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageEmbedsById(long messageId,
 @Nonnull
 Collection<? extends MessageEmbed> newEmbeds)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

newEmbeds - Up to 10 new MessageEmbeds for the edited message

Returns:

MessageEditAction

Throws:

IllegalArgumentException -

• If provided messageId is null or empty.
• If provided MessageEmbed is not sendable

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(@Nonnull
 String messageId,
 @Nonnull
 Collection<? extends MessageTopLevelComponent> components)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 List<ActionRow> rows = Arrays.asList(
   ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
   ActionRow.of(Button.link(url, "Help")) // 2nd row below message
 );
 channel.editMessageComponentsById(messageId, rows).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

components - The MessageTopLevelComponents to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(long messageId,
 @Nonnull
 Collection<? extends MessageTopLevelComponent> components)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 List<ActionRow> rows = Arrays.asList(
   ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
   ActionRow.of(Button.link(url, "Help")) // 2nd row below message
 );
 channel.editMessageComponentsById(messageId, rows).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

components - The MessageTopLevelComponents to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(@Nonnull
 String messageId,
 @Nonnull
 MessageTopLevelComponent... components)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 channel.editMessageComponentsById(messageId,
   ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
   ActionRow.of(Button.link(url, "Help")) // 2nd row below message
 ).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

components - The MessageTopLevelComponents to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(long messageId,
 @Nonnull
 MessageTopLevelComponent... components)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 channel.editMessageComponentsById(messageId,
   ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
   ActionRow.of(Button.link(url, "Help")) // 2nd row below message
 ).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

components - The MessageTopLevelComponents to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(@Nonnull
 String messageId,
 @Nonnull
 ComponentTree<? extends MessageTopLevelComponent> tree)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 channel.editMessageComponentsById(messageId,
   MessageComponentTree.of(
     ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
     ActionRow.of(Button.link(url, "Help")) // 2nd row below message
   )
 ).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

tree - The ComponentTree to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• MessageComponentTree

editMessageComponentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageComponentsById(long messageId,
 @Nonnull
 ComponentTree<? extends MessageTopLevelComponent> tree)

Attempts to edit a message by its id in this MessageChannel.
This will replace all the current Components, such as Buttons or SelectMenus on this message. The provided parameters are MessageTopLevelComponents such as ActionRow which contain a list of components to arrange in the respective layout.

Example

 channel.editMessageComponentsById(messageId,
   MessageComponentTree.of(
     ActionRow.of(Button.success("prompt:accept", "Accept"), Button.danger("prompt:reject", "Reject")), // 1st row below message
     ActionRow.of(Button.link(url, "Help")) // 2nd row below message
   )
 ).queue();
 

The following ErrorResponses are possible:

• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Parameters:

messageId - The id referencing the Message that should be edited

tree - The ComponentTree to set, can be empty to remove components, can contain up to 5 V1 components. There are no limits for V2 components outside the total tree size (40).

Returns:

MessageEditAction

Throws:

UnsupportedOperationException - If the component layout is a custom implementation that is not supported by this interface

IllegalArgumentException -

• If null is provided
• If any of the provided components are not compatible with messages

InsufficientPermissionException - If this is a GuildMessageChannel and this account does not have Permission.VIEW_CHANNEL or Permission.MESSAGE_SEND

DetachedEntityException - If this entity is detached

See Also:

• MessageComponentTree

editMessageAttachmentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageAttachmentsById(@Nonnull
 String messageId,
 @Nonnull
 Collection<? extends AttachedFile> attachments)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

messageId - The message id. For interactions this supports "@original" to edit the source message of the interaction.

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

MessageEditAction that can be used to further update the message

Throws:

IllegalArgumentException - If null is provided

DetachedEntityException - If this entity is detached

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)

editMessageAttachmentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageAttachmentsById(@Nonnull
 String messageId,
 @Nonnull
 AttachedFile... attachments)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

messageId - The message id. For interactions this supports "@original" to edit the source message of the interaction.

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

MessageEditAction that can be used to further update the message

Throws:

IllegalArgumentException - If null is provided

DetachedEntityException - If this entity is detached

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)

editMessageAttachmentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageAttachmentsById(long messageId,
 @Nonnull
 Collection<? extends AttachedFile> attachments)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

messageId - The message id. For interactions this supports "@original" to edit the source message of the interaction.

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

MessageEditAction that can be used to further update the message

Throws:

IllegalArgumentException - If null is provided

DetachedEntityException - If this entity is detached

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)

editMessageAttachmentsById

@Nonnull
@CheckReturnValue
default MessageEditAction editMessageAttachmentsById(long messageId,
 @Nonnull
 AttachedFile... attachments)

Attempts to edit a message by its id in this MessageChannel.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• INVALID_AUTHOR_EDIT
  Attempted to edit a message that was not sent by the currently logged in account. Discord does not allow editing of other users' Messages!
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• INVALID_FORM_BODY
  Components V2 is used by the to-be-edited message, and this request has non-empty content or embeds.

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

messageId - The message id. For interactions this supports "@original" to edit the source message of the interaction.

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

MessageEditAction that can be used to further update the message

Throws:

IllegalArgumentException - If null is provided

DetachedEntityException - If this entity is detached

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)