> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloombot.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed syntax

> Build rich messages in Bloom: the embed format, URL buttons, message content, and Discord's embed limits.

Many Bloom features let you compose a rich message: saved embeds, welcome and booster messages, level up announcements, and more. This is the reference for the format you write to build them.

## The embed format

Bloom uses one format for embeds, written as `$e{...}` blocks. The same format works everywhere Bloom builds an embed: saved embeds, welcome and booster messages, level up announcements, automatic messages, and sticky messages. Learn it once and it applies across all of them.

You write one `$e{...}` block per property, and you can place them in any order, one after another.

```text theme={null}
$e{title: Server rules}$e{description: Be kind and follow Discord's terms.}$e{color: #6E8CAB}
```

### Preview it instantly

The fastest way to learn the format is `embedview`, which renders whatever code you give it and works in a server or in a direct message.

<ParamField path="embedview <embed_code>" type="prefix command">
  Renders an embed from the code you provide. Aliases: `ev`. No special permission is needed; Bloom needs Send Messages and Embed Links.
</ParamField>

```text theme={null}
!embedview $e{title: Hello}$e{description: Line one\nLine two}$e{color: #1DB954}
```

Bloom replies with the finished embed: a title, a two line description, and a green side bar. Nothing is saved.

### Embed properties

Each property is a separate `$e{...}` block.

| Property      | Example                                    | Notes                                               |
| ------------- | ------------------------------------------ | --------------------------------------------------- |
| `title`       | `$e{title: Welcome}`                       | The bold heading.                                   |
| `description` | `$e{description: First line\nSecond line}` | The main text. Use `\n` for a line break.           |
| `color`       | `$e{color: #6E8CAB}`                       | A hex color or a color name.                        |
| `footer`      | `$e{footer: Read the rules}`               | Small text at the bottom.                           |
| `thumbnail`   | `$e{thumbnail: https://example.com/i.png}` | Small image in the corner. Must be an http(s) URL.  |
| `image`       | `$e{image: https://example.com/b.png}`     | Large image below the text. Must be an http(s) URL. |
| `author`      | `$e{author: Staff team}`                   | Small text above the title.                         |
| `timestamp`   | `$e{timestamp: true}`                      | Adds the current time to the footer.                |
| `field`       | `$e{field: Name\|Value\|true}`             | A titled field. See below.                          |

### Fields

A field has a name, a value, and an optional inline flag, separated by the pipe character `|`.

```text theme={null}
$e{field: Rules|No spam, be respectful|false}
```

* The first part is the field name.
* The second part is the field value.
* The third part is `true` to place the field inline (side by side with other inline fields) or `false` for a full width field. If you leave it out, the field is not inline.

### Message content outside the embed

Text you want to appear as a normal message above the embed goes in a `{message: ...}` block. Welcome and level up messages use this to mention the member.

```text theme={null}
{message: Welcome to the server!}$e{title: Read the rules}$e{description: Check #rules before posting.}
```

### URL buttons

Add link buttons under the embed with `$btn{...}`. Each button has a label and a URL.

```text theme={null}
$e{title: Get started}$btn{label: Join the community|url: https://discord.gg/HYSgTQ6SHR}$btn{label: Open the dashboard|url: https://dash.bloombot.cloud/}
```

* The label may contain spaces and needs no quotes.
* The URL must start with `http://` or `https://`. Buttons with an invalid URL are skipped.
* Buttons are laid out automatically at 5 per row.

<Info>
  These are link buttons only. They open a URL when clicked. Interactive buttons that trigger Bloom actions are configured through their own features, not through `$btn`.
</Info>

### A complete example

```text theme={null}
!embedview {message: Welcome to the server!}$e{title: Welcome}$e{description: Glad to have you.\nRead the rules before posting.}$e{color: #6E8CAB}$e{field: First step|Introduce yourself in #general|true}$e{timestamp: true}$btn{label: Read the rules|url: https://example.com/rules}
```

Bloom replies with a greeting line, followed by an embed that has a title, a two line description, a blue side bar, one inline field, a timestamp, and a link button.

<Info>
  Many features let you use variables inside an embed, such as `{user}` in a welcome message. The available variables depend on the feature you are configuring. Level up messages, for example, use the [level up variables](/configuration/leveling#level-up-variables).
</Info>

## Saving and reusing embeds

Use the `embed` command to store an embed under a name and send it later.

<ParamField path="embed" type="prefix command">
  Creates, lists, and sends saved embeds. Alias: `embeds`. You need Manage Messages; Bloom needs Send Messages and Embed Links.

  * `!embed create <name> <embed_code>` saves an embed. The name may contain only lowercase letters, numbers, and underscores.
  * `!embed list` lists the saved embeds.
  * `!embed send <name> [#channel]` sends a saved embed, to the current channel or a named channel.
  * `!embed delete <name>` deletes a saved embed.
  * `!embed syntax` shows a short syntax reminder.
</ParamField>

```text Save then send theme={null}
!embed create rules $e{title: Server rules}$e{description: Be kind and follow Discord's terms.}
!embed send rules #welcome
```

The first command stores the embed as `rules`. The second posts it in `#welcome`.

## Extracting and building embeds

<ParamField path="embedcode [message_url]" type="prefix command">
  Reads an existing message and returns its `$e{...}` code, so you can copy an embed you already posted. Aliases: `ecode`, `ecd`. Reply to a message or pass its link.
</ParamField>

<ParamField path="embedcreator" type="prefix command">
  Opens an interactive builder that previews the embed as you edit and exports the final code. Aliases: `ec`, `createembed`, `embedcreate`, `makeembed`.
</ParamField>

<ParamField path="componentview <component_code>" type="prefix command">
  Renders a Components V2 layout written in the `$c{...}` format, a separate and more advanced format from embeds. Run `!componentview syntax` for its grammar. Alias: `compview`.
</ParamField>

<Warning>
  The `componentview` command also has the short alias `cv`, but `cv` is claimed by another command as well. Use `componentview` or `compview` to be sure you get the component viewer.
</Warning>

## Colors and defaults

If you do not set a `color`, Bloom uses the server's configured embed color. If the server has not set one, the saved embed builder falls back to `#95ACC6`.

<Info>
  Different Bloom features fall back to different colors when none is set, so the safest practice is to include an explicit `color` in any embed where the exact color matters.
</Info>

## Discord embed limits

Embeds are a Discord feature, and Discord enforces these limits. Bloom builds within them, and Discord rejects an embed that exceeds them.

| Element               | Limit            |
| --------------------- | ---------------- |
| Title                 | 256 characters   |
| Description           | 4,096 characters |
| Fields                | 25 per embed     |
| Field name            | 256 characters   |
| Field value           | 1,024 characters |
| Footer text           | 2,048 characters |
| Author name           | 256 characters   |
| Embeds per message    | 10               |
| Total across an embed | 6,000 characters |

## Related pages

<CardGroup cols={2}>
  <Card title="Leveling" icon="chart-line" href="/configuration/leveling">
    Level up messages accept `$e{...}` embed templates.
  </Card>

  <Card title="Using prefix commands" icon="keyboard" href="/getting-started/commands">
    How to run `embed` and the preview commands.
  </Card>
</CardGroup>