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

# Moderating Private Messages with SocialSpy and CmdSpy

> Use SocialSpy to monitor private conversations and CmdSpy to track player commands. Covers spy formats, sensitive masking, and persistent state.

PumpkinMsg gives your moderation team two complementary surveillance tools: SocialSpy for private conversations and CmdSpy for player commands. Both tools are non-intrusive to normal players, persist across server restarts, and respect your configured format strings so spy output always matches your server's visual style.

## SocialSpy

SocialSpy lets authorized staff members receive a copy of every private message exchanged on the network. Staff use `/socialspy` (alias `/spy`) to toggle the feature on or off. The permission required is `pumpkinmsg.staff.spy`.

### Global Mode vs. Player-Specific Mode

<Tabs>
  <Tab title="Global Mode">
    Running `/socialspy` with no argument toggles global mode. In global mode you receive a copy of every private message sent anywhere on the network.

    ```bash theme={null}
    /socialspy        # enable global spy
    /socialspy        # run again to disable
    ```

    When enabled you receive the confirmation:

    ```
    [Staff Spy] » Global mode enabled.
    ```
  </Tab>

  <Tab title="Player-Specific Mode">
    Running `/socialspy <player>` pins the feed to a single player. You only receive messages where that player appears as the sender or the recipient — all other conversations are invisible to you.

    ```bash theme={null}
    /socialspy Steve    # watch only Steve's conversations
    /spy Alex           # alias form
    ```

    When enabled you receive:

    ```
    [Staff Spy] » Watching: Steve.
    ```

    To stop watching a specific player, run `/socialspy` with no argument to disable spy entirely, then run `/socialspy` again with no argument to re-enable it in global mode.
  </Tab>
</Tabs>

### What Staff See

Each intercepted message is formatted using the `spy` string from `config.toml`:

```toml theme={null}
spy = "<#C678DD>[Spy] <sender_prefix><#61AFEF><sender> <#5C6370>-> <target_prefix><#61AFEF><target><#5C6370>: <#D19A66><message>"
```

The `<sender_prefix>` and `<target_prefix>` tokens are resolved via LuckPerms, so moderators can immediately identify the ranks of both participants. If LuckPerms is not installed, those tokens resolve to an empty string.

<Note>
  Both the sender and the recipient of a message are automatically excluded from the spy broadcast for that message — they already see their own conversation and do not receive a duplicate spy line.
</Note>

## CmdSpy

CmdSpy gives staff visibility into the commands players execute. The permission required is `pumpkinmsg.staff.cmdspy`. Use `/spycommands` (alias `/cmdspy`) to manage it.

### Scope Options

<Tabs>
  <Tab title="Paper (Single Server)">
    On a Paper server, `/spycommands` is a simple toggle. Running it once enables command monitoring for all players on that server. Running it again disables it.

    ```bash theme={null}
    /spycommands    # toggle on/off
    ```
  </Tab>

  <Tab title="Velocity (Proxy)">
    On Velocity you have granular control over which backend server to monitor.

    ```bash theme={null}
    /spycommands              # toggle global cmdspy
    /spycommands global       # explicitly watch all servers
    /spycommands survival     # watch only the "survival" server
    /spycommands off          # disable cmdspy entirely
    ```

    The `<server>` token in the `cmdspy` format string shows which server the command originated from, making it easy to filter your logs after the fact.
  </Tab>
</Tabs>

### Sensitive Command Masking

PumpkinMsg automatically masks commands that could expose player credentials. The following commands are **never** shown in CmdSpy output, regardless of who is watching:

* `/login`
* `/register`
* `/changepassword`

<Warning>
  This masking is enforced at the plugin level and cannot be disabled through configuration. It protects player account security no matter how staff configure their spy settings.
</Warning>

### CmdSpy Format

The output uses the `cmdspy` string from `config.toml`:

```toml theme={null}
cmdspy = "<#C678DD>[Cmd Spy] <player_prefix><#61AFEF><player> <#5C6370>used <white>/<command> <#5C6370>on <#E5C07B><server>"
```

## Message Delivery Flow

Understanding the order in which PumpkinMsg evaluates each condition helps you predict exactly what players and staff will see when a message is sent.

<Steps>
  <Step title="Check sender togglemsg">
    If the sender has run `/togglemsg` to disable their own outgoing messages, the plugin sends them `sender-toggled-off` and stops.
  </Step>

  <Step title="Check target is online">
    If the target player is offline or not found on the network, the plugin sends the sender `player-offline` and stops.
  </Step>

  <Step title="Check self-message">
    If the sender is targeting themselves, the plugin sends `cannot-msg-self` and stops.
  </Step>

  <Step title="Check target togglemsg (bypass)">
    If the target has disabled incoming messages via `/togglemsg`, the plugin sends `target-toggled-off` to the sender — unless the sender holds `pumpkinmsg.staff.bypass`, in which case delivery continues.
  </Step>

  <Step title="Check ignore list (bypass)">
    If the target has ignored the sender, the plugin sends `player-ignoring-you` — unless the sender holds `pumpkinmsg.staff.bypass`, in which case delivery continues.
  </Step>

  <Step title="Deliver message">
    The plugin formats and sends the `sender` string to the sender and the `receiver` string to the target, then records both players as each other's last-message partner for `/reply`.
  </Step>

  <Step title="Broadcast to spies">
    The plugin iterates over all online players who have SocialSpy active. Each spy receives the `spy` format string — unless they are the sender or the recipient of the message. If a spy has pinned their feed to a specific player, they only receive the broadcast if that player is involved in the current message.
  </Step>
</Steps>

## Persistent State

All spy, ignore, and togglemsg state is written to flat files in the `plugins/PumpkinMsg/` data folder whenever it changes. This means:

* A staff member's SocialSpy or CmdSpy session **survives proxy/server restarts**.
* A player's ignore list and togglemsg preference are **restored automatically** when they reconnect.

No manual backup of a database is needed — the flat files in the data folder are the entire state of the plugin.