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

Class MessageCreateBuilder

java.lang.Object

net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

net.dv8tion.jda.api.utils.messages.MessageCreateBuilder

All Implemented Interfaces:

MessageCreateRequest<MessageCreateBuilder>, MessageData, MessageRequest<MessageCreateBuilder>

public class MessageCreateBuilder
extends AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>
implements MessageCreateRequest<MessageCreateBuilder>

Builder specialized for building a 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
 

See Also:

• MessageChannel.sendMessage(MessageCreateData)
• IReplyCallback.reply(data)
• InteractionHook.sendMessage(data)
• MessageEditBuilder

Constructor Summary

Constructors

Constructor	Description
MessageCreateBuilder()

Method Summary

Modifier and Type	Method	Description
MessageCreateBuilder	addComponents(Collection<? extends LayoutComponent> components)	Appends the provided LayoutComponents to the request.
MessageCreateBuilder	addContent(String content)	Appends the content to the currently set content of this request.
MessageCreateBuilder	addEmbeds(Collection<? extends MessageEmbed> embeds)	Appends the provided MessageEmbeds to the request.
MessageCreateBuilder	addFiles(Collection<? extends FileUpload> files)	Appends the provided FileUploads to the request.
MessageCreateData	build()	Builds a validated instance of this builder's state, which can then be used for requests.
MessageCreateBuilder	clear()	Clears this builder's state, resetting it to the initial state identical to creating a new instance.
MessageCreateBuilder	closeFiles()	Closes and removes all FileUploads added to this builder.
static MessageCreateBuilder	from(MessageCreateData data)	Factory method to start a builder from an existing instance of MessageCreateData.
static MessageCreateBuilder	fromEditData(MessageEditData data)	Factory method to start a builder from an existing instance of MessageEditData.
static MessageCreateBuilder	fromMessage(Message message)	Factory method to start a builder from an existing instance of Message.
List<FileUpload>	getAttachments()	The configured message attachments as AttachedFile, this is the opposite of MessageRequest.setFiles(Collection) and only returns what was set using that setter.
boolean	isEmpty()	Whether this builder is considered empty, this checks for all required fields of the request type.
boolean	isValid()	Whether this builder has a valid state to build.
MessageCreateBuilder	setFiles(Collection<? extends FileUpload> files)	The FileUploads that should be attached to the message.
MessageCreateBuilder	setSuppressedNotifications(boolean suppressed)	Set whether this message should trigger push/desktop notifications to other users.
MessageCreateBuilder	setTTS(boolean tts)	Whether the message should use Text-to-Speech (TTS).

Methods inherited from class net.dv8tion.jda.api.utils.messages.AbstractMessageBuilder

getAllowedMentions, getComponents, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, isMentionRepliedUser, isSuppressEmbeds, mention, mentionRepliedUser, mentionRoles, mentionUsers, setAllowedMentions, setComponents, setContent, setEmbeds, setSuppressEmbeds

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageCreateRequest

addActionRow, addActionRow, addComponents, addEmbeds, addFiles, applyData, applyEditData, applyMessage

Methods inherited from interface net.dv8tion.jda.api.utils.messages.MessageData

getAllowedMentions, getComponents, getContent, getEmbeds, getMentionedRoles, getMentionedUsers, isMentionRepliedUser, isSuppressEmbeds

Methods 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

@Nonnull
public static MessageCreateBuilder from(@Nonnull
 MessageCreateData data)

Factory method to start a builder from an existing instance of MessageCreateData.
Equivalent to new 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:

• MessageCreateRequest.applyData(MessageCreateData)

fromEditData

@Nonnull
public static MessageCreateBuilder fromEditData(@Nonnull
 MessageEditData data)

Factory method to start a builder from an existing instance of MessageEditData.
Equivalent to new MessageCreateBuilder().applyEditData(data).
This will only set fields which were explicitly set on the MessageEditBuilder, unless it was configured to be replacing.

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:

• MessageCreateRequest.applyEditData(MessageEditData)

fromMessage

@Nonnull
public static MessageCreateBuilder fromMessage(@Nonnull
 Message message)

Factory method to start a builder from an existing instance of Message.
Equivalent to new MessageCreateBuilder().applyMessage(data).
The MessageData are 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:

• MessageRequest.applyMessage(Message)

addContent

@Nonnull
public MessageCreateBuilder addContent(@Nonnull
 String content)

