# variables - placeholders & functions

A comprehensive list of variables and placeholders available in littlebot for use in autoresponders, custom messages, and function parameters.

---

## Placeholder List

### User / Author Information

| Placeholder | Example Output | Description |
|---|---|---|
| `{user}` | `JennyBot#0001` | The username and discriminator of the user |
| `{user_name}` | `JennyBot` | The username of the user without discriminator |
| `{user_id}` | `395526710101278721` | The user ID |
| `{user_mention}` | `<@395526710101278721>` | A mention of the user |
| `{user_avatar}` | `https://cdn.discordapp.com/...` | The user's avatar URL |
| `{user_created}` | `2021-05-15` | The account creation date |
| `{user_status}` | `online` | The user's current status (online, idle, dnd, offline) |
| `{user_activity}` | `Playing Minecraft` | The user's current activity |
| `{user_color}` | `#FF0000` | The user's top role color |
| `{user_balance}` | `5000` | User's balance (if applicable) |

**Advanced Usage:** User information can be extended to retrieve specific user data:
- `{user_name:395526710101278721}` - Get the name of a specific user by ID
- `{user_mention:[$1]}` - Get a mention of the first argument

---

### Server / Guild Information

| Placeholder | Example Output | Description |
|---|---|---|
| `{server}` | `Jensy's Domain` | The server name |
| `{server_id}` | `395526710101278721` | The server ID |
| `{server_icon}` | `https://cdn.discordapp.com/...` | The server icon URL |
| `{server_owner}` | `JennyBot#0001` | The server owner's username |
| `{server_owner_id}` | `395526710101278721` | The server owner's ID |
| `{server_created}` | `2020-01-15` | The server creation date |
| `{server_members}` | `150` | Total member count |
| `{server_members_online}` | `45` | Currently online members count* |
| `{server_bots}` | `12` | Number of bots in the server* |
| `{server_channels}` | `25` | Total channel count |
| `{server_roles}` | `8` | Total role count |
| `{server_region}` | `us-west` | The server's voice region |
| `{server_boost_tier}` | `2` | Server boost tier level |
| `{server_boost_count}` | `15` | Number of boosts |

*Due to Discord's constraints with intents, these values may be unreliable for non-premium servers since October 2020.

---

### Member Information

| Placeholder | Example Output | Description |
|---|---|---|
| `{member_name}` | `JennyBot` | The member's nickname or username |
| `{member_joined}` | `2021-06-20` | When the member joined the server |
| `{member_roles}` | `Moderator, Developer` | Member's roles (comma-separated) |
| `{member_top_role}` | `Moderator` | The member's highest role |
| `{member_avatar}` | `https://cdn.discordapp.com/...` | Member's avatar URL |

---

### Channel Information

| Placeholder | Example Output | Description |
|---|---|---|
| `{channel}` | `#general` | The channel name with # symbol |
| `{channel_name}` | `general` | The channel name without # |
| `{channel_id}` | `395526710101278721` | The channel ID |
| `{channel_created}` | `2020-01-15` | Channel creation date |
| `{channel_topic}` | `General discussion` | The channel topic/description |
| `{channel_type}` | `text` | Channel type (text, voice, stage, forum) |
| `{channel_nsfw}` | `false` | Whether the channel is NSFW |
| `{channel_mention}` | `<#395526710101278721>` | A mention of the channel |

---

### Message Information

| Placeholder | Example Output | Description |
|---|---|---|
| `{message}` | `Hello world!` | The full message content |
| `{message_id}` | `395526710101278721` | The message ID |
| `{message_url}` | `https://discord.com/channels/...` | Direct link to the message |
| `{message_created}` | `2024-05-15 14:30:00` | Message creation timestamp |
| `{message_attachments}` | `2` | Number of attachments |

---

### Miscellaneous

