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

# Phrase & Regex

> Hashbot supports two filter types: phrase (literal match) and regex (pattern match). Here's when to use each.

### The Simple Version

**Phrase** = exactly what you typed, found anywhere in the name. Nothing is "special."

**Regex** = a mini search language where certain characters have magic powers.

<Note>
  Both types are **case-sensitive** by default, and both match **anywhere** in the name (substring match).
</Note>

### When They Behave the Same

For plain words with no special characters, phrase and regex are identical:

| Username      | Phrase: `house` | Regex: `house` |
| ------------- | :-------------: | :------------: |
| `house`       |      match      |      match     |
| `houseparty`  |      match      |      match     |
| `treehouse99` |      match      |      match     |
| `HOUSE`       |     no match    |    no match    |

No difference here because `house` has no special regex characters.

### When It Actually Matters

The difference shows up when your filter contains characters that are **special in regex**: `. [ ] ( ) + * ? ^ $ |`

**Example: filtering the name `[evil]`**

* **Phrase: `[evil]`** --- matches the literal text `[evil]`. Brackets are just brackets.
* **Regex: `[evil]`** --- brackets have meaning in regex. `[evil]` means "any single character: e, v, i, or l." So it matches `Steve`, `olive`, `Bill` --- not what you wanted.

**Example: filtering `crazy.guy`**

* **Phrase: `crazy.guy`** --- matches exactly `crazy.guy`
* **Regex: `crazy.guy`** --- the `.` means "any character", so it also matches `crazy-guy`, `crazy guy`, `crazy3guy`

<Tip>
  **Rule of thumb:** if you're filtering an exact word or phrase, use **Phrase**. If you need pattern flexibility (case-insensitive, anchoring, alternatives), use **Regex**.
</Tip>

### What Regex Can Do That Phrase Can't

| Goal               | Regex Pattern | What It Does                             |
| ------------------ | ------------- | ---------------------------------------- |
| Case-insensitive   | `(?i)house`   | Matches `house`, `HOUSE`, `HoUsE`        |
| Starts with        | `^house`      | Matches `houseparty` but NOT `treehouse` |
| Ends with          | `house$`      | Matches `treehouse` but NOT `houseparty` |
| Exact full name    | `^house$`     | ONLY matches `house`, nothing else       |
| Alternatives       | `house\|home` | Matches `house` OR `home`                |
| Character variants | `[a@]dmin`    | Matches `admin` and `@dmin`              |

### Which One Should You Use?

<CardGroup cols={2}>
  <Card title="Use Phrase" icon="font">
    * Filtering exact words or names
    * Your filter contains special characters you want matched literally (brackets, dots, etc.)
    * You want simple, safe, no-surprises matching
    * **90% of filters should be phrase**
  </Card>

  <Card title="Use Regex" icon="code">
    * You need case-insensitive matching (`(?i)`)
    * You want to anchor to start/end of name (`^`, `$`)
    * You need to match character variants (`[a@4]dmin`)
    * You need alternatives (`support|help`)
  </Card>
</CardGroup>

### Emergency Pause

If a filter causes widespread issues, pause all actions immediately:

* Pause Hashbot: `/settings pause pause-state:pause`
* Resume after review: `/settings pause pause-state:unpause`

<Warning>
  Use the pause feature if you see false positives affecting users.
</Warning>

### Need Help?

Regex can be complex. If you're unsure:

[**Join our Support Discord**](https://discord.gg/hashbot) and open a ticket.
We're happy to help review, fix, or write regex filters tailored to your needs.