Description copied from interface: MessageCreateRequest

Appends the content to the currently set content of this request.
Use MessageRequest.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:

addContent in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

content - The content to append

Returns:

The same instance for chaining

addEmbeds

@Nonnull
public MessageCreateBuilder addEmbeds(@Nonnull
 Collection<? extends MessageEmbed> embeds)

Description copied from interface: MessageCreateRequest

Appends the provided MessageEmbeds to the request.
Use MessageRequest.setEmbeds(Collection) instead, to replace the embeds entirely.

Example
Sending a message with multiple embeds:

 channel.sendMessageEmbeds(embed1).addEmbeds(embed2).queue();
 

Specified by:

addEmbeds in interface MessageCreateRequest<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: MessageCreateRequest

Appends the provided LayoutComponents to the request.
Use MessageRequest.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:

addComponents in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

components - The layout components to add

Returns:

The same instance for chaining

See Also:

• ActionRow

setFiles

@Nonnull
public MessageCreateBuilder setFiles(@Nullable
 Collection<? extends FileUpload> files)

Description copied from interface: MessageRequest

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();
 

Specified by:

setFiles in interface MessageRequest<MessageCreateBuilder>

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

getAttachments

@Nonnull
public List<FileUpload> getAttachments()

Description copied from interface: MessageData

The configured message attachments as AttachedFile, this is the opposite of MessageRequest.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:

getAttachments in interface MessageCreateRequest<MessageCreateBuilder>

Specified by:

getAttachments in interface MessageData

Returns:

The currently configured attachments, or an empty list if none were set yet

See Also:

• MessageRequest.setFiles(Collection)

addFiles

@Nonnull
public MessageCreateBuilder addFiles(@Nonnull
 Collection<? extends FileUpload> files)

Description copied from interface: MessageCreateRequest

Appends the provided FileUploads to the request.
Use MessageRequest.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 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
Sending a message with multiple files:

 channel.sendFiles(file1).addFiles(file2).queue();
 

Specified by:

addFiles in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

files - The files to add

Returns:

The same instance for chaining

setTTS

@Nonnull
public MessageCreateBuilder setTTS(boolean tts)

Description copied from interface: MessageCreateRequest

Whether the message should use Text-to-Speech (TTS).

Requires Permission.MESSAGE_TTS to be enabled.

Specified by:

setTTS in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

tts - True, if the message should use TTS

Returns:

The same instance for chaining

setSuppressedNotifications

@Nonnull
public MessageCreateBuilder setSuppressedNotifications(boolean suppressed)

Description copied from interface: MessageCreateRequest

Set 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:

setSuppressedNotifications in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

suppressed - True, if this message should not trigger push/desktop notifications

Returns:

The same reply action, for chaining convenience

isEmpty

public boolean isEmpty()

Description copied from class: AbstractMessageBuilder

Whether this builder is considered empty, this checks for all required fields of the request type.
On a create request, this checks for content, embeds, components, and files.
An edit request is only considered empty if no setters were called. And never empty, if the builder is a replace request.

Specified by:

isEmpty in class AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

Returns:

True, if the builder state is empty

isValid

public boolean isValid()

Description copied from class: AbstractMessageBuilder

Whether this builder has a valid state to build.
If this is false, then AbstractMessageBuilder.build() throws an IllegalStateException. You can check the exception docs on AbstractMessageBuilder.build() for specifics.

Specified by:

isValid in class AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

Returns:

True, if the builder is in a valid state

build

@Nonnull
public MessageCreateData build()

Description copied from class: AbstractMessageBuilder

Builds a validated instance of this builder's state, which can then be used for requests.

Specified by:

build in class AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

Returns:

The validated data instance

clear

@Nonnull
public MessageCreateBuilder clear()

Description copied from class: AbstractMessageBuilder

Clears 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 calling clear() to close the files explicitly.

Overrides:

clear in class AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

Returns:

The same builder instance for chaining

closeFiles

@Nonnull
public MessageCreateBuilder closeFiles()

Description copied from class: AbstractMessageBuilder

Closes and removes all FileUploads added to this builder.

This will keep any AttachmentUpdates added to this builder, as those do not require closing. You can use MessageEditRequest.setAttachments(AttachedFile...) to remove them as well.

Specified by:

closeFiles in class AbstractMessageBuilder<MessageCreateData,MessageCreateBuilder>

Returns:

The same builder instance for chaining