EmbedBuilder

Builder system for creating rich message embeds with customizable fields, colors, images, and formatting

EmbedBuilder

Builder system used to build MessageEmbed objects. Embeds allow you to send rich, formatted messages with titles, descriptions, fields, images, and more.

Constructor

EmbedBuilder()

Constructs a new EmbedBuilder instance.

EmbedBuilder embed = new EmbedBuilder();

EmbedBuilder(EmbedBuilder builder)

Creates an EmbedBuilder using fields from an existing builder.

EmbedBuilder newEmbed = new EmbedBuilder(existingBuilder);

EmbedBuilder(MessageEmbed embed)

Creates an EmbedBuilder using fields from an existing embed.

EmbedBuilder newEmbed = new EmbedBuilder(existingEmbed);

Static Methods

fromData(DataObject data)

Creates an instance from a serialized DataObject. This is the inverse of MessageEmbed.toData().

DataObject data = // ... serialized embed data
EmbedBuilder embed = EmbedBuilder.fromData(data);

Builder Methods

setTitle(String title)

Sets the title of the embed.

Parameters:

• title - The title text (max 256 characters)

Returns: The builder instance

embed.setTitle("Welcome to JDA!");

setTitle(String title, String url)

Sets the title with a clickable URL.

Parameters:

• title - The title text (max 256 characters)
• url - The URL the title links to (must be http/https)

Returns: The builder instance

embed.setTitle("JDA Documentation", "https://docs.jda.wiki");

setUrl(String url)

Sets the URL of the embed. Used with title for clickable hyperlinks. If multiple embeds in a message use the same URL, Discord merges them into a gallery view.

Parameters:

• url - The URL (must be http/https, max 2048 characters)

Returns: The builder instance

embed.setUrl("https://github.com/discord-jda/JDA");

setDescription(CharSequence description)

Sets the description of the embed. This is the main text content.

Parameters:

• description - The description text (max 4096 characters)

Returns: The builder instance

embed.setDescription("This is a detailed description of the embed.");

appendDescription(CharSequence description)

Appends text to the existing description.

Parameters:

• description - The text to append (total max 4096 characters)

Returns: The builder instance

embed.setDescription("First line\n")
     .appendDescription("Second line\n")
     .appendDescription("Third line");

getDescriptionBuilder()

Returns the StringBuilder used to build the description. Useful for advanced manipulation.

Returns: StringBuilder with current description

StringBuilder desc = embed.getDescriptionBuilder();
desc.append("Added text");

setColor(Color color)

Sets the color of the embed’s side bar.

Parameters:

• color - The color (use null for default)

Returns: The builder instance

import java.awt.Color;

embed.setColor(Color.BLUE);
embed.setColor(new Color(255, 0, 0)); // Red

setColor(int color)

Sets the color using a raw RGB integer value.

Parameters:

• color - The raw RGB value

Returns: The builder instance

embed.setColor(0xFF5733); // Orange

setTimestamp(TemporalAccessor temporal)

Sets the timestamp shown at the bottom of the embed.

Parameters:

• temporal - The timestamp (typically Instant or OffsetDateTime)

Returns: The builder instance

import java.time.Instant;

embed.setTimestamp(Instant.now());

setThumbnail(String url)

Sets a small thumbnail image in the top-right corner.

Parameters:

