Class MessageCreateBuilder
- All Implemented Interfaces:
MessageCreateRequest<MessageCreateBuilder>,MessageData,MessageRequest<MessageCreateBuilder>
MessageCreateData.
This can be used to build a request and send it to various API endpoints.
Example
try (FileUpload file = FileUpload.fromData(new File("wave.gif"))) {
MessageCreateData data = new MessageCreateBuilder()
.setContent("Hello guys!")
.setTTS(true)
.setFiles(file)
.build();
for (MessageChannel channel : channels) {
channel.sendMessage(data).queue();
}
} // closes wave.gif if an error occurred
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddComponents(Collection<? extends LayoutComponent> components) Appends the providedLayoutComponentsto the request.addContent(String content) Appends the content to the currently set content of this request.addEmbeds(Collection<? extends MessageEmbed> embeds) Appends the providedMessageEmbedsto the request.addFiles(Collection<? extends FileUpload> files) Appends the providedFileUploadsto the request.build()Builds a validated instance of this builder's state, which can then be used for requests.clear()Clears this builder's state, resetting it to the initial state identical to creating a new instance.Closes and removes allFileUploadsadded to this builder.static MessageCreateBuilderfrom(MessageCreateData data) Factory method to start a builder from an existing instance ofMessageCreateData.static MessageCreateBuilderfromEditData(MessageEditData data) Factory method to start a builder from an existing instance ofMessageEditData.static MessageCreateBuilderfromMessage(Message message) Factory method to start a builder from an existing instance ofMessage.The configured message attachments asAttachedFile, this is the opposite ofMessageRequest.setFiles(Collection)and only returns what was set using that setter.getPoll()The poll attached to this messagebooleanisEmpty()Whether this builder is considered empty, this checks for all required fields of the request type.booleanisValid()Whether this builder has a valid state to build.setFiles(Collection<? extends FileUpload> files) TheFileUploadsthat should be attached to the message.setPoll(MessagePollData poll) Add a poll to this message.setSuppressedNotifications(boolean suppressed) Set whether this message should trigger push/desktop notifications to other users.setTTS(boolean tts) Whether the message should use Text-to-Speech (TTS).setVoiceMessage(boolean voiceMessage) Whether this message should be considered a voice message.Methods inherited from class net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder
getAllowedMentions, getComponents, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, getMessageFlagsRaw, isMentionRepliedUser, isSuppressEmbeds, mention, mentionRepliedUser, mentionRoles, mentionUsers, setAllowedMentions, setComponents, setContent, setEmbeds, setSuppressEmbedsMethods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface net.dv8tion.jda.api.utils.messages.MessageCreateRequest
addActionRow, addActionRow, addComponents, addEmbeds, addFiles, applyData, applyEditData, applyMessageMethods inherited from interface net.dv8tion.jda.api.utils.messages.MessageData
getAllowedMentions, getComponents, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, isMentionRepliedUser, isSuppressEmbedsMethods inherited from interface net.dv8tion.jda.api.utils.messages.MessageRequest
mention, mention, mentionRepliedUser, mentionRoles, mentionRoles, mentionRoles, mentionUsers, mentionUsers, mentionUsers, setActionRow, setActionRow, setAllowedMentions, setComponents, setComponents, setContent, setEmbeds, setEmbeds, setFiles, setSuppressEmbeds
-
Constructor Details
-
MessageCreateBuilder
public MessageCreateBuilder()
-
-
Method Details
-
from
Factory method to start a builder from an existing instance ofMessageCreateData.
Equivalent tonew MessageCreateBuilder().applyData(data).- Parameters:
data- The message create data to apply- Returns:
- A new MessageCreateBuilder instance with the applied data
- Throws:
IllegalArgumentException- If null is provided- See Also:
-
fromEditData
Factory method to start a builder from an existing instance ofMessageEditData.
Equivalent tonew MessageCreateBuilder().applyEditData(data).
This will only set fields which were explicitly set on theMessageEditBuilder, unless it was configured to bereplacing.This will not copy the message's attachments, only any configured
FileUploads. To copy attachments, you must download them explicitly instead.- Parameters:
data- The message edit data to apply- Returns:
- A new MessageCreateBuilder instance with the applied data
- Throws:
IllegalArgumentException- If null is provided- See Also:
-
fromMessage
Factory method to start a builder from an existing instance ofMessage.
Equivalent tonew MessageCreateBuilder().applyMessage(data).
TheMessageDataare not updated to reflect the provided message, and might mention users that the message did not.This cannot copy the file attachments of the message, they must be manually downloaded and provided to
MessageRequest.setFiles(FileUpload...).- Parameters:
message- The message data to apply- Returns:
- A new MessageCreateBuilder instance with the applied data
- Throws:
IllegalArgumentException- If the message is null or a system message- See Also:
-
addContent
Description copied from interface:MessageCreateRequestAppends the content to the currently set content of this request.
UseMessageRequest.setContent(String)instead, to replace the content entirely.Example
Sending a message with the content"Hello World!":channel.sendMessage("Hello ").addContent("World!").queue();- Specified by:
addContentin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
content- The content to append- Returns:
- The same instance for chaining
-
addEmbeds
Description copied from interface:MessageCreateRequestAppends the providedMessageEmbedsto the request.
UseMessageRequest.setEmbeds(Collection)instead, to replace the embeds entirely.Example
Sending a message with multiple embeds:channel.sendMessageEmbeds(embed1).addEmbeds(embed2).queue();- Specified by:
addEmbedsin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
embeds- The embeds to add- Returns:
- The same instance for chaining
-
addComponents
@Nonnull public MessageCreateBuilder addComponents(@Nonnull Collection<? extends LayoutComponent> components) Description copied from interface:MessageCreateRequestAppends the providedLayoutComponentsto the request.
UseMessageRequest.setComponents(Collection)instead, to replace the components entirely.Example
Sending a message with multiple action rows:channel.sendMessageComponents(ActionRow.of(selectMenu)) .addComponents(ActionRow.of(button1, button2)) .queue();- Specified by:
addComponentsin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
components- The layout components to add- Returns:
- The same instance for chaining
- See Also:
-
setFiles
Description copied from interface:MessageRequestTheFileUploadsthat 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();- Specified by:
setFilesin interfaceMessageRequest<MessageCreateBuilder>- Parameters:
files- TheFileUploadsto 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
-
getAttachments
Description copied from interface:MessageDataThe configured message attachments asAttachedFile, this is the opposite ofMessageRequest.setFiles(Collection)and only returns what was set using that setter.For message edit requests, this will not be the current file attachments of the message.
- Specified by:
getAttachmentsin interfaceMessageCreateRequest<MessageCreateBuilder>- Specified by:
getAttachmentsin interfaceMessageData- Returns:
- The currently configured attachments, or an empty list if none were set yet
- See Also:
-
getPoll
Description copied from interface:MessageCreateRequestThe poll attached to this message- Specified by:
getPollin interfaceMessageCreateRequest<MessageCreateBuilder>- Returns:
- The attached poll, or null if no poll is present
-
setPoll
Description copied from interface:MessageCreateRequestAdd a poll to this message.- Specified by:
setPollin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
poll- The poll to send- Returns:
- The same instance for chaining
- See Also:
-
addFiles
Description copied from interface:MessageCreateRequestAppends the providedFileUploadsto the request.
UseMessageRequest.setFiles(Collection)instead, to replace the file attachments entirely.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
Sending a message with multiple files:channel.sendFiles(file1).addFiles(file2).queue();- Specified by:
addFilesin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
files- The files to add- Returns:
- The same instance for chaining
-
setTTS
Description copied from interface:MessageCreateRequestWhether the message should use Text-to-Speech (TTS).Requires
Permission.MESSAGE_TTSto be enabled.- Specified by:
setTTSin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
tts- True, if the message should use TTS- Returns:
- The same instance for chaining
-
setSuppressedNotifications
Description copied from interface:MessageCreateRequestSet whether this message should trigger push/desktop notifications to other users.
When a message is suppressed, it will not trigger push/desktop notifications.- Specified by:
setSuppressedNotificationsin interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
suppressed- True, if this message should not trigger push/desktop notifications- Returns:
- The same instance for chaining
-
setVoiceMessage
Description copied from interface:MessageCreateRequestWhether this message should be considered a voice message.
Voice messages must upload a valid voice message attachment, usingFileUpload.asVoiceMessage(MediaType, byte[], double).- Specified by:
setVoiceMessagein interfaceMessageCreateRequest<MessageCreateBuilder>- Parameters:
voiceMessage- True, if this message is a voice message. Turned on automatically if attachment is a valid voice message attachment.- Returns:
- The same instance for chaining
-
isEmpty
public boolean isEmpty()Description copied from class:AbstractMessageBuilderWhether this builder is considered empty, this checks for all required fields of the request type.
On a create request, this checks forcontent,embeds,components, andfiles.
An edit request is only considered empty if no setters were called. And never empty, if the builder is areplace request.- Specified by:
isEmptyin classAbstractMessageBuilder<MessageCreateData,MessageCreateBuilder> - Returns:
- True, if the builder state is empty
-
isValid
public boolean isValid()Description copied from class:AbstractMessageBuilderWhether this builder has a valid state to build.
If this isfalse, thenAbstractMessageBuilder.build()throws anIllegalStateException. You can check the exception docs onAbstractMessageBuilder.build()for specifics.- Specified by:
isValidin classAbstractMessageBuilder<MessageCreateData,MessageCreateBuilder> - Returns:
- True, if the builder is in a valid state
-
build
Description copied from class:AbstractMessageBuilderBuilds a validated instance of this builder's state, which can then be used for requests.- Specified by:
buildin classAbstractMessageBuilder<MessageCreateData,MessageCreateBuilder> - Returns:
- The validated data instance
-
clear
Description copied from class:AbstractMessageBuilderClears this builder's state, resetting it to the initial state identical to creating a new instance.WARNING: This will remove all the files added to the builder, but will not close them. You can use
AbstractMessageBuilder.closeFiles()before callingclear()to close the files explicitly.- Overrides:
clearin classAbstractMessageBuilder<MessageCreateData,MessageCreateBuilder> - Returns:
- The same builder instance for chaining
-
closeFiles
Description copied from class:AbstractMessageBuilderCloses and removes allFileUploadsadded to this builder.This will keep any
AttachmentUpdatesadded to this builder, as those do not require closing. You can useMessageEditRequest.setAttachments(AttachedFile...)to remove them as well.- Specified by:
closeFilesin classAbstractMessageBuilder<MessageCreateData,MessageCreateBuilder> - Returns:
- The same builder instance for chaining
-