Embeds

If you have been around on Discord for a bit chances are you have seen these special messages. They have a colored border, are often sent by bots and have embedded images, text fields and other fancy stuff.

In the following section we will explain how you compose an embed, send it, and what you need to be aware of while doing so.

Embed preview

Here is an example of what an embed may look like. We will go over their construction in the next part of this guide.

Tutorial Bot
Tutorial Bot Bot 06/25/2019
Some description here
Regular field title
Some value here
Inline field title
Some value here
Inline field title
Some value here
Inline field title
Some value here

Using the RichEmbed constructor

Discord.js features the utility class RichEmbed for easy construction and manipulation of embeds.

// at the top of your file
const Discord = require('discord.js');

// inside a command, event listener, etc.
const exampleEmbed = new Discord.RichEmbed()
	.setColor('#0099ff')
	.setTitle('Some title')
	.setURL('https://discord.js.org/')
	.setAuthor('Some name', 'https://i.imgur.com/wSTFkRM.png', 'https://discord.js.org')
	.setDescription('Some description here')
	.setThumbnail('https://i.imgur.com/wSTFkRM.png')
	.addField('Regular field title', 'Some value here')
	.addBlankField()
	.addField('Inline field title', 'Some value here', true)
	.addField('Inline field title', 'Some value here', true)
	.addField('Inline field title', 'Some value here', true)
	.setImage('https://i.imgur.com/wSTFkRM.png')
	.setTimestamp()
	.setFooter('Some footer text here', 'https://i.imgur.com/wSTFkRM.png');

channel.send(exampleEmbed);

TIP

You don't need to include all the elements showcased above. If you want a simpler embed, just leave some out.

The .setColor() method accepts an integer, HEX color string, an array of RGB values or specific color strings. You can find a list of them at the Discord.js documentation.

.addBlankField() is a convenience method for .addField('\u200b', '\u200b') to add a spacer to the embed. This can also be used inline by passing true as the first parameter.

WARNING

On the master branch, the receiving and outgoing embed classes have been unified; you will need to use Discord.MessageEmbed() as constructor instead.

The above example chains the manipulating methods to the newly created RichEmbed object. This is possible because the return value of each manipulating method is the RichEmbed instance itself. If you want to modify the embed based on conditions you will need to reference it directly (as exampleEmbed for our example).

const exampleEmbed = new Discord.RichEmbed().setTitle('Some title');

if (message.author.bot) {
	exampleEmbed.setColor('#7289da');
}

Local images

To use local images inside your embed, you need to upload them alongside the embed with the .attachFiles() method. You can either provide the file path FileOptions, BufferResolvable, or Attachment objects inside an array.

You can then access and use the images inside the embed itself with attachment://fileName.extension.

const exampleEmbed = new Discord.RichEmbed()
	.setTitle('Some title')
	.attachFiles(['../assets/discordjs.png'])
	.setImage('attachment://discordjs.png');

channel.send(exampleEmbed);

WARNING

If the images doesn't display inside the embed but outside of it, double check your syntax to make sure it's as shown above.

Using an embed object

const exampleEmbed = {
	color: 0x0099ff,
	title: 'Some title',
	url: 'https://discord.js.org',
	author: {
		name: 'Some name',
		icon_url: 'https://i.imgur.com/wSTFkRM.png',
		url: 'https://discord.js.org',
	},
	description: 'Some description here',
	thumbnail: {
		url: 'https://i.imgur.com/wSTFkRM.png',
	},
	fields: [
		{
			name: 'Regular field title',
			value: 'Some value here',
		},
		{
			name: '\u200b',
			value: '\u200b',
		},
		{
			name: 'Inline field title',
			value: 'Some value here',
			inline: true,
		},
		{
			name: 'Inline field title',
			value: 'Some value here',
			inline: true,
		},
		{
			name: 'Inline field title',
			value: 'Some value here',
			inline: true,
		},
	],
	image: {
		url: 'https://i.imgur.com/wSTFkRM.png',
	},
	timestamp: new Date(),
	footer: {
		text: 'Some footer text here',
		icon_url: 'https://i.imgur.com/wSTFkRM.png',
	},
};

channel.send({ embed: exampleEmbed });

TIP

You don't need to include all the elements showcased above. If you want a simpler embed, just leave some out.

WARNING

The color field has to be an integer for embed objects! If you have a hex color string (e.g. '#7289da') you can replace the # with 0x to use it as a number: 0x7289da.

If you want to modify the embed object based on conditions you will need to reference it directly (as exampleEmbed for our example). You can then (re)assign the property values as you would with any other object.

const exampleEmbed = { title: 'Some title' };

if (message.author.bot) {
	exampleEmbed.color = 0x7289da;
}

Local images

To use local images inside your embed you need to construct an Attachment from them to send as message option alongside the embed.

You can then access and use the images inside the embed itself with attachment://fileName.extension.

const file = new Discord.Attachment('../assets/discordjs.png');

const exampleEmbed = {
	title: 'Some title',
	image: {
		url: 'attachment://discordjs.png',
	},
};

channel.send({ files: [file], embed: exampleEmbed });

WARNING

If the images doesn't display inside the embed but outside of it, double check your syntax to make sure it's as shown above.

Resending embeds

At some point in your bot development, you might want to get an embed from a message that you're receiving, edit it, and send it again.

To achieve this, you retrieve the embed from the messages embed array (message.embeds) and pass it to the RichEmbed constructor. The constructed RichEmbed can then be edited before sending it again.

WARNING

You cannot just resend the received embed structure! It's a MessageEmbed rather than a RichEmbed and contains circular references that prevent sending. While possible on the master branch due to above mentioned merge of RichEmbed and MessageEmbed it's still not recommended to edit the reference directly as this modifies the embed on the original Message in your bots cache as well and thus may lead to unexpected behaviour!

const receivedEmbed = message.embeds[0];
const exampleEmbed = new Discord.RichEmbed(receivedEmbed).setTitle('New title');

channel.send(exampleEmbed);

Notes

  • To display fields side-by-side, you need at least two consecutive fields set to inline
  • By default, up to 3 fields will display inline. If a thumbnail is set, this will change to 2
  • The timestamp will automatically adjust the timezone depending on the user's device
  • Mentions of any kind will only render correctly in field values and descriptions
  • Mentions in embeds will not trigger a notification
  • Embeds allow masked links (e.g. [Guide](https://discordjs.guide/ 'optional hovertext')), but only in description and field values

Embed limits

There are a few limits to be aware of while planning your embeds due to limitations set by the API. Here is a quick reference you can come back to:

  • Embed titles are limited to 256 characters
  • Embed descriptions are limited to 2048 characters
  • There can be up to 25 fields
  • A field's name is limited to 256 characters and its value to 1024 characters
  • The footer text is limited to 2048 characters
  • The author name is limited to 256 characters
  • In addition, the sum of all characters in an embed structure must not exceed 6000 characters
  • A bot can have 1 embed per message
  • A webhook can have 10 embeds per message

Source: Discord API documentation

Last Updated: 4/22/2019, 8:42:31 AM