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

# Notify

> Learn about SimpleCloud's notify plugin for real-time server and group notifications

## Overview

Notify sends MiniMessage-formatted chat notifications to permitted staff when server and group state changes happen in your SimpleCloud network.

<Note>
  This plugin depends on the `simplecloud-api` platform plugin and uses MiniMessage
  for text formatting. See the [MiniMessage
  documentation](https://docs.papermc.io/adventure/minimessage/) for formatting
  syntax.
</Note>

## Supported Software

| Software   | Plugin Support |
| ---------- | -------------- |
| Velocity   | Yes            |
| BungeeCord | Yes            |

## Quick Setup

1. Download the plugin from [GitHub](https://github.com/simplecloudapp/notify-plugin/releases).
2. Place it in your proxy template's `plugins/` folder.
3. Make sure the `simplecloud-api` plugin is installed on the proxy.
4. Start the proxy once to generate `messages.yml`.
5. Edit `plugins/notify-velocity/messages.yml` or `plugins/notify-bungeecord/messages.yml`.

## Notifications

Notify subscribes to the Cloud API event stream and can send messages for:

* Server state changes to `STARTING`, `AVAILABLE`, and `STOPPING`
* Server stopped events
* Group created events
* Group deleted events

Set a notification message to `null` to disable that specific notification. Set the whole `notifications.server` or `notifications.group` section to `null` to disable that category.

## Configuration

The generated `messages.yml` contains message text, reusable variables, and formatting options:

```yaml theme={null}
version: "1"

format:
  date: "dd.MM.yyyy HH:mm:ss"

variables:
  prefix: "<color:#0EA5E9><bold>⚡</bold></color>"

notifications:
  hover:
    server: |-
      <#E2E8F0>Server information
      <br><#94A3B8>Time<#475569>: <#E2E8F0><time>
      <br><#94A3B8>State<#475569>: <#E2E8F0><state>
      <br><#94A3B8>Address<#475569>: <#E2E8F0><ip>:<port>
      <br><#94A3B8>Players<#475569>: <#E2E8F0><players>/<max>
    group: |-
      <#E2E8F0>Group information
      <br><#94A3B8>Time<#475569>: <#E2E8F0><time>

  server:
    starting: "<prefix> <#0EA5E9>Server <hover:show_text:'<notifications.hover.server>'><#F8FAFC><server></hover> is now starting."
    available: "<prefix> <#A3E635>Server <hover:show_text:'<notifications.hover.server>'><#F8FAFC><server></hover> is now available."
    stopping: "<prefix> <#F59E0B>Server <hover:show_text:'<notifications.hover.server>'><#F8FAFC><server></hover> is now stopping."
    stopped: "<prefix> <#DC2626>Server <hover:show_text:'<notifications.hover.server>'><#F8FAFC><server></hover> is now stopped."

  group:
    created: "<prefix> <#0EA5E9>Group <hover:show_text:'<notifications.hover.group>'><#F8FAFC><group></hover> was created."
    deleted: "<prefix> <#DC2626>Group <hover:show_text:'<notifications.hover.group>'><#F8FAFC><group></hover> was deleted."
```

## Placeholders

### Server Notifications

| Placeholder     | Description                                     |
| --------------- | ----------------------------------------------- |
| `<server>`      | Group or server base name                       |
| `<group>`       | Group name                                      |
| `<id>`          | Numerical ID prefixed with a space when present |
| `<uuid>`        | Server UUID                                     |
| `<state>`       | Current server state                            |
| `<ip>`          | Server IP address                               |
| `<port>`        | Server port                                     |
| `<players>`     | Current player count                            |
| `<max>`         | Maximum players                                 |
| `<time>`        | Current timestamp using `format.date`           |
| `<updated>`     | Last update timestamp using `format.date`       |
| `<create_date>` | Creation timestamp using `format.date`          |

### Group Notifications

| Placeholder | Description                           |
| ----------- | ------------------------------------- |
| `<group>`   | Group name                            |
| `<time>`    | Current timestamp using `format.date` |

## Permissions

| Permission                      | Description                       |
| ------------------------------- | --------------------------------- |
| `notify.state.server.starting`  | Receive server starting messages  |
| `notify.state.server.available` | Receive server available messages |
| `notify.state.server.stopping`  | Receive server stopping messages  |
| `notify.state.server.stopped`   | Receive server stopped messages   |
| `notify.state.group.created`    | Receive group created messages    |
| `notify.state.group.deleted`    | Receive group deleted messages    |

<Note>
  The permission check happens per notification. Give staff only the event
  categories they should receive.
</Note>

<Note>
  `notify.state.server.deleted` is still accepted as a legacy alias for stopped-server notifications.
</Note>