| Placeholder | Example Output | Description |
|---|---|---|
| `{prefix}` | `jen` | The current server prefix |
| `{bot_name}` | `littlebot` | The bot's username |
| `{bot_version}` | `1.0.0` | Bot version (if set) |
| `{timestamp}` | `1621080600` | Current Unix timestamp |
| `{now}` | `2024-05-15 14:30:00` | Current date and time |
| `{random}` | `42` | Random number (0-100) |
| `{random:1-10}` | `7` | Random number in specified range |
| `{mention_count}` | `2` | Number of mentions in message |

---

### Unique / Situational

Variables that only work in specific contexts:

| Variable | Usable In | Description |
|---|---|---|
| `{joined_member}` | Welcome messages | The member who just joined |
| `{left_member}` | Goodbye messages | The member who just left |
| `{promoted_role}` | Role updates | The role that was added |
| `{removed_role}` | Role updates | The role that was removed |
| `{target_user}` | Mod commands | The user being targeted (warn, ban, etc.) |
| `{reason}` | Mod commands | The reason provided for moderation |
| `{duration}` | Temporary actions | Duration of temporary action |

---

## Function List

### Formatting and Redirecting

| Function | Syntax | Example | Description |
|---|---|---|---|
| Embed | `{embed:title\|description\|color}` | `{embed:Hello\|This is an embed\|FF0000}` | Creates an embed message |
| Uppercase | `{upper:text}` | `{upper:{user_name}}` | Converts text to uppercase |
| Lowercase | `{lower:text}` | `{lower:{user_name}}` | Converts text to lowercase |
| Mention | `{mention:user_id}` | `{mention:395526710101278721}` | Creates a mention from a user ID |
| Link | `{link:text\|url}` | `{link:Click here\|https://example.com}` | Creates a formatted link |
| Role Mention | `{role_mention:role_id}` | `{role_mention:395526710101278721}` | Creates a role mention |
| Channel Mention | `{channel_mention:channel_id}` | `{channel_mention:395526710101278721}` | Creates a channel mention |

---

### Auto-Deletions

| Function | Syntax | Example | Description |
|---|---|---|---|
| Delete Trigger | `{delete_trigger:5}` | `{delete_trigger:5}` | Deletes trigger message after N seconds |
| Delete Response | `{delete_response:10}` | `{delete_response:10}` | Deletes bot response after N seconds |
| Delete Both | `{delete_both:5\|10}` | `{delete_both:5\|10}` | Deletes both after specified seconds |

---

### Conditional Logic

| Function | Syntax | Example | Description |
|---|---|---|---|
| If | `{if:condition\|true_text\|false_text}` | `{if:{user_status}==online\|Online!\|Offline}` | Conditional output based on condition |
| Choice | `{choice:option1\|option2\|option3}` | `{choice:Hello\|Hi\|Hey}` | Randomly selects one option |
| Range | `{range:1-10}` | `{range:1-5}` | Random number in range |

---

### Advanced Functions

| Function | Syntax | Description |
|---|---|---|
| Locked Choice | `{locked:key\|option1\|option2}` | Returns the same choice for the same key |
| User Arguments | `{$1}`, `{$2}`, etc. | Accesses command arguments by position |
| Contains | `{contains:text\|substring}` | Checks if text contains substring |
| Replace | `{replace:text\|find\|replace}` | Replaces occurrences in text |
| Math | `{math:expression}` | Evaluates math expressions (1+1, 10/2, etc.) |

---

## Escaping Placeholders

To prevent a placeholder from being replaced, use a backslash before it:

```
\{user} will display as {user} instead of showing the username
```

---

## Usage Tips

- **Combining placeholders:** Mix multiple placeholders: `{user_mention} welcome to {server}!`
- **Nesting functions:** `{upper:{user_name}}`
- **Conditional messages:** Use `{if:}` to create context-aware responses
- **Random responses:** Use `{choice:}` for variety in automated messages
- **Advanced usage:** Refer to specific guides for ranges, locked choices, and matchmodes

---

**Last Updated:** 2024-05-31  
**Bot Version:** littlebot