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

# Welcome

> Welcome posts a greeting when a member joins the server. Configure the channel, format, and content, review a preview, then enable the module after the bot has the required permissions.

## Permissions and activation

Prefix subcommands require Administrator and run only in a server. The bot must view and send messages in the channel; embed format also requires **Embed Links**. `set-channel` checks those permissions, and `on` will not enable the module if the channel or a permission is missing. The member-join event can welcome new members, including bot accounts; delivery pauses while `Join Gate` is in raid state. The bot filter used for join logs does not by itself disable welcome delivery.

There are two activation controls: `.welcome on` enables the master module after validating the channel; `.welcome off` changes the legacy `welcome.enabled` indicator but does not change that master switch (`modules.welcome`). Because delivery checks the module switch, `.welcome off` alone does not guarantee that welcomes stop. To actually pause them, disable Welcome in the Dashboard or use `/welcome enabled:false`, which updates both controls.

> [!NOTE]
>
> `.welcome off` changes only the legacy indicator; it does not disable `modules.welcome`. To pause delivery, use the Dashboard or `/welcome enabled:false`. New default greetings are in English. When configuration is read, Headless translates only old built-in copy that matches exactly; each server's customized content, including Spanish copy, is preserved.

### `.welcome set-channel`

```headless-command Syntax theme={null}
.welcome set-channel <channel>
```

```headless-command Example theme={null}
.welcome set-channel #welcome
```

### `.welcome on`

```headless-command Syntax theme={null}
.welcome on
```

```headless-command Example theme={null}
.welcome on
```

### `.welcome`

```headless-command Syntax theme={null}
/welcome [channel:<channel>] [enabled:<enabled>]
```

```headless-command Example theme={null}
/welcome channel:#welcome enabled:true
```

**Note:**

Welcome keeps one configuration per server. Disabling the master toggle pauses future delivery; it does not erase the saved channel, copy, variables, or media. The indicator shown by `.welcome off` is legacy state and does not replace that toggle. `.welcome set-channel` may still require Embed Links when the saved format is text because its current validation checks the channel using the default embed format.

## Content and variables

The message can be plain text, a configured embed, or an embed script from the shared parser. Use welcome variables to inspect available keys; some belong to other events and may render as N/A. Welcome accepts links such as [label](https://...), the `{link:Label|https://...}` token, and channel mentions using `{channel:CHANNEL_ID}`. Preview renders a sample using the command author.

### `.welcome set-title`

```headless-command Syntax theme={null}
.welcome set-title <title>
```

```headless-command Example theme={null}
.welcome set-title Welcome, {user.display_name}!
```

### `.welcome set-message`

```headless-command Syntax theme={null}
.welcome set-message <message>
```

```headless-command Example theme={null}
.welcome set-message Welcome to {guild.name}
```

### `.welcome format`

```headless-command Syntax theme={null}
.welcome format [mode=embed]
```

```headless-command Example theme={null}
.welcome format embed
```

## Mentions and deletion

The optional new-member mention is sent outside the embed and can be toggled with `mention`. The send allows user mentions but blocks @everyone, @here, and role mentions. `autodelete 0` keeps the greeting; a positive integer schedules deletion of the welcome message. The Dashboard also has a separate control for deleting the mention; there is no prefix subcommand for that timer.

### `.welcome mention`

```headless-command Syntax theme={null}
.welcome mention <state> [message]
```

```headless-command Example theme={null}
.welcome mention on {user.mention}
```

## Buttons, images, and appearance

The Dashboard can save up to five URL buttons; prefix commands expose only three fixed slots: rules, support, and extra. The Dashboard publishes buttons only when both a label and a valid HTTPS URL are present; prefix subcommands accept http\://, https\://, or discord://. The Dashboard also exposes avatar, thumbnail, banner, GIF, color, footer, and author text. `set-banner` and `set-gif` accept a public URL or `off` to remove the media. In an embed, the GIF is used as the thumbnail unless a custom thumbnail is configured; the banner occupies the main image.

### `.welcome set-banner`

```headless-command Syntax theme={null}
.welcome set-banner <url>
```

```headless-command Example theme={null}
.welcome set-banner https://example.com/banner.png
```

### `.welcome button-rules`

```headless-command Syntax theme={null}
.welcome button-rules <url> [label]
```

```headless-command Example theme={null}
.welcome button-rules https://example.com/rules Rules
```

### `.welcome preview`

```headless-command Syntax theme={null}
.welcome preview
```

```headless-command Example theme={null}
.welcome preview
```

## Command scope

The `.welcome` group shows status. `/welcome` is also available with `channel` and `enabled` options to inspect or change the channel and master activation; for example, `/welcome enabled:false` disables it. Most content settings use prefix subcommands or the Dashboard.

## Steps

**1. Choose a channel**

Run .welcome set-channel #welcome. Resolve any permission reported by the diagnostic.

**2. Write and customize the greeting**

Set the title, message, and format; add media and buttons if needed.

**3. Test before enabling**

Run .welcome preview and check text, variables, image, mentions, and links.

**4. Enable or pause the module**

Run `.welcome on` after checking permissions. To pause delivery, use `/welcome enabled:false` or the Dashboard master toggle; `.welcome off` does not change that master switch.

> **Prefix commands**
>
> The default prefix is a period and can be changed per server. Commands: .welcome; .welcome set-channel #channel; .welcome on or off; .welcome set-title text; .welcome set-message text; .welcome variables; .welcome format embed|text; .welcome set-banner URL|off; .welcome set-gif URL|off; .welcome mention on|off \[text]; .welcome avatar on|off; .welcome buttons on|off; .welcome button-rules URL \[label]; .welcome button-support URL \[label]; .welcome button-extra URL \[label]; .welcome autodelete seconds; .welcome preview. Group alias: .bienvenida. Several subcommands also have aliases.

> **Options that do not change the safety policy**
>
> The .welcome autopin command is reserved and always keeps auto-pin disabled; it does not pin or modify messages. Use the server Dashboard to edit five buttons, the full visual fields, or the separate mention deletion timer.

## Configuration guidance

> **Setup**
>
> Choose the welcome channel, configure the message and buttons, and test with welcome preview.

> **Design**
>
> Keep the title short, the copy clear, and the rules button easy to recognize.

> **Common errors**
>
> Check channel permissions, validate the rules URL, and shorten messages that cannot be rendered.

## Related pages

* [Template variables](/docs/en/resources/scripting/variables.md)
* [Embed scripting](/docs/en/resources/scripting/embeds.md)
* [Auto Responders](/docs/en/server/auto-responders.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.