Package net.dv8tion.jda.core

Class EmbedBuilder

java.lang.Object

net.dv8tion.jda.core.EmbedBuilder

public class EmbedBuilder
extends java.lang.Object

Builder system used to build MessageEmbeds.
A visual breakdown of an Embed and how it relates to this class is available at https://imgur.com/a/yOb5n.

Since:

3.0

Author:

John A. Grosh

Field Summary

Fields

Modifier and Type	Field	Description
static java.util.regex.Pattern	URL_PATTERN
static java.lang.String	ZERO_WIDTH_SPACE

Constructor Summary

Constructors

Constructor	Description
EmbedBuilder()	Creates an EmbedBuilder to be used to creates an embed to send.
EmbedBuilder(EmbedBuilder builder)
EmbedBuilder(MessageEmbed embed)	Creates an EmbedBuilder using fields in an existing embed.

Method Summary

Modifier and Type	Method	Description
EmbedBuilder	addBlankField(boolean inline)	Adds a blank (empty) Field to the embed.
EmbedBuilder	addField(java.lang.String name, java.lang.String value, boolean inline)	Adds a Field to the embed.
EmbedBuilder	addField(MessageEmbed.Field field)	Copies the provided Field into a new Field for this builder.
EmbedBuilder	appendDescription(java.lang.CharSequence description)	Appends to the description of the embed.
MessageEmbed	build()	Returns a MessageEmbed that has been checked as being valid for sending.
EmbedBuilder	clear()	Resets this builder to default state.
EmbedBuilder	clearFields()	Clears all fields from the embed, such as those created with the EmbedBuilder(MessageEmbed) constructor or via the addField methods.
java.lang.StringBuilder	getDescriptionBuilder()	The StringBuilder used to build the description for the embed.
java.util.List<MessageEmbed.Field>	getFields()	Modifiable list of MessageEmbed Fields that the builder will use for build().
boolean	isEmpty()	Checks if the given embed is empty.
boolean	isValidLength(AccountType type)	Checks whether the constructed MessageEmbed is within the limits for the specified AccountType Bot: 6000 Client: 2000
int	length()	The overall length of the current EmbedBuilder in displayed characters.
EmbedBuilder	setAuthor(java.lang.String name)	Sets the Author of the embed.
EmbedBuilder	setAuthor(java.lang.String name, java.lang.String url)	Sets the Author of the embed.
EmbedBuilder	setAuthor(java.lang.String name, java.lang.String url, java.lang.String iconUrl)	Sets the Author of the embed.
EmbedBuilder	setColor(int color)	Sets the raw RGB color value for the embed.
EmbedBuilder	setColor(java.awt.Color color)	Sets the Color of the embed.
EmbedBuilder	setDescription(java.lang.CharSequence description)	Sets the Description of the embed.
EmbedBuilder	setFooter(java.lang.String text, java.lang.String iconUrl)	Sets the Footer of the embed.
EmbedBuilder	setImage(java.lang.String url)	Sets the Image of the embed.
EmbedBuilder	setThumbnail(java.lang.String url)	Sets the Thumbnail of the embed.
EmbedBuilder	setTimestamp(java.time.temporal.TemporalAccessor temporal)	Sets the Timestamp of the embed.
EmbedBuilder	setTitle(java.lang.String title)	Sets the Title of the embed.
EmbedBuilder	setTitle(java.lang.String title, java.lang.String url)	Sets the Title of the embed.

Methods inherited from class java.lang.Object

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

Field Detail

ZERO_WIDTH_SPACE

public static final java.lang.String ZERO_WIDTH_SPACE

See Also:

Constant Field Values

URL_PATTERN

public static final java.util.regex.Pattern URL_PATTERN

Constructor Detail

EmbedBuilder

public EmbedBuilder()

Creates an EmbedBuilder to be used to creates an embed to send.
Every part of an embed can be removed or cleared by providing null to the setter method.

EmbedBuilder

public EmbedBuilder(EmbedBuilder builder)

EmbedBuilder

public EmbedBuilder(MessageEmbed embed)

Creates an EmbedBuilder using fields in an existing embed.

Parameters:

embed - the existing embed

Method Detail

build

public MessageEmbed build()

Returns a MessageEmbed that has been checked as being valid for sending.

Returns:

the built, sendable MessageEmbed

Throws:

java.lang.IllegalStateException - If the embed is empty. Can be checked with isEmpty().

clear

public EmbedBuilder clear()

Resets this builder to default state.
All parts will be either empty or null after this method has returned.

Returns:

The current EmbedBuilder with default values

isEmpty

public boolean isEmpty()

Checks if the given embed is empty. Empty embeds will throw an exception if built

Returns:

true if the embed is empty and cannot be built

length

public int length()

The overall length of the current EmbedBuilder in displayed characters.
Represents the MessageEmbed.getLength() value.

