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
    • setDefaultUseComponentsV2

      static void setDefaultUseComponentsV2(boolean use)
      Sets whether V2 components will be used by default, this is false 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 is false 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 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 MessageTopLevelComponent> components)
      The MessageTopLevelComponents that should be attached to the message.
      You can use Collections.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 - 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:
      The same instance for chaining
      Throws:
      IllegalArgumentException -
    • setComponents

      @Nonnull default R setComponents(@Nonnull MessageTopLevelComponent... components)
      The MessageTopLevelComponents 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 - 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:
      The same instance for chaining
      Throws:
      IllegalArgumentException -
    • setComponents

      @Nonnull default R setComponents(@Nonnull ComponentTree<? extends MessageTopLevelComponent> tree)
      The ComponentTree of MessageTopLevelComponents that should be attached to the message.
      You can call this method without anything to remove all components from the message.
      Parameters:
      tree - The new 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:
      The same instance for chaining
      Throws:
      IllegalArgumentException -
      See Also:
    • useComponentsV2

      @Nonnull R useComponentsV2(boolean use)
      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 extending MessageTopLevelComponent, 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

      @Nonnull default R useComponentsV2()
      Enables using V2 components, this is disabled by default.
      This is a shortcut for useComponentV2(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 extending MessageTopLevelComponent, 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

      @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 user, 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 in 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

      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

      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

      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