Package net.dv8tion.jda.api

Class 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 Embed Overview.
    Since:
    3.0
    Author:
    John A. Grosh

    • 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​(@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 Detail

      • build

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

        @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

      • setTitle

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

      • setTitle

        @Nonnull
public EmbedBuilder setTitle​(@Nullable
                             java.lang.String title,
                             @Nullable
                             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 -

      • getDescriptionBuilder

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

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

      • appendDescription

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

      • setTimestamp

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

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

      • setThumbnail

        @Nonnull
public EmbedBuilder setThumbnail​(@Nullable
                                 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
 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.sendFile(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:
        java.lang.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
                             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
 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.sendFile(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:
        java.lang.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:
        MessageChannel.sendFile(...)

      • setAuthor

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

      • setAuthor

        @Nonnull
public EmbedBuilder setAuthor​(@Nullable
                              java.lang.String name,
                              @Nullable
                              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 -

      • setAuthor

        @Nonnull
public EmbedBuilder setAuthor​(@Nullable
                              java.lang.String name,
                              @Nullable
                              java.lang.String url,
                              @Nullable
                              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
 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.sendFile(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:
        java.lang.IllegalArgumentException -

      • setFooter

        @Nonnull
public EmbedBuilder setFooter​(@Nullable
                              java.lang.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:
        java.lang.IllegalArgumentException - If text is longer than 2048 characters, as defined by MessageEmbed.TEXT_MAX_LENGTH

      • setFooter

        @Nonnull
public EmbedBuilder setFooter​(@Nullable
                              java.lang.String text,
                              @Nullable
                              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
 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.sendFile(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:
        java.lang.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​(@Nullable
                             java.lang.String name,
                             @Nullable
                             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 -

      • addBlankField

        @Nonnull
public EmbedBuilder addBlankField​(boolean inline)
        Adds a blank (empty) Field to the embed.

        Example of Inline

        Example if 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 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