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 MessageTopLevelComponent> components)	Appends the provided MessageTopLevelComponents 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.
MessagePollData	getPoll()	The poll attached to this message
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	setPoll(MessagePollData poll)	Add a poll to this 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).
MessageCreateBuilder	setVoiceMessage(boolean voiceMessage)	Whether this message should be considered a voice message.

Methods inherited from class AbstractMessageBuilder

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

Methods inherited from class Object

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

Methods inherited from interface MessageCreateRequest

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

Methods inherited from interface MessageData

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

Methods inherited from interface MessageRequest

mention, mention, mentionRepliedUser, mentionRoles, mentionRoles, mentionRoles, mentionUsers, mentionUsers, mentionUsers, setAllowedMentions, setComponents, setComponents, setComponents, setContent, setEmbeds, setEmbeds, setFiles, setSuppressEmbeds, useComponentsV2, useComponentsV2

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 MessageTopLevelComponent> components)

Description copied from interface: MessageCreateRequest

Appends the provided MessageTopLevelComponents to the request.
Use MessageRequest.setComponents(Collection) instead, to replace the components entirely.

Example
Sending a message with multiple 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")
       .addComponents(list)
       .queue();

Specified by:

addComponents in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

components - The MessageTopLevelComponents to add, 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

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)

getPoll

@Nullable
public MessagePollData getPoll()

Description copied from interface: MessageCreateRequest

The poll attached to this message

Specified by:

getPoll in interface MessageCreateRequest<MessageCreateBuilder>

Returns:

The attached poll, or null if no poll is present

setPoll

@Nonnull
public MessageCreateBuilder setPoll(@Nullable
 MessagePollData poll)

Description copied from interface: MessageCreateRequest

Add a poll to this message.

Specified by:

setPoll in interface MessageCreateRequest<MessageCreateBuilder>

Parameters:

poll - The poll to send

Returns:

The same instance for chaining

See Also:

• MessagePollBuilder

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 instance for chaining

setVoiceMessage

@Nonnull
public MessageCreateBuilder setVoiceMessage(boolean voiceMessage)

Description copied from interface: MessageCreateRequest

Whether this message should be considered a voice message.
Voice messages must upload a valid voice message attachment, using FileUpload.asVoiceMessage(MediaType, byte[], double).

Specified by:

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