Package net.dv8tion.jda.api

Class EmbedBuilder

java.lang.Object
net.dv8tion.jda.api.EmbedBuilder
public class EmbedBuilder extends Object
Builder system used to build MessageEmbeds.
A visual breakdown of an Embed and how it relates to this class is available at Embed Overview.
Since:
3.0
Author:
John A. Grosh

  • Field Details

  • Constructor Details

    • EmbedBuilder

      public EmbedBuilder()
      Constructs a new EmbedBuilder instance, which can be used to create MessageEmbeds. These can then be sent to a channel using MessageChannel.sendMessageEmbeds(MessageEmbed, MessageEmbed...).
      Every part of an embed can be removed or cleared by providing null to the setter method.

    • EmbedBuilder

      public EmbedBuilder(@Nullable EmbedBuilder builder)
      Creates an EmbedBuilder using fields from an existing builder
      Parameters:
      builder - the existing builder

    • EmbedBuilder

      public EmbedBuilder(@Nullable MessageEmbed embed)
      Creates an EmbedBuilder using fields in an existing embed.
      Parameters:
      embed - the existing embed

  • Method Details

    • fromData

      @Nonnull public static EmbedBuilder fromData(@Nonnull DataObject data)
      Creates an instance of this builder from the provided DataObject.

      This is the inverse of MessageEmbed.toData().

      Parameters:
      data - The serialized embed object
      Returns:
      The new builder instance
      Throws:
      IllegalArgumentException - If the provided data is null or invalid
      ParsingException - If the provided data is malformed

    • build

      @Nonnull public MessageEmbed build()
      Returns a MessageEmbed that has been checked as being valid for sending.
      Returns:
      the built, sendable MessageEmbed
      Throws:
      IllegalStateException -

    • clear

      @Nonnull 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

    • copyFrom

      public void copyFrom(@Nullable EmbedBuilder builder)
      Copies the data from the given builder into this builder.
      All the parts of the given builder will be applied to this one.
      Parameters:
      builder - the existing builder

    • copyFrom

      public void copyFrom(@Nullable MessageEmbed embed)
      Copies the data from the given embed into this builder.
      All the parts of the given embed will be applied to this builder.
      Parameters:
      embed - the existing embed

    • 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()
      Checks whether the constructed MessageEmbed is within the limits for a bot account.
      Returns:
      True, if the length is less or equal to 6000
      See Also:

    • setTitle

      @Nonnull public EmbedBuilder setTitle(@Nullable 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:
      IllegalArgumentException -

    • setTitle

      @Nonnull public EmbedBuilder setTitle(@Nullable String title, @Nullable String url)
      Sets the Title of the embed.
      You can provide null as url if no url should be used.
      If you want to set a URL without a title, use setUrl(String) instead.

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

    • setUrl

      @Nonnull public EmbedBuilder setUrl(@Nullable String url)
      Sets the URL of the embed.
      The Discord client mostly only uses this property in combination with the title for a clickable Hyperlink.

      If multiple embeds in a message use the same URL, the Discord client will merge them into a single embed and aggregate images into a gallery view.

      Returns:
      the builder after the URL has been set
      Throws:
      IllegalArgumentException -
      • If the character limit for url, defined by MessageEmbed.URL_MAX_LENGTH as 2000, is exceeded.
      • If the provided url is not a properly formatted http or https url.
      See Also:

    • getDescriptionBuilder

      @Nonnull public 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

      @Nonnull public final EmbedBuilder setDescription(@Nullable 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:
      IllegalArgumentException - If description is longer than 4096 characters, as defined by MessageEmbed.DESCRIPTION_MAX_LENGTH

    • appendDescription

      @Nonnull public EmbedBuilder appendDescription(@Nonnull 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:
      IllegalArgumentException -

    • setTimestamp

      @Nonnull public EmbedBuilder setTimestamp(@Nullable 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

      @Nonnull public EmbedBuilder setColor(@Nullable 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

      @Nonnull 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:

    • setThumbnail

      @Nonnull public EmbedBuilder setThumbnail(@Nullable String url)
      Sets the Thumbnail of the embed.

      Example

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

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 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");
 channel.sendFiles(FileUpload.fromData(file, "cat.png")).setEmbeds(embed.build()).queue();
      Parameters:
      url - the url of the thumbnail of the embed
      Returns:
      the builder after the thumbnail has been set
      Throws:
      IllegalArgumentException -
      • If the character limit for url, defined by MessageEmbed.URL_MAX_LENGTH as 2000, is exceeded.
      • If the provided url is not a properly formatted http or https url.

    • setImage

      @Nonnull public EmbedBuilder setImage(@Nullable String url)
      Sets the Image of the embed.

      Example

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

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 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");
 channel.sendFiles(FileUpload.fromData(file, "cat.png")).setEmbeds(embed.build()).queue();
      Parameters:
      url - the url of the image of the embed
      Returns:
      the builder after the image has been set
      Throws:
      IllegalArgumentException -
      • If the character limit for url, defined by MessageEmbed.URL_MAX_LENGTH as 2000, is exceeded.
      • If the provided url is not a properly formatted http or https url.
      See Also:

    • setAuthor

      @Nonnull public EmbedBuilder setAuthor(@Nullable 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
      Throws:
      IllegalArgumentException - If name is longer than 256 characters, as defined by MessageEmbed.AUTHOR_MAX_LENGTH

    • setAuthor

      @Nonnull public EmbedBuilder setAuthor(@Nullable String name, @Nullable 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:
      IllegalArgumentException -

    • setAuthor

      @Nonnull public EmbedBuilder setAuthor(@Nullable String name, @Nullable String url, @Nullable 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.sendFiles(...)) you can reference said image using the specified filename as URI attachment://filename.ext.

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 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");
 channel.sendFiles(FileUpload.fromData(file, "cat.png")).setEmbeds(embed.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:
      IllegalArgumentException -

    • setFooter

      @Nonnull public EmbedBuilder setFooter(@Nullable String text)
      Sets the Footer of the embed without icon.

      Example

      Parameters:
      text - the text of the footer of the embed. If this is not set or set to null, the footer will not appear in the embed.
      Returns:
      the builder after the footer has been set
      Throws:
      IllegalArgumentException - If text is longer than 2048 characters, as defined by MessageEmbed.TEXT_MAX_LENGTH

    • setFooter

      @Nonnull public EmbedBuilder setFooter(@Nullable String text, @Nullable String iconUrl)
      Sets the Footer of the embed.

      Example

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

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 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");
 channel.sendFiles(FileUpload.fromData(file, "cat.png")).setEmbeds(embed.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:
      IllegalArgumentException -

    • addField

      @Nonnull public EmbedBuilder addField(@Nullable 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

      @Nonnull public EmbedBuilder addField(@Nonnull String name, @Nonnull 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 of 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:
      IllegalArgumentException -

    • addBlankField

      @Nonnull 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

      @Nonnull 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

      @Nonnull public 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