Package net.dv8tion.jda.api.utils.messages

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
public interface MessageRequest<R extends MessageRequest<R>> extends MessageData
Abstraction of the common setters used for messages in the API.
These setters can both be applied to edit requests and create requests for messages in various parts of the API.
See Also:

  • Method Details

    • setDefaultMentions

      static void setDefaultMentions(@Nullable Collection<Message.MentionType> allowedMentions)
      Sets the MentionTypes that should be parsed by default. This just sets the default for all RestActions and can be overridden on a per-action basis using setAllowedMentions(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 the mention* 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

      @Nonnull static EnumSet<Message.MentionType> getDefaultMentions()
      Returns the default MentionTypes previously set by AllowedMentions.setDefaultMentions(Collection).
      Returns:
      Default mentions set by AllowedMentions.setDefaultMentions(Collection)

    • setDefaultMentionRepliedUser

      static void setDefaultMentionRepliedUser(boolean mention)
      Sets the default value for mentionRepliedUser(boolean)

      Default: true

      Parameters:
      mention - True, if replies should mention by default

    • isDefaultMentionRepliedUser

      static boolean isDefaultMentionRepliedUser()
      Returns the default mention behavior for replies.
      If this is true then all replies will mention the author of the target message by default. You can specify this individually with mentionRepliedUser(boolean) for each message.

      Default: true

      Returns:
      True, if replies mention by default

    • setContent

      @Nonnull R setContent(@Nullable String content)
      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

      @Nonnull R setEmbeds(@Nonnull Collection<? extends MessageEmbed> embeds)
      The MessageEmbeds that should be attached to the message.
      You can use Collections.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

      @Nonnull default R setEmbeds(@Nonnull MessageEmbed... embeds)
      The MessageEmbeds that should be attached to the message.
      You can use new 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

      @Nonnull R setComponents(@Nonnull Collection<? extends LayoutComponent> components)
      The LayoutComponents that should be attached to the message.
      You can use Collections.emptyList() to remove all components from the message.

      The most commonly used layout is ActionRow.

      Example: Set action rows

      
 final List<LayoutComponent> 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 is still required")
   .setComponents(list)
   .queue();

      Example: Remove action rows

      
 channel.sendMessage("Content is still required")
    .setComponents(Collections.emptyList())
    .queue();
      Parameters:
      components - The components for the message (up to 5)
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException -
      • If null is provided
      • If any component is not message compatible
      • If more than 5 components are provided

    • setComponents

      @Nonnull default R setComponents(@Nonnull LayoutComponent... components)
      The LayoutComponents that should be attached to the message.
      You can call this method without anything to remove all components from the message.

      The most commonly used layout is ActionRow.

      Example: Set action rows

      
 channel.sendMessage("Content is still required")
   .setComponents(
     ActionRow.of(selectMenu) // first row
     ActionRow.of(button1, button2)) // second row (shows below the first)
   .queue();

      Example: Remove action rows

      
 channel.sendMessage("Content is still required")
   .setComponents()
   .queue();
      Parameters:
      components - The components for the message (up to 5)
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException -
      • If null is provided
      • If any component is not message compatible
      • If more than 5 components are provided

    • setActionRow

      @Nonnull default R setActionRow(@Nonnull Collection<? extends ItemComponent> components)
      Convenience method to set the components of a message to a single ActionRow of components.
      To remove components, you should use setComponents(LayoutComponent...) instead.

      Example

      
 final List<ItemComponent> list = new ArrayList<>();
 list.add(button1);
 list.add(button2);

 channel.sendMessage("Content is still required")
   .setActionRow(list)
   .queue();
      is equivalent to: 
      
 final List<LayoutComponent> list = new ArrayList<>();
 list.add(ActionRow.of(button1, button2));

 channel.sendMessage("Content is still required")
   .setComponents(list)
   .queue();

      Parameters:
      components - The ItemComponents for the message (up to 5)
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException -

    • setActionRow

      @Nonnull default R setActionRow(@Nonnull ItemComponent... components)
      Convenience method to set the components of a message to a single ActionRow of components.
      To remove components, you should use setComponents(LayoutComponent...) instead.

      Example

      
 channel.sendMessage("Content is still required")
   .setActionRow(button1, button2)
   .queue();
      is equivalent to: 
      
 channel.sendMessage("Content is still required")
   .setComponents(ActionRow.of(button1, button2))
   .queue();

      Parameters:
      components - The ItemComponents for the message (up to 5)
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException -

    • setSuppressEmbeds

      @Nonnull R setSuppressEmbeds(boolean suppress)
      Set whether embeds should be suppressed on this message.
      This also includes rich embeds added via setEmbeds(MessageEmbed...).

      Default: false

      Parameters:
      suppress - True, if all embeds should be suppressed
      Returns:
      The same instance for chaining

    • setFiles

      @Nonnull R setFiles(@Nullable Collection<? extends FileUpload> files)
      The FileUploads 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 use MessageEditRequest.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 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.

      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 - The FileUploads 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

      @Nonnull default R setFiles(@Nonnull FileUpload... files)
      The FileUploads 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 use MessageEditRequest.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 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.

      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 - The FileUploads 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

      @Nonnull @CheckReturnValue R mentionRepliedUser(boolean mention)
      Whether to mention the used, when replying to a message.
      This only matters in combination with MessageCreateAction.setMessageReference(...)!

      This is true by default but can be configured using setDefaultMentionRepliedUser(boolean)!

      Parameters:
      mention - True, to mention the author if the referenced message
      Returns:
      The same instance for chaining

    • setAllowedMentions

      @Nonnull @CheckReturnValue R setAllowedMentions(@Nullable Collection<Message.MentionType> allowedMentions)
      Sets the MentionTypes 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 the mention* 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 pass null or EnumSet.allOf(MentionType.class) to allow all mentions.
      Returns:
      The same instance for chaining

    • mention

      @Nonnull @CheckReturnValue R mention(@Nonnull Collection<? extends IMentionable> mentions)
      Used to provide a whitelist for Users, Members and Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
      On other types of IMentionable, 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue default R mention(@Nonnull IMentionable... mentions)
      Used to provide a whitelist for Users, Members and Roles that should be pinged, even when they would not be pinged otherwise according to the Set of allowed mention types.
      On other types of IMentionable, 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue R mentionUsers(@Nonnull Collection<String> userIds)
      Used to provide a whitelist of Users 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue default R mentionUsers(@Nonnull String... userIds)
      Used to provide a whitelist of Users 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue default R mentionUsers(@Nonnull long... userIds)
      Used to provide a whitelist of Users 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue R mentionRoles(@Nonnull Collection<String> roleIds)
      Used to provide a whitelist of Roles 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue default R mentionRoles(@Nonnull String... roleIds)
      Used to provide a whitelist of Roles 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull @CheckReturnValue default R mentionRoles(@Nonnull long... roleIds)
      Used to provide a whitelist of Roles 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 via setDefaultMentions(Collection) or setAllowedMentions(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

      @Nonnull R applyMessage(@Nonnull Message message)
      Applies all the data of the provided Message and attempts to copy it.
      This cannot copy the file attachments of the message, they must be manually downloaded and provided to setFiles(FileUpload...).
      The allowed 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) to true, 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