Interface MessageRequest<R extends MessageRequest<R>>
- Type Parameters:
R
- Return type used for chaining method calls
- All Superinterfaces:
MessageData
- All Known Subinterfaces:
ForumPostAction
,MessageCreateAction
,MessageCreateRequest<R>
,MessageEditAction
,MessageEditCallbackAction
,MessageEditRequest<R>
,ReplyCallbackAction
,WebhookMessageCreateAction<T>
,WebhookMessageEditAction<T>
- All Known Implementing Classes:
AbstractMessageBuilder
,MessageCreateBuilder
,MessageEditBuilder
These setters can both be applied to
edit requests
and create requests
for messages in various parts of the API.- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionapplyMessage
(Message message) Applies all the data of the providedMessage
and attempts to copy it.static EnumSet
<Message.MentionType> Returns the defaultMentionTypes
previously set byAllowedMentions.setDefaultMentions(Collection)
.static boolean
Returns the default mention behavior for replies.static boolean
Whether V2 components are used by default, this isfalse
by default.mention
(Collection<? extends IMentionable> mentions) default R
mention
(IMentionable... mentions) mentionRepliedUser
(boolean mention) Whether to mention the user, when replying to a message.default R
mentionRoles
(long... roleIds) Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.default R
mentionRoles
(String... roleIds) Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.mentionRoles
(Collection<String> roleIds) Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.default R
mentionUsers
(long... userIds) Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.default R
mentionUsers
(String... userIds) Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.mentionUsers
(Collection<String> userIds) Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.setAllowedMentions
(Collection<Message.MentionType> allowedMentions) Sets theMentionTypes
that should be parsed.setComponents
(Collection<? extends MessageTopLevelComponent> components) TheMessageTopLevelComponents
that should be attached to the message.default R
setComponents
(MessageTopLevelComponent... components) TheMessageTopLevelComponents
that should be attached to the message.default R
setComponents
(ComponentTree<? extends MessageTopLevelComponent> tree) TheComponentTree
ofMessageTopLevelComponents
that should be attached to the message.setContent
(String content) The message content, which shows above embeds and attachments.static void
setDefaultMentionRepliedUser
(boolean mention) Sets the default value formentionRepliedUser(boolean)
static void
setDefaultMentions
(Collection<Message.MentionType> allowedMentions) Sets theMentionTypes
that should be parsed by default.static void
setDefaultUseComponentsV2
(boolean use) Sets whether V2 components will be used by default, this isfalse
by default.setEmbeds
(Collection<? extends MessageEmbed> embeds) TheMessageEmbeds
that should be attached to the message.default R
setEmbeds
(MessageEmbed... embeds) TheMessageEmbeds
that should be attached to the message.setFiles
(Collection<? extends FileUpload> files) TheFileUploads
that should be attached to the message.default R
setFiles
(FileUpload... files) TheFileUploads
that should be attached to the message.setSuppressEmbeds
(boolean suppress) Set whether embeds should be suppressed on this message.default R
Enables using V2 components, this is disabled by default.useComponentsV2
(boolean use) Sets whether this message is allowed to use V2 components, this is disabled by default.Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageData
getAllowedMentions, getAttachments, getComponents, getComponentTree, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, isMentionRepliedUser, isSuppressEmbeds, isUsingComponentsV2
-
Method Details
-
setDefaultMentions
Sets theMentionTypes
that should be parsed by default. This just sets the default for all RestActions and can be overridden on a per-action basis usingsetAllowedMentions(Collection)
.
If a message is sent with an empty Set of MentionTypes, then it will not ping any User, Role or@everyone
/@here
, while still showing up as mention tag.If
null
is provided to this method, then all Types will be pingable (unless whitelisting via one of themention*
methods is used).Example
// Disable EVERYONE and HERE mentions by default (to avoid mass ping) EnumSet<Message.MentionType> deny = EnumSet.of(Message.MentionType.EVERYONE, Message.MentionType.HERE); MessageRequest.setDefaultMentions(EnumSet.complementOf(deny));
- Parameters:
allowedMentions
- MentionTypes that are allowed to being parsed and pinged.null
to disable and allow all mentions.
-
getDefaultMentions
Returns the defaultMentionTypes
previously set byAllowedMentions.setDefaultMentions(Collection)
.- Returns:
- Default mentions set by AllowedMentions.setDefaultMentions(Collection)
-
setDefaultMentionRepliedUser
static void setDefaultMentionRepliedUser(boolean mention) Sets the default value formentionRepliedUser(boolean)
Default: true
- Parameters:
mention
- True, if replies should mention by default
-
setDefaultUseComponentsV2
static void setDefaultUseComponentsV2(boolean use) Sets whether V2 components will be used by default, this isfalse
by default.
When enabled,useComponentsV2()
gets called for every message builder.This can be overwritten with
useComponentsV2(boolean)
on each builder instance.- Parameters:
use
-true
to enable V2 components by default,false
to disabled them by default.
-
isDefaultUseComponentsV2
static boolean isDefaultUseComponentsV2()Whether V2 components are used by default, this isfalse
by default.
When enabled,useComponentsV2()
gets called for every message builder.This can be overwritten with
useComponentsV2(boolean)
on each builder instance.- Returns:
true
if every message will use Components V2 by default,false
if not
-
isDefaultMentionRepliedUser
static boolean isDefaultMentionRepliedUser()Returns the default mention behavior for replies.
If this istrue
then all replies will mention the author of the target message by default. You can specify this individually withmentionRepliedUser(boolean)
for each message.Default: true
- Returns:
- True, if replies mention by default
-
setContent
The message content, which shows above embeds and attachments.- Parameters:
content
- The content (up to 2000 characters)- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If the content is longer than 2000 characters
-
setEmbeds
TheMessageEmbeds
that should be attached to the message.
You can useCollections.emptyList()
to remove all embeds from the message.This requires
Permission.MESSAGE_EMBED_LINKS
in the channel.- Parameters:
embeds
- The embeds to attach to the message (up to 10)- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null or more than 10 embeds are provided- See Also:
-
setEmbeds
TheMessageEmbeds
that should be attached to the message.
You can usenew MessageEmbed[0]
to remove all embeds from the message.This requires
Permission.MESSAGE_EMBED_LINKS
in the channel.- Parameters:
embeds
- The embeds to attach to the message (up to 10)- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null or more than 10 embeds are provided
-
setComponents
TheMessageTopLevelComponents
that should be attached to the message.
You can useCollections.emptyList()
to remove all components from the message.Example: Set action rows
final List<MessageTopLevelComponent> list = new ArrayList<>(); list.add(ActionRow.of(selectMenu); // first row list.add(ActionRow.of(button1, button2)); // second row (shows below the first) channel.sendMessage("Content here") .setComponents(list) .queue();
Example: Remove action rows
channel.sendMessage("Content here") .setComponents(Collections.emptyList()) .queue();
- Parameters:
components
- TheMessageTopLevelComponents
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:
- The same instance for chaining
- Throws:
IllegalArgumentException
-- If
null
is provided - If any of the provided components are not compatible with messages
- If
-
setComponents
TheMessageTopLevelComponents
that should be attached to the message.
You can call this method without anything to remove all components from the message.Example: Set action rows
channel.sendMessage("Content here") .setComponents( ActionRow.of(selectMenu), // first row ActionRow.of(button1, button2)) // second row (shows below the first) .queue();
Example: Remove action rows
channel.sendMessage("Content here") .setComponents() .queue();
- Parameters:
components
- TheMessageTopLevelComponents
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:
- The same instance for chaining
- Throws:
IllegalArgumentException
-- If
null
is provided - If any of the provided components are not compatible with messages
- If
-
setComponents
TheComponentTree
ofMessageTopLevelComponents
that should be attached to the message.
You can call this method without anything to remove all components from the message.- Parameters:
tree
- The newComponentTree
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:
- The same instance for chaining
- Throws:
IllegalArgumentException
-- If
null
is provided - If any of the provided components are not compatible with messages
- If
- See Also:
-
useComponentsV2
Sets whether this message is allowed to use V2 components, this is disabled by default.Using V2 components removes the top-level component limit, and allows more components in total (40).
They also allow you to use a larger choice of components, such as any component extendingMessageTopLevelComponent
, as long as they are compatible.
The character limit for the messages also gets changed to 4000.This, however, comes with a few drawbacks:
- You cannot send content, embeds, polls or stickers
- It does not support voice messages
- It does not support previewing files
- URLs don't create embeds
- You cannot switch this message back to not using Components V2 (you can however upgrade a message to V2)
A default value can be set in
setDefaultUseComponentsV2(boolean)
.- Parameters:
use
-true
to enable V2 components,false
to disabled them.- Returns:
- The same instance for chaining
- See Also:
-
useComponentsV2
Enables using V2 components, this is disabled by default.
This is a shortcut foruseComponentV2(true)
Using V2 components removes the top-level component limit, and allows more components in total (40).
They also allow you to use a larger choice of components, such as any component extendingMessageTopLevelComponent
, as long as they are compatible.
The character limit for the messages also gets changed to 4000.This, however, comes with a few drawbacks:
- You cannot send content, embeds, polls or stickers
- It does not support voice messages
- It does not support previewing files
- URLs don't create embeds
- You cannot switch this message back to not using Components V2 (you can however upgrade a message to V2)
- Returns:
- The same instance for chaining
- See Also:
-
setSuppressEmbeds
Set whether embeds should be suppressed on this message.
This also includes rich embeds added viasetEmbeds(MessageEmbed...)
.Default: false
- Parameters:
suppress
- True, if all embeds should be suppressed- Returns:
- The same instance for chaining
-
setFiles
TheFileUploads
that should be attached to the message.
This will replace all the existing attachments on the message, if this is an edit request. You can useMessageEditRequest.setAttachments(Collection)
to keep existing attachments, instead of this method.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 usingFileUpload.fromData(File)
, before callingRestAction.queue()
. You can safely use a try-with-resources to handle this, sinceFileUpload.close()
becomes ineffective once the request is handed off.Example
Create an embed with a custom image, uploaded alongside the message:MessageEmbed embed = new EmbedBuilder() .setDescription("Image of a cute cat") .setImage("attachment://cat.png") // here "cat.png" is the name used in the FileUpload.fromData factory method .build(); // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image. FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending channel.sendMessageEmbeds(embed) .setFiles(file) .queue();
- Parameters:
files
- TheFileUploads
to attach to the message, null or an empty list will set the attachments to an empty list and remove them from the message- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided inside the collection
-
setFiles
TheFileUploads
that should be attached to the message.
This will replace all the existing attachments on the message, if this is an edit request. You can useMessageEditRequest.setAttachments(AttachedFile...)
to keep existing attachments, instead of this method.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 usingFileUpload.fromData(File)
, before callingRestAction.queue()
. You can safely use a try-with-resources to handle this, sinceFileUpload.close()
becomes ineffective once the request is handed off.Example
Create an embed with a custom image, uploaded alongside the message:MessageEmbed embed = new EmbedBuilder() .setDescription("Image of a cute cat") .setImage("attachment://cat.png") // here "cat.png" is the name used in the FileUpload.fromData factory method .build(); // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image. FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending channel.sendMessageEmbeds(embed) .setFiles(file) .queue();
- Parameters:
files
- TheFileUploads
to attach to the message, null or an empty list will set the attachments to an empty list and remove them from the message- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided
-
mentionRepliedUser
Whether to mention the user, when replying to a message.
This only matters in combination withMessageCreateAction.setMessageReference(...)
!This is true by default but can be configured using
setDefaultMentionRepliedUser(boolean)
!- Parameters:
mention
- True, to mention the author in the referenced message- Returns:
- The same instance for chaining
-
setAllowedMentions
@Nonnull @CheckReturnValue R setAllowedMentions(@Nullable Collection<Message.MentionType> allowedMentions) Sets theMentionTypes
that should be parsed.
If a message is sent with an empty Set of MentionTypes, then it will not ping any User, Role or@everyone
/@here
, while still showing up as mention tag.If
null
is provided to this method, then all Types will be mentionable (unless whitelisting via one of themention*
methods is used).Note: A default for this can be set using
AllowedMentions.setDefaultMentions(Collection)
.- Parameters:
allowedMentions
- MentionTypes that are allowed to being parsed and mentioned. All other mention types will not be mentioned by this message. You can passnull
orEnumSet.allOf(MentionType.class)
to allow all mentions.- Returns:
- The same instance for chaining
-
mention
Used to provide a whitelist forUsers
,Members
andRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
On other types ofIMentionable
, this does nothing.Note: When a User/Member is whitelisted this way, then parsing of User mentions is automatically disabled (same applies to Roles).
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
mentions
- Users, Members and Roles that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mention
Used to provide a whitelist forUsers
,Members
andRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
On other types ofIMentionable
, this does nothing.Note: When a User/Member is whitelisted this way, then parsing of User mentions is automatically disabled (same applies to Roles).
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
mentions
- Users, Members and Roles that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionUsers
Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a User is whitelisted this way, then parsing of User mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
userIds
- Ids of Users that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionUsers
Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a User is whitelisted this way, then parsing of User mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
userIds
- Ids of Users that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionUsers
Used to provide a whitelist ofUsers
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a User is whitelisted this way, then parsing of User mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
userIds
- Ids of Users that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionRoles
Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a Role is whitelisted this way, then parsing of Role mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
roleIds
- Ids of Roles that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionRoles
Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a Role is whitelisted this way, then parsing of Role mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
roleIds
- Ids of Roles that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
mentionRoles
Used to provide a whitelist ofRoles
that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.Note: When a Role is whitelisted this way, then parsing of Role mentions is automatically disabled.
Also note that whitelisting users or roles implicitly disables parsing of other mentions, if not otherwise set viasetDefaultMentions(Collection)
orsetAllowedMentions(Collection)
.- Parameters:
roleIds
- Ids of Roles that should be explicitly whitelisted to be pingable.- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided- See Also:
-
applyMessage
Applies all the data of the providedMessage
and attempts to copy it.
This cannot copy the file attachments of the message, they must be manually downloaded and provided tosetFiles(FileUpload...)
.
Theallowed mentions
are not updated to reflect the provided message, and might mention users that the message did not.For edit requests, this will set
MessageEditRequest.setReplace(boolean)
totrue
, and replace the existing message completely.- Parameters:
message
- The message to copy the data from- Returns:
- The same instance for chaining
- Throws:
IllegalArgumentException
- If null is provided or the message is a system message
-