> ## 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.

# Welcome messages

> Greet new members with a custom message when they join, built from a template or your own embed.

Bloom can send a custom welcome message to a channel whenever a new member joins your server. This page covers setting it up, writing the message, previewing it, and keeping the channel tidy.

<Info>
  Every server has its own command prefix. Throughout these docs, `!` stands for **your server's prefix**. The commands here need the **Administrator** permission.
</Info>

## How it works

A welcome message is sent whenever a new member joins. For it to send, **two** things must both be set:

* a **welcome channel**, and
* a **welcome message**, built from a template or your own embed code.

If either is missing, nothing is sent. Setting a channel or saving a message turns welcome messages on automatically, so once both exist, the next join is greeted.

<Info>
  A welcome message is the public greeting members see. It is separate from the join gate, which screens or verifies members before they are let in. Assigning roles on join and logging joins in a staff channel are also their own features, configured separately.
</Info>

## Defaults

| Setting          | Default      | Meaning                                                                      |
| ---------------- | ------------ | ---------------------------------------------------------------------------- |
| Welcome messages | On, but idle | Enabled by default, but nothing sends until a channel and a message are set. |
| Welcome channel  | Not set      | No channel, so no welcome is sent.                                           |
| Welcome message  | Not set      | No content configured yet.                                                   |
| Self-destruct    | Off          | Welcome messages stay in the channel.                                        |

## Quick start

<Steps>
  <Step title="Set the welcome channel">
    Run `!welcome #welcome`. Bloom confirms the channel and enables welcome messages. Bloom must be able to Send Messages and Embed Links there.
  </Step>

  <Step title="Choose a message">
    Run `!welcome template` to pick a ready-made design, or `!welcome paste` to supply your own embed code. Bloom previews it and asks you to confirm before saving.
  </Step>

  <Step title="Preview it">
    Run `!welcome test`. Bloom renders the message using your own account as the sample member, so you can see the result without waiting for a real join.
  </Step>
</Steps>

## Configuring the message

<ParamField path="welcome" type="Administrator">
  Configures the welcome message. Run with no argument to see the current status. Aliases: `setwelcome`, `welcomemsg`.

  * `!welcome #channel` sets the welcome channel (also accepts a channel ID or name) and enables welcome messages.
  * `!welcome template` lists ready-made designs and saves the one you pick.
  * `!welcome paste` prompts you to send your own embed code, previews it, and saves it on confirmation.
  * `!welcome test` previews the saved message using your account as the sample.
  * `!welcome enable` and `!welcome disable` turn welcome messages on or off without deleting the configuration.
  * `!welcome convert` upgrades a legacy message to the modern format (see below).
  * `!welcome selfdestruct <duration|off>` auto-deletes each welcome message after a delay.
</ParamField>

The message is written in the same `$e{...}` embed format used across Bloom, with variables that fill in the joining member's details. Use a `{message: ...}` block to send a line above the embed that actually pings the member.

```text A welcome that pings the member theme={null}
{message: Welcome {user.mention}!}$e{title: Welcome to {guild.name}}$e{description: You are member number {guild.members}. Read the rules before posting.}$e{thumbnail: {user.avatar}}$e{color: #55738F}
```

On the next join, Bloom posts a greeting line that mentions the member, followed by an embed with their avatar and the current member count. For the full embed format see the [Embed syntax reference](/reference/embeds); for every token you can use, see [Variables and placeholders](/reference/variables#welcome-messages).

### Set the channel only

<ParamField path="welcomechannel <#channel|none>" type="Administrator">
  Sets or clears just the welcome channel, without touching the message. Alias: `setwelcomechannel`. Use `none` to clear the channel and stop welcome messages.
</ParamField>

### Auto-delete welcome messages

<ParamField path="welcome selfdestruct <duration|off>" type="Administrator">
  Deletes each welcome message a set time after it is sent, to keep the channel clean.

  * **Accepted values:** a duration such as `30s`, `5m`, or `1h`. The minimum is 5 seconds and the maximum is 1 hour.
  * Use `off` to disable it, so welcome messages stay in the channel.
</ParamField>

### Legacy format and conversion

Bloom accepts two message formats. The **modern** format uses `$e{...}` blocks. An older **YAML** format writes one `key: value` per line. Both work, and `!welcome test` shows which one your current message uses.

<ParamField path="welcome convert" type="Administrator">
  Converts a saved YAML message to the modern `$e{...}` format, previews the result, and saves it on confirmation. Your original is left unchanged if you cancel.
</ParamField>

<Tip>
  If you are building a message from scratch, use the modern `$e{...}` format. It is the same format saved embeds use, so anything you learn on the [Embed syntax](/reference/embeds) page applies here too.
</Tip>

## Interactions with other features

* **Join gate.** Members who are rejected or still being verified by the join gate never trigger a welcome message, because the gate runs first.
* **Embeds and variables.** Welcome messages share the `$e{...}` [embed format](/reference/embeds) and the [welcome variables](/reference/variables#welcome-messages) with several other Bloom features, such as booster and level up messages.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No welcome message is sent when someone joins">
    A welcome needs both a channel and a message. Run `!welcome` to check the status. Confirm a channel is set, a message is saved, and welcome messages are enabled. Then confirm Bloom can Send Messages and Embed Links in that channel.
  </Accordion>

  <Accordion title="The message sends but does not ping the new member">
    Put the mention in a `{message: ...}` block, for example `{message: Welcome {user.mention}!}`, rather than only inside the embed. Bloom sends that block as normal text above the embed so the mention notifies the member.
  </Accordion>

  <Accordion title="The test shows blank spots that real joins fill in">
    `!welcome test` uses your own account as the sample. A few tokens, such as the member's join date and server nickname, only have a value during a real join, so they can appear blank in the test but work in practice.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Variables and placeholders" icon="hashtag" href="/reference/variables">
    Every token you can use in a welcome message and what it fills in.
  </Card>

  <Card title="Embed syntax" icon="code" href="/reference/embeds">
    The `$e{...}` format welcome messages are written in.
  </Card>

  <Card title="Invite and first setup" icon="rocket" href="/getting-started/first-setup">
    Add Bloom and set the basics before configuring welcome.
  </Card>

  <Card title="Leveling" icon="chart-line" href="/configuration/leveling">
    Another configurable Bloom system that shares the embed and variable format.
  </Card>
</CardGroup>