Package net.dv8tion.jda.api

Class 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

    • 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

      • 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

      • 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 -

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

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