• url - The image URL (http/https or attachment://filename.ext)

Returns: The builder instance

embed.setThumbnail("https://example.com/image.png");

// Using uploaded attachment
embed.setThumbnail("attachment://cat.png");
channel.sendFiles(FileUpload.fromData(file, "cat.png"))
       .setEmbeds(embed.build())
       .queue();

setImage(String url)

Sets a large image displayed in the embed body.

Parameters:

• url - The image URL (http/https or attachment://filename.ext)

Returns: The builder instance

embed.setImage("https://example.com/banner.png");

// Using uploaded attachment
embed.setImage("attachment://banner.png");
channel.sendFiles(FileUpload.fromData(file, "banner.png"))
       .setEmbeds(embed.build())
       .queue();

setAuthor(String name)

Sets the author name displayed at the top of the embed.

Parameters:

• name - The author name (max 256 characters)

Returns: The builder instance

embed.setAuthor("Bot Name");

setAuthor(String name, String url)

Sets the author with a clickable URL.

Parameters:

• name - The author name (max 256 characters)
• url - The URL the name links to (must be http/https)

Returns: The builder instance

embed.setAuthor("GitHub", "https://github.com");

setAuthor(String name, String url, String iconUrl)

Sets the author with a URL and icon.

Parameters:

• name - The author name (max 256 characters)
• url - The URL the name links to (must be http/https)
• iconUrl - The icon image URL (http/https or attachment://)

Returns: The builder instance

embed.setAuthor("User", "https://example.com", "https://example.com/avatar.png");

setFooter(String text)

Sets the footer text displayed at the bottom of the embed.

Parameters:

• text - The footer text (max 2048 characters)

Returns: The builder instance

embed.setFooter("Requested by User#1234");

setFooter(String text, String iconUrl)

Sets the footer with an icon.

Parameters:

• text - The footer text (max 2048 characters)
• iconUrl - The icon image URL (http/https or attachment://)

Returns: The builder instance

embed.setFooter("JDA Bot", "https://example.com/icon.png");

addField(String name, String value, boolean inline)

Adds a field to the embed. Fields are displayed in rows.

Parameters:

• name - The field name/title (max 256 characters)
• value - The field value/content (max 1024 characters)
• inline - Whether the field displays inline with others

Returns: The builder instance

embed.addField("Field 1", "Value 1", true)
     .addField("Field 2", "Value 2", true)
     .addField("Long Field", "This field takes the full width", false);

addField(MessageEmbed.Field field)

Adds a field object to the embed.

Parameters:

• field - The field to add

Returns: The builder instance

MessageEmbed.Field field = new MessageEmbed.Field("Name", "Value", true);
embed.addField(field);

addBlankField(boolean inline)

Adds an empty field for spacing.

Parameters:

• inline - Whether the blank field is inline

Returns: The builder instance

embed.addField("Field 1", "Value", true)
     .addBlankField(true) // Spacing
     .addField("Field 2", "Value", true);

clearFields()

Removes all fields from the embed.

Returns: The builder instance

embed.clearFields();

getFields()

Returns a modifiable list of the embed’s fields.

Returns: Mutable List<MessageEmbed.Field>

List<MessageEmbed.Field> fields = embed.getFields();
fields.remove(0); // Remove first field

clear()

Resets the builder to default state, removing all content.

Returns: The builder instance

embed.clear(); // Start fresh

copyFrom(EmbedBuilder builder)

Copies all data from another builder.

Parameters:

• builder - The builder to copy from

embed.copyFrom(otherBuilder);

copyFrom(MessageEmbed embed)

Copies all data from an existing embed.

Parameters:

• embed - The embed to copy from

embed.copyFrom(existingEmbed);

Validation Methods

isEmpty()

Checks if the embed is empty. Empty embeds cannot be built.

Returns: true if empty

if (embed.isEmpty()) {
    System.out.println("Add some content!");
}

length()

Returns the total character length of the embed.

Returns: Total character count

int totalLength = embed.length();

isValidLength()

Checks if the embed is within Discord’s length limits (6000 characters for bots).

Returns: true if within limits

if (!embed.isValidLength()) {
    System.out.println("Embed is too long!");
}

build()

Builds and returns the final MessageEmbed. Validates all constraints.

Returns: The completed MessageEmbed

Throws:

• IllegalStateException if embed is empty, too long, or has too many fields (max 25)

MessageEmbed completed = embed.build();
channel.sendMessageEmbeds(completed).queue();

Constants

ZERO_WIDTH_SPACE

A zero-width space character used for blank fields.

String space = EmbedBuilder.ZERO_WIDTH_SPACE;

Complete Example

import net.dv8tion.jda.api.EmbedBuilder;
import java.awt.Color;
import java.time.Instant;

public class EmbedExample {
    public void sendWelcomeEmbed(MessageChannel channel, Member member) {
        EmbedBuilder embed = new EmbedBuilder()
            .setTitle("Welcome to the Server!", "https://discord.com")
            .setDescription("We're glad to have you here.")
            .setColor(Color.GREEN)
            .setAuthor(member.getEffectiveName(), null, member.getAvatarUrl())
            .setThumbnail(member.getGuild().getIconUrl())
            .addField("Member Count", String.valueOf(member.getGuild().getMemberCount()), true)
            .addField("Join Date", member.getTimeJoined().format(DateTimeFormatter.ISO_LOCAL_DATE), true)
            .setFooter("Welcome!", member.getJDA().getSelfUser().getAvatarUrl())
            .setTimestamp(Instant.now());
        
        channel.sendMessageEmbeds(embed.build()).queue();
    }
}

Limits

• Title: 256 characters
• Description: 4096 characters
• Fields: Maximum 25 fields
• Field Name: 256 characters
• Field Value: 1024 characters
• Footer: 2048 characters
• Author: 256 characters
• Total Length: 6000 characters (for bots)
• URLs: 2048 characters

See Also

• MessageEmbed
• Message Sending
• Discord Embed Visualizer