> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/addon-api/getting-started/internal-api/embeds.md).

# Embeds

This page explains how to work with the internal Embed API.

## Embed API

Embeds are a beautiful way to enhance your plugin with clean, professional-looking message designs. Athena’s API provides three custom pre-built embed types.

***

### Error embeds

Error embeds are primarily used inside `try-catch` blocks. To generate an error embed, use the following snippet:

```js
const errorEmbed = this.heart.core.util.discord.generateErrorEmbed(`${userMention(interaction.user.id)}, something went wrong!`);
interaction.reply({ embeds: [errorEmbed] });
```

The `.generateErrorEmbed()` function returns an [EmbedBuilder](https://discord.js.org/docs/packages/builders/main/EmbedBuilder:Class) instance. The text you pass in becomes the description of the error embed preset.

***

### Warning embeds

Warning embeds are the correct way to inform the command or interaction executor that they cannot proceed. Typical use cases include:

* The user does not have permission to use a panel.
* The command can only be executed in ticket channels.
* Any other situation where the command cannot be executed.

```js
const warnEmbed = this.heart.core.util.discord.generateWarnEmbed(`${userMention(interaction.user.id)}, this command can only be run in tickets!`);
interaction.reply({ embeds: [warnEmbed] });
```

The `.generateWarnEmbed()` function returns an [EmbedBuilder](https://discord.js.org/docs/packages/builders/main/EmbedBuilder:Class) instance. The text you pass in becomes the description of the warning embed preset.

***

### Other embeds

Not every message should be an error or warning. This embed type is used for general information, notifications, and other messages that do not fall under those categories.

```js
const embedConfiguration = {
  title: 'Test',
  description: 'Hello World, I\'m testing my first placeholder here %test%. The command was executed by %userId%',
  color: 'red',
  defaultFooter: true,
  defaultTimestamp: true,
  guildIcon: true,
  userIcon: true,
};

const placeholders = {
  test: 'Placeholder 1',
  userId: interaction.user.id,
};

const embed = this.heart.core.util.discord.resolveEmbed(embedConfiguration, placeholders, interaction.guild, interaction.user);
interaction.reply({ embeds: [embed] });
```

The embed configuration follows the official Embed JSON representation. Athena provides four additional custom fields to extend the embed functionality:

* `defaultFooter`: If set to `true`, the time when the embed is generated is used as the timestamp.
* `defaultFooter`: If set to `true`, the default footer text from your `common.json` config is used.
* `guildIcon`: If set to `true` and a guild instance is provided, the guild icon is displayed in the embed thumbnail.
* `userIcon`: If set to `true` and a user instance is provided, the user avatar is displayed in the embed thumbnail.

Placeholders can be used by writing `%placeholder_name%` in any field such as the title or description. This is extremely useful if you want to make your messages configurable through your configuration file.

Athena also provides additional default placeholders that work in every embed rendered by `.resolveEmbed()`:

* `%custom_emoji_<number>%`
* `%user%`
* `%user_display%`
* `%user_id%`
* `%user_mention%`
* `%user_icon%`
* `%user_created%`
* `%user_created_formatted%`
* `%user_joined%`
* `%user_joined_formatted%`
* `%guild%`
* `%guild_id%`
* `%guild_icon%`
* `%random_int_<max_number>%`
* `%random_string_<length>%`
* `%current_date%`
* `%current_time%`
* `%current_time_seconds%`
* `%current_datetime%`
* `%current_iso%`

> All `%user_...%` placeholders only work if a user instance is provided to `.resolveEmbed()`. The same applies to `%guild_...%` placeholders and a guild instance.