Returns:

length of the current builder state

isValidLength

public boolean isValidLength(AccountType type)

Checks whether the constructed MessageEmbed is within the limits for the specified AccountType

• Bot: 6000
• Client: 2000

Parameters:

type - The AccountType to validate

Returns:

True, if the length is less or equal to the specific limit

Throws:

java.lang.IllegalArgumentException - If provided with null

setTitle

public EmbedBuilder setTitle(java.lang.String title)

Sets the Title of the embed.
Overload for setTitle(String, String) without URL parameter.

Example

Parameters:

title - the title of the embed

Returns:

the builder after the title has been set

Throws:

java.lang.IllegalArgumentException -

• If the provided title is an empty String.
• If the length of title is greater than MessageEmbed.TITLE_MAX_LENGTH.

setTitle

public EmbedBuilder setTitle(java.lang.String title,
                             java.lang.String url)

Sets the Title of the embed.
You can provide null as url if no url should be used.

Example

Parameters:

title - the title of the embed

url - Makes the title into a hyperlink pointed at this url.

Returns:

the builder after the title has been set

Throws:

java.lang.IllegalArgumentException -

• If the provided title is an empty String.
• If the length of title is greater than MessageEmbed.TITLE_MAX_LENGTH.
• If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided url is not a properly formatted http or https url.

getDescriptionBuilder

public java.lang.StringBuilder getDescriptionBuilder()

The StringBuilder used to build the description for the embed.
Note: To reset the description use setDescription(null)

Returns:

StringBuilder with current description context

setDescription

public final EmbedBuilder setDescription(java.lang.CharSequence description)

Sets the Description of the embed. This is where the main chunk of text for an embed is typically placed.

Example

Parameters:

description - the description of the embed, null to reset

Returns:

the builder after the description has been set

Throws:

java.lang.IllegalArgumentException - If the length of description is greater than MessageEmbed.TEXT_MAX_LENGTH

appendDescription

public EmbedBuilder appendDescription(java.lang.CharSequence description)

Appends to the description of the embed. This is where the main chunk of text for an embed is typically placed.

Example

Parameters:

description - the string to append to the description of the embed

Returns:

the builder after the description has been set

Throws:

java.lang.IllegalArgumentException -

• If the provided description String is null
• If the length of description is greater than MessageEmbed.TEXT_MAX_LENGTH.

setTimestamp

public EmbedBuilder setTimestamp(java.time.temporal.TemporalAccessor temporal)

Sets the Timestamp of the embed.

Example

Hint: You can get the current time using Instant.now() or convert time from a millisecond representation by using Instant.ofEpochMilli(long);

Parameters:

temporal - the temporal accessor of the timestamp

Returns:

the builder after the timestamp has been set

setColor

public EmbedBuilder setColor(java.awt.Color color)

Sets the Color of the embed. Example

Parameters:

color - The Color of the embed or null to use no color

Returns:

the builder after the color has been set

See Also:

setColor(int)

setColor

public EmbedBuilder setColor(int color)

Sets the raw RGB color value for the embed. Example

Parameters:

color - The raw rgb value, or Role.DEFAULT_COLOR_RAW to use no color

Returns:

the builder after the color has been set

See Also:

setColor(java.awt.Color)

setThumbnail

public EmbedBuilder setThumbnail(java.lang.String url)

Sets the Thumbnail of the embed.

Example

Uploading images with Embeds
When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

Example

 MessageChannel channel; // = reference of a MessageChannel
 MessageBuilder message = new MessageBuilder();
 EmbedBuilder embed = new EmbedBuilder();
 InputStream file = new URL("https://http.cat/500").openStream();
 embed.setThumbnail("attachment://cat.png") // we specify this in sendFile as "cat.png"
      .setDescription("This is a cute cat :3");
 message.setEmbed(embed.build());
 channel.sendFile(file, "cat.png", message.build()).queue();
 

Parameters:

url - the url of the thumbnail of the embed

Returns:

the builder after the thumbnail has been set

Throws:

java.lang.IllegalArgumentException -

• If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided url is not a properly formatted http or https url.

setImage

public EmbedBuilder setImage(java.lang.String url)

Sets the Image of the embed.

Example

Uploading images with Embeds
When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

Example

 MessageChannel channel; // = reference of a MessageChannel
 MessageBuilder message = new MessageBuilder();
 EmbedBuilder embed = new EmbedBuilder();
 InputStream file = new URL("https://http.cat/500").openStream();
 embed.setImage("attachment://cat.png") // we specify this in sendFile as "cat.png"
      .setDescription("This is a cute cat :3");
 message.setEmbed(embed.build());
 channel.sendFile(file, "cat.png", message.build()).queue();
 

Parameters:

url - the url of the image of the embed

Returns:

the builder after the image has been set

Throws:

java.lang.IllegalArgumentException -

• If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided url is not a properly formatted http or https url.

See Also:

MessageChannel.sendFile(...)

setAuthor

public EmbedBuilder setAuthor(java.lang.String name)

Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name.

Example

Parameters:

name - the name of the author of the embed. If this is not set, the author will not appear in the embed

Returns:

the builder after the author has been set

setAuthor

public EmbedBuilder setAuthor(java.lang.String name,
                              java.lang.String url)

Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name and the url.

Example

Parameters:

name - the name of the author of the embed. If this is not set, the author will not appear in the embed

url - the url of the author of the embed

Returns:

the builder after the author has been set

Throws:

java.lang.IllegalArgumentException -

• If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided url is not a properly formatted http or https url.

setAuthor

public EmbedBuilder setAuthor(java.lang.String name,
                              java.lang.String url,
                              java.lang.String iconUrl)

Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url.

Example

Uploading images with Embeds
When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

Example

 MessageChannel channel; // = reference of a MessageChannel
 MessageBuilder message = new MessageBuilder();
 EmbedBuilder embed = new EmbedBuilder();
 InputStream file = new URL("https://http.cat/500").openStream();
 embed.setAuthor("Minn", null, "attachment://cat.png") // we specify this in sendFile as "cat.png"
      .setDescription("This is a cute cat :3");
 message.setEmbed(embed.build());
 channel.sendFile(file, "cat.png", message.build()).queue();
 

Parameters:

name - the name of the author of the embed. If this is not set, the author will not appear in the embed

url - the url of the author of the embed

iconUrl - the url of the icon for the author

Returns:

the builder after the author has been set

Throws:

java.lang.IllegalArgumentException -

• If the length of url is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided url is not a properly formatted http or https url.
• If the length of iconUrl is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided iconUrl is not a properly formatted http or https url.

setFooter

public EmbedBuilder setFooter(java.lang.String text,
                              java.lang.String iconUrl)

Sets the Footer of the embed.

Example

Uploading images with Embeds
When uploading an image (using MessageChannel.sendFile(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

Example

 MessageChannel channel; // = reference of a MessageChannel
 MessageBuilder message = new MessageBuilder();
 EmbedBuilder embed = new EmbedBuilder();
 InputStream file = new URL("https://http.cat/500").openStream();
 embed.setFooter("Cool footer!", "attachment://cat.png") // we specify this in sendFile as "cat.png"
      .setDescription("This is a cute cat :3");
 message.setEmbed(embed.build());
 channel.sendFile(file, "cat.png", message.build()).queue();
 

Parameters:

text - the text of the footer of the embed. If this is not set, the footer will not appear in the embed.

iconUrl - the url of the icon for the footer

Returns:

the builder after the footer has been set

Throws:

java.lang.IllegalArgumentException -

• If the length of text is longer than MessageEmbed.TEXT_MAX_LENGTH.
• If the length of iconUrl is longer than MessageEmbed.URL_MAX_LENGTH.
• If the provided iconUrl is not a properly formatted http or https url.

addField

public EmbedBuilder addField(MessageEmbed.Field field)

Copies the provided Field into a new Field for this builder.
For additional documentation, see addField(String, String, boolean)

Parameters:

field - the field object to add

Returns:

the builder after the field has been added

addField

public EmbedBuilder addField(java.lang.String name,
                             java.lang.String value,
                             boolean inline)

Adds a Field to the embed.

Note: If a blank string is provided to either name or value, the blank string is replaced with ZERO_WIDTH_SPACE.

Example of Inline

Example if Non-inline

Parameters:

name - the name of the Field, displayed in bold above the value.

value - the contents of the field.

inline - whether or not this field should display inline.

Returns:

the builder after the field has been added

Throws:

java.lang.IllegalArgumentException -

• If only name or value is set. Both must be set.
• If the length of name is greater than MessageEmbed.TITLE_MAX_LENGTH.
• If the length of value is greater than MessageEmbed.VALUE_MAX_LENGTH.

addBlankField

public EmbedBuilder addBlankField(boolean inline)

Adds a blank (empty) Field to the embed.

Example of Inline

Example of Non-inline

Parameters:

inline - whether or not this field should display inline

Returns:

the builder after the field has been added

clearFields

public EmbedBuilder clearFields()

Clears all fields from the embed, such as those created with the EmbedBuilder(MessageEmbed) constructor or via the addField methods.

Returns:

the builder after the field has been added

getFields

public java.util.List<MessageEmbed.Field> getFields()

Modifiable list of MessageEmbed Fields that the builder will use for build().
You can add/remove Fields and restructure this List and it will then be applied in the built MessageEmbed. These fields will be available again through MessageEmbed.getFields().

Returns:

Mutable List of Fields