Fossabot

https://docs.fossabot.com/
Admin
Fossabot is a Twitch chat bot that provides features to create an ultimate chat experience for...
Tokens:41,339
Snippets:677
Trust Score:8.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example Output for !uptime

Source: https://docs.fossabot.com/commands/default/uptime

Displays the duration the channel has been live.

```text
ChannelName has been live for 3 hours and 25 minutes
```

--------------------------------

### TFT variable output examples

Source: https://docs.fossabot.com/variables/teamfighttactics

Example outputs for successful queries and various error states.

```text
sujin#goat is currently Gold IV 0 LP
```

```text
[Error: Riot ID not found.]
```

```text
[Error: Summoner not found.]
```

```text
[Error: Summoner stats not found.]
```

--------------------------------

### Example output for recorded games

Source: https://docs.fossabot.com/variables/gamesplayed

Shows the format of the returned list of games.

```text
Grand Theft Auto V, Just Chatting
```

--------------------------------

### Example Output for $(botuptime)

Source: https://docs.fossabot.com/variables/botuptime

The format of the string returned by the $(botuptime) variable.

```text
3 days, 2 hours and 1 minute
```

--------------------------------

### Example output for default request

Source: https://docs.fossabot.com/variables/lastfm

The standard output format when only the username is provided.

```text
Fox Stevenson - Dreamland
```

--------------------------------

### Example output for $(downtime)

Source: https://docs.fossabot.com/variables/downtime

The format of the returned duration string.

```text
3 hours and 25 minutes
```

--------------------------------

### Example Output for !commands

Source: https://docs.fossabot.com/commands/default/commands

Displays the response provided by the bot after executing the command.

```text
Channel commands are available at: https://fossabot.com/channelname/commands
```

--------------------------------

### Example output of $(query)

Source: https://docs.fossabot.com/variables/query

The resulting output when a command is triggered with additional arguments.

```text
look at this cool text
```

--------------------------------

### Retrieve Username Output

Source: https://docs.fossabot.com/variables/user

Examples of the output returned by the $(user) variable.

```text
Aiden
```

```text
Fossabot
```

--------------------------------

### Create a new command

Source: https://docs.fossabot.com/commands/default/addcmd

Example of creating a basic command with a name and response text.

```text
!addcmd hello Welcome to my stream!
```

```text
Successfully added command "!hello"
```

--------------------------------

### Example Output for !game

Source: https://docs.fossabot.com/commands/default/game

Displays the output format when no play time is available.

```text
ChannelName is playing Just Chatting
```

--------------------------------

### Example Output for !followage

Source: https://docs.fossabot.com/commands/default/followage

Displays the follow duration when using the command with default or specified parameters.

```text
UserName has been following ChannelName for 2 years, 3 months, 15 days
```

```text
UserName1 has been following UserName2 for 1 year, 6 months, 2 days
```

--------------------------------

### Example Usage of !filesay

Source: https://docs.fossabot.com/commands/default/filesay

Executes the command by providing a URL to a text file.

```text
!filesay https://example.com/messages.txt
```

--------------------------------

### Example Output for !followdate

Source: https://docs.fossabot.com/commands/default/followdate

Displays the follow date when using the command with default or specified users.

```text
UserName followed ChannelName on Mon, 15 Mar 2021 14:30:22 UTC
```

```text
UserName1 followed UserName2 on Wed, 22 Jul 2020 09:15:45 UTC
```

--------------------------------

### Set Game Command Usage

Source: https://docs.fossabot.com/commands/default/setgame

Example of the command syntax and the resulting success message.

```text
!setgame Minecraft
```

```text
Changed game to "Minecraft"
```

--------------------------------

### Example output of !fact

Source: https://docs.fossabot.com/commands/default/fact

The expected response format when the command is invoked.

```text
A group of flamingos is called a "flamboyance"!
```

--------------------------------

### Example Output for !accountdate

Source: https://docs.fossabot.com/commands/default/accountdate

Displays the account creation date for the command sender or a specified user.

```text
UserName created their account on Mon, 06 Apr 2015 23:09:03 UTC
```

```text
UserName created their account on Tue, 10 Jul 2018 20:56:46 UTC
```

--------------------------------

### Usage Examples for $(followage)

Source: https://docs.fossabot.com/variables/followage

Demonstrates various ways to invoke the variable, including default channel usage and explicit parameter passing.

```text
Aiden has been following Fossabot for 9 days and 2 hours
```

```text
Aiden has been following Fossabot for 9 days and 2 hours
```

```text
Aiden has been following Fossabot for 9 days and 2 hours
```

--------------------------------

### Add a new custom command

Source: https://docs.fossabot.com/commands/default/cmd

Example output and usage error for creating a new command.

```text
Successfully added command "!hello"
```

```text
Usage: !cmd add <command> <response>
```

--------------------------------

### Example Output for !clear

Source: https://docs.fossabot.com/commands/default/clear

The confirmation message displayed after successfully clearing the queue.

```text
Cleared the current media request queue!
```

--------------------------------

### Example output for !dadjoke

Source: https://docs.fossabot.com/commands/default/dadjoke

The expected response format when the command is triggered.

```text
Why don't scientists trust atoms? Because they make up everything!
```

--------------------------------

### Example Output for !skip

Source: https://docs.fossabot.com/commands/default/skip

Displays the confirmation message returned when a track is successfully skipped.

```text
Skipped the currently playing track!
```

--------------------------------

### Example output for custom format request

Source: https://docs.fossabot.com/variables/lastfm

The output format when a custom string is provided.

```text
Dreamland by Fox Stevenson
```

--------------------------------

### Example Output for !game with Play Time

Source: https://docs.fossabot.com/commands/default/game

Displays the output format when play time and Steam integration are available.

```text
ChannelName is playing Minecraft (Play time: 2 hours and 15 minutes) | https://steamcommunity.com/app/123456
```

--------------------------------

### Repeat Variable Usage Example

Source: https://docs.fossabot.com/variables/repeat

Demonstrates the syntax for repeating a phrase multiple times.

```text
$(repeat 5 PogChamp Kappa)
```

--------------------------------

### Example output for !ping

Source: https://docs.fossabot.com/commands/default/ping

The response returned by the bot indicating its current uptime.

```text
Fossabot has been online for 2 days, 5 hours and 23 minutes!
```

--------------------------------

### Fetch weather data for a location

Source: https://docs.fossabot.com/variables/weather

Example usage of the $(weather) variable with a location parameter.

```text
$(weather London, UK)
```

--------------------------------

### Example Output for !gamesplayed

Source: https://docs.fossabot.com/commands/default/gamesplayed

Displays the format of the command output showing the date and a list of games with their respective durations.

```text
[29 Aug 2025]: Just Chatting (21m 56s), Metal Gear Solid 3 Snake Eater (2h 54m), SHINOBI: Art of Vengeance (31m 45s), Path of Exile 2 (3h 4m)
```

--------------------------------

### Create a Twitch Clip

Source: https://docs.fossabot.com/commands/default/clip

Examples of using the !clip command with and without an optional title.

```text
🎬 Clip created! https://clips.twitch.tv/HappyFunnyAmazingCoolMoment
```

```text
🎬 Clip created! https://clips.twitch.tv/HappyFunnyAmazingCoolMoment
```

--------------------------------

### Update command response

Source: https://docs.fossabot.com/commands/default/editcmd

Example of updating a command's response text.

```text
!editcmd hello Welcome to my amazing stream!
```

```text
Successfully updated command "!hello"
```

--------------------------------

### Delete a custom command

Source: https://docs.fossabot.com/commands/default/delcmd

Example of the command usage and the resulting success message.

```text
!delcmd hello
```

```text
Successfully deleted command "!hello"
```

--------------------------------

### Example Output for !voteskip

Source: https://docs.fossabot.com/commands/default/voteskip

Displays the response when a vote is cast and when the skip threshold is reached.

```text
Aiden voted to skip this track. 3 votes are required to skip!
```

```text
⏭️ skipping "Rick Astley - Never Gonna Give You Up"...
```

--------------------------------

### Edit an existing custom command

Source: https://docs.fossabot.com/commands/default/cmd

Example output and error handling for modifying an existing command.

```text
Successfully updated command "!hello"
```

```text
Usage: !cmd edit <command> <response>
```

```text
[Error: Command with that name or alias does not exist.]
```

--------------------------------

### Example output for the Mastodon variable

Source: https://docs.fossabot.com/variables/mastodon

Displays the status content, URL, and time elapsed since the post.

```text
👋 - https://mastodon.social/@fossabot/109838109407056375 | 4 minutes and 53 seconds ago
```

--------------------------------

### Usage of $(fromindex) with fallback

Source: https://docs.fossabot.com/variables/fromindex

Example of using the variable with a fallback response when no arguments are provided.

```text
$(fromindex2 this is a fallback response)
```

--------------------------------

### Example Output for !eightball

Source: https://docs.fossabot.com/commands/default/eightball

Displays the successful response format when a question is provided to the command.

```text
the magic 8-ball says... It is decidedly so! 🎱  
```

--------------------------------

### URL Encode Input Example

Source: https://docs.fossabot.com/variables/urlencode

Demonstrates the basic usage of the urlencode variable to transform a string into a URL-safe format.

```text
my+example+input
```

--------------------------------

### Example Output for !votekick

Source: https://docs.fossabot.com/commands/default/votekick

Displays the message shown in chat when a vote kick poll is successfully initiated.

```text
Aiden has started a poll to remove UserName from chat. Vote in chat by typing VoteYea or VoteNay!
```

--------------------------------

### Retrieve FrankerFaceZ Emotes

Source: https://docs.fossabot.com/variables/ffzemotes

Examples of using the $(ffzemotes) variable with and without a specific username.

```text
POGGERS PepoDance OMEGALUL  
```

```text
MONKERS PepePls pepePoint  
```

--------------------------------

### Example Output for !wrongsong

Source: https://docs.fossabot.com/commands/default/wrongsong

Displays the confirmation message returned when a track is successfully removed from the queue.

```text
Removed "Rick Astley - Never Gonna Give You Up" from the media request queue
```

--------------------------------

### Retrieve League of Legends Player Stats

Source: https://docs.fossabot.com/variables/leagueoflegends

Example usage of the variable to fetch rank and LP for a specific player.

```text
$(leagueoflegends kr Hide on bush#KR1)
```

```text
Hide on bush is currently Grandmaster I 789 LP
```

--------------------------------

### Calculate time until a future date

Source: https://docs.fossabot.com/variables/countdown

Example usage of the countdown variable with a standard date format.

```text
$(countdown 2030-01-01 00:00:00)
```

```text
7 years, 11 months, 14 days and 9 hours
```

--------------------------------

### Get Request Context

Source: https://docs.fossabot.com/variables/customapi

Endpoint to retrieve detailed data about an incoming request.

```http
GET https://api.fossabot.com/v2/customapi/context/<token>
```

--------------------------------

### $(channel.provider)

Source: https://docs.fossabot.com/variables/channel

Returns the platform a broadcaster's account was created on.

```APIDOC
## $(channel.provider)

### Description
Returns the platform a broadcaster's account was created on (i.e. twitch).

### Parameters
This variable does not take any parameters.

### Example Output
twitch
```

--------------------------------

### Set Game Dynamically

Source: https://docs.fossabot.com/variables/setgame

Use this syntax to allow the command to accept the game name as an argument.

```text
$(setgame)
```

```text
Changed game to "Grand Theft Auto V"
```

--------------------------------

### !cmd add

Source: https://docs.fossabot.com/commands/default/cmd

Creates a new custom command for the channel.

```APIDOC
## !cmd add

### Description
Creates a new custom command for the channel. This command is restricted to Broadcasters and Moderators.

### Parameters
- **Command name** (string) - Required - The name of the command to create
- **Response** (string) - Required - The response text for the command

### Flags
- **--enable** (flag) - Optional - Enable the command (default: enabled)
- **--disable** (flag) - Optional - Disable the command
- **-g, --global <seconds>** (integer) - Optional - Set global cooldown in seconds (default: 5)
- **-u, --user <seconds>** (integer) - Optional - Set user cooldown in seconds (default: 15)
- **-n, --name <name>** (string) - Optional - Set command name
- **-t, --type <type>** (string) - Optional - Set response type: reply, say, whisper, or mention (default: say)
- **--addalias <alias>** (string) - Optional - Add an alias for the command
- **--removealias <alias>** (string) - Optional - Remove an alias from the command
```

--------------------------------

### Command Show Usage and Error Messages

Source: https://docs.fossabot.com/commands/default/cmd

Displays usage instructions when the command name is missing or an error message if the command does not exist.

```text
Usage: !cmd show <command>
```

```text
[Error: Command with that name or alias does not exist.]
```

--------------------------------

### Unsupported Platform Error

Source: https://docs.fossabot.com/commands/default/filesay

Returned when the command is executed on a platform that does not support it.

```text
Filesay is not supported on this platform.
```

--------------------------------

### !cmd set

Source: https://docs.fossabot.com/commands/default/cmd

Creates or updates a custom command with a specified response and optional configuration flags.

```APIDOC
## !cmd set

### Description
Creates or updates a custom command. If the command doesn't exist, it will be created. If it does exist, it will be updated.

### Parameters
- **Command name** (string) - Required - The name of the command to create or update
- **Response** (string) - Required - The response text for the command

### Flags
- `--enable` - Optional - Enable the command (default: enabled)
- `--disable` - Optional - Disable the command
- `-g, --global <seconds>` - Optional - Set global cooldown in seconds (default: 5)
- `-u, --user <seconds>` - Optional - Set user cooldown in seconds (default: 15)
- `-n, --name <name>` - Optional - Set command name
- `-t, --type <type>` - Optional - Set response type: `reply`, `say`, `whisper`, or `mention` (default: say)
- `--addalias <alias>` - Optional - Add an alias for the command
- `--removealias <alias>` - Optional - Remove an alias from the command
```

--------------------------------

### Retrieve Channel Creation Date

Source: https://docs.fossabot.com/variables/channel

Returns the account creation date in UTC.

```text
$(channel.accountsince)
```

```text
Mon, 06 Apr 2015 23:09:03 UTC
```

--------------------------------

### Retrieve broadcaster platform

Source: https://docs.fossabot.com/variables/channel

Returns the platform name where the account was created.

```text
$(channel.provider)
```

--------------------------------

### Invoke a custom command with references

Source: https://docs.fossabot.com/variables/references

Executes a command by name. Requires the command name as a parameter.

```text
$(references hello)
```

--------------------------------

### Get redeemer position for message sender

Source: https://docs.fossabot.com/variables/twitchreward

Returns the queue position for the user who triggered the command.

```text
$(twitchreward.redeemer_position Play a game of VALORANT with me!)
```

```text
2
```

--------------------------------

### Calculate time with timezone offset

Source: https://docs.fossabot.com/variables/countdown

Example usage of the countdown variable including a specific timezone offset.

```text
$(countdown Jan 01 2030 00:00:00 GMT-0400)
```

```text
7 years, 11 months, 14 days and 13 hours
```

--------------------------------

### $(sender.provider)

Source: https://docs.fossabot.com/variables/sender

Returns the platform of the sender.

```APIDOC
## $(sender.provider)

### Description
Returns the platform the sender sent the message from (e.g., twitch).

### Parameters
- None
```

--------------------------------

### Command Set Usage Error

Source: https://docs.fossabot.com/commands/default/cmd

Displayed when the required command name or response parameters are missing.

```text
Usage: !cmd set <command> <response>
```

--------------------------------

### Get redeemer position for specific user

Source: https://docs.fossabot.com/variables/twitchreward

Returns the queue position for a specific user identified by username or ID.

```text
$(twitchreward.redeemer_position.aiden Play a game of VALORANT with me!)
```

```text
2
```

```text
$(twitchreward.redeemer_position.87763385 Play a game of VALORANT with me!)
```

```text
2
```

--------------------------------

### Retrieve command argument with fallback

Source: https://docs.fossabot.com/variables/indexes

Demonstrates using the index variable to fetch the second argument with a fallback string.

```text
$(index2 this is a fallback response)
```

--------------------------------

### GET /v2/customapi/context/<token>

Source: https://docs.fossabot.com/variables/customapi

Retrieves detailed data about an incoming customapi request, such as channel information and message content.

```APIDOC
## GET /v2/customapi/context/<token>

### Description
Retrieves detailed data about an incoming customapi request.

### Method
GET

### Endpoint
https://api.fossabot.com/v2/customapi/context/<token>

### Parameters
#### Path Parameters
- **token** (string) - Required - The token associated with the request context.

### Response
#### Success Response (200)
- **channel** (object) - Information about the channel.
- **message** (object|null) - Information about the message content, or null if dispatched from an automated action.
```

--------------------------------

### Usage of !commands

Source: https://docs.fossabot.com/commands/default/commands

Executes the command to retrieve the channel commands URL.

```text
!commands
```

--------------------------------

### $(customapi) Variable

Source: https://docs.fossabot.com/variables/customapi

The $(customapi) variable executes an HTTP GET request to a provided URL and returns the raw response body.

```APIDOC
## $(customapi)

### Description
Returns the response of an HTTP GET request to a specified URL. The variable ignores status codes and returns the raw body content.

### Parameters
- **URL** (string) - Required - The URL to send the HTTP GET request to.

### Error Handling
- If an invalid URL is provided or the remote server cannot be reached, it returns: `[Error: Failed to connect to remote server.]`

### Custom Headers
Fossabot includes several headers in the request, such as:
- `x-fossabot-channelid`: The internal Fossabot ID of the broadcaster.
- `x-fossabot-channellogin`: The lowercase username of the broadcaster.
- `x-fossabot-customapitoken`: A unique token for request identification.
- `user-agent`: Set to `Fossabot Web Proxy`.
```

--------------------------------

### Retrieve current song with custom format

Source: https://docs.fossabot.com/variables/lastfm

Fetches the currently playing song using a custom format string with placeholders.

```text
$(lastfm aiden {songname} by {artist})
```

--------------------------------

### Output with arguments

Source: https://docs.fossabot.com/variables/fromindex

The result returned when the command is triggered with arguments.

```text
test2 test3
```

--------------------------------

### Calculate time elapsed from UTC date

Source: https://docs.fossabot.com/variables/countup

Example usage for calculating time passed since January 1st, 2022 in UTC.

```text
$(countup 2022-01-01 00:00:00)
```

```text
17 days, 13 hours and 15 minutes
```

--------------------------------

### GET /v2/customapi/validate/<token>

Source: https://docs.fossabot.com/variables/customapi

Validates that a customapi request originated from Fossabot. This is a single-use endpoint; subsequent calls with the same token will return an error.

```APIDOC
## GET /v2/customapi/validate/<token>

### Description
Validates that a customapi request originated from Fossabot. This is a single-use endpoint.

### Method
GET

### Endpoint
https://api.fossabot.com/v2/customapi/validate/<token>

### Parameters
#### Path Parameters
- **token** (string) - Required - The single-use token provided by the request.

### Response
#### Success Response (200)
- **context_url** (string) - The URL to retrieve additional request context.

#### Response Example
{
    "context_url": "https://api.fossabot.com/v2/customapi/context/<token>"
}
```

--------------------------------

### $(channel)

Source: https://docs.fossabot.com/variables/channel

Returns the lowercase version of the broadcaster's username (login).

```APIDOC
## $(channel)

### Description
Returns the lowercase version of a broadcaster's username (login).

### Parameters
None.

### Example Output
fossabot
```

--------------------------------

### Calculate time elapsed with timezone offset

Source: https://docs.fossabot.com/variables/countup

Example usage for calculating time passed since January 1st, 2022 using an EDT timezone offset.

```text
$(countup Jan 01 2022 00:00:00 GMT-0400)
```

```text
17 days, 9 hours and 15 minutes
```

--------------------------------

### $(valorant.leaderboard_placement)

Source: https://docs.fossabot.com/variables/valorant

Returns the current position of the broadcaster on their Ranked Leaderboard.

```APIDOC
## $(valorant.leaderboard_placement)

### Description
Returns the current position of the broadcaster on their Ranked Leaderboard. Note that data may be stale for up to 30 minutes due to Riot Games API limitations.

### Parameters
None.

### Example Output
122

### Error Output
- If not on leaderboard: [Error: Could not find player on any VALORANT leaderboards.]
- If not authorized: [Error: The broadcaster must first link their Riot Games account in fossabot.com -> integrations.]
```

--------------------------------

### $(channel.accountsince)

Source: https://docs.fossabot.com/variables/channel

Returns the date of the broadcaster's Twitch account creation in UTC.

```APIDOC
## $(channel.accountsince)

### Description
Returns the date when a broadcaster created their Twitch account in coordinated universal time (UTC).

### Parameters
None.

### Example Output
Mon, 06 Apr 2015 23:09:03 UTC
```

--------------------------------

### !cmd enable

Source: https://docs.fossabot.com/commands/default/cmd

Enables a disabled custom command.

```APIDOC
## !cmd enable

### Description
Enables a disabled custom command.

### Parameters
- **command name** (string) - Required - The name of the command to enable.

### Example Output
`Successfully enabled "!hello"`

### Error Output
- If no name provided: `Usage: !cmd enable <command>`
- If command not found: `[Error: Command with that name or alias does not exist.]`
- If already enabled: `[Error: Command is already enabled!]`
```

--------------------------------

### Execute !songqueue command

Source: https://docs.fossabot.com/commands/default/songqueue

Usage of the !songqueue command to retrieve the media request queue link.

```text
!songqueue
```

```text
View the current media request queue: https://fossa.bot/channelname/mediarequest
```

--------------------------------

### !cmd show

Source: https://docs.fossabot.com/commands/default/cmd

Displays the response text associated with a specific custom command.

```APIDOC
## !cmd show

### Description
Displays the response of a custom command.

### Parameters
- **Command name** (string) - Required - The name of the command to show
```

--------------------------------

### $(setgame)

Source: https://docs.fossabot.com/variables/setgame

Updates the stream game directory to the specified game name.

```APIDOC
## $(setgame)

### Description
Changes the currently played game on the stream. If a game name is provided, it updates the directory to that game; otherwise, it may clear or reset the status depending on implementation.

### Parameters
- **game** (string) - Optional - The name of the game to set the stream directory to.

### Usage Examples
- `$(setgame)`: Used in a command to set the game based on user input.
- `$(setgame Grand Theft Auto V)`: Hardcoded usage to set the game to a specific title.

### Response
- Success: "Changed game to \"[Game Name]\""
- Error: "[Error: Game does not exist on Twitch.]"
```

--------------------------------

### Error Output for !followage

Source: https://docs.fossabot.com/commands/default/followage

Displays various error messages returned when the command fails due to invalid input or relationship status.

```text
Error: You cannot follow yourself
```

```text
Error: Invalid username
```

```text
Error: One or more users not found
```

```text
UserName is not following ChannelName
```

--------------------------------

### $(game) / $(game.name)

Source: https://docs.fossabot.com/variables/game

Retrieves the current game directory for a specified broadcaster. $(game) is an alias for $(game.name).

```APIDOC
## $(game) / $(game.name)

### Description
Returns the currently playing game of a given broadcaster. Defaults to the current broadcaster if no username is provided.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch the game for.

### Example Output
$(game) -> "Just Chatting"
$(game fossabot) -> "<no game>"

### Error Output
- [Error: User not found.]
- [Error: Invalid username.]
```

--------------------------------

### $(user.provider)

Source: https://docs.fossabot.com/variables/user

Returns the platform a user sent the message from.

```APIDOC
## $(user.provider)

### Description
Returns the platform a user sent the message from (e.g., twitch).

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the sender if not provided.

### Example Output
`$(user.provider)` -> `twitch`
`$(user.provider fossabot)` -> `twitch`

### Error Output
`[Error: Invalid username.]`
```

--------------------------------

### $(user.accountsince)

Source: https://docs.fossabot.com/variables/user

Returns the specific date and time a Twitch account was created.

```APIDOC
## $(user.accountsince)

### Description
Returns the date when a user created their Twitch account in coordinated universal time (UTC).

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the sender if not provided.

### Response
- **Success** - Returns a date string in UTC format (e.g., "Mon, 06 Apr 2015 23:09:03 UTC").
```

--------------------------------

### Display User Metadata in Commands

Source: https://docs.fossabot.com/variables/user

Use user members to display dynamic information about the command sender.

```text
Shout out to $(user.display_name)! Go follow them at twitch.tv/$(user.login) - they were last seen playing $(user.game)!
```

```text
Shout out to Aiden! Go follow them at twitch.tv/aiden - they were last seen playing Just Chatting!
```

--------------------------------

### Perform basic addition with $(math)

Source: https://docs.fossabot.com/variables/math

Evaluates a simple arithmetic expression.

```text
$(math 1 + 1)
```

```text
2
```

--------------------------------

### $(user.uptime)

Source: https://docs.fossabot.com/variables/user

Returns the time that has passed since a user's stream has gone live.

```APIDOC
## $(user.uptime)

### Description
Returns the time that has passed since a user's stream has gone live.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the sender if not provided.

### Response
- **Success**: Returns the uptime duration string.
- **Error**: Returns '[Error: Invalid username.]' if the username is invalid or '[Error: Stream is offline.]' if the stream is not live.
```

--------------------------------

### Handle user not found error

Source: https://docs.fossabot.com/commands/default/accountage

Output returned when the specified user cannot be found.

```text
Error: User not found  
```

--------------------------------

### $(botuptime)

Source: https://docs.fossabot.com/variables/botuptime

Returns the uptime of the current broadcaster's Fossabot shard.

```APIDOC
## $(botuptime)

### Description
Returns the uptime of the current broadcaster's Fossabot shard. Note that this value may vary between channels and can reset if the system migrates the channel to a different server.

### Parameters
This variable does not take any parameters.

### Example Output
`3 days, 2 hours and 1 minute`
```

--------------------------------

### Successful command output

Source: https://docs.fossabot.com/variables/references

The expected output when referencing a valid command.

```text
Hello Fossabot!
```

--------------------------------

### Retrieve user provider

Source: https://docs.fossabot.com/variables/user

Returns the platform name for the specified user or the message sender.

```text
twitch
```

```text
twitch
```

```text
[Error: Invalid username.]
```

--------------------------------

### $(fromindex)

Source: https://docs.fossabot.com/variables/fromindex

Returns all arguments provided after a specified argument index following a command name. If no arguments are found at the specified index, it returns the provided fallback response.

```APIDOC
## $(fromindex)

### Description
Returns all arguments provided after a specified argument index following a command name. If no arguments are provided after the index, the optional fallback response is returned.

### Parameters
- **index** (integer) - Required - The position index of the arguments to start returning from.
- **fallback response** (string) - Optional - The text to return if no arguments are found after the specified index.

### Example Usage
Command: `!verycoolname`
Response: `$(fromindex 2 this is a fallback response)`

- Input: `!verycoolname test1 test2 test3` -> Output: `test2 test3`
- Input: `!verycoolname` -> Output: `this is a fallback response`

### Error Handling
- If no arguments are found after the index and no fallback response is provided, returns: `[Error: Index <index> is not in arguments.]`
```

--------------------------------

### Display Custom Command Response

Source: https://docs.fossabot.com/commands/default/cmd

Retrieves and displays the configured response for a specific custom command.

```text
Response for [!hello]: Welcome to my stream!
```

--------------------------------

### Execute !clear command

Source: https://docs.fossabot.com/commands/default/clear

Usage of the command to clear the media request queue.

```text
!clear
```

--------------------------------

### Handle insufficient parameters

Source: https://docs.fossabot.com/commands/default/editcmd

Error message displayed when the required command and response parameters are missing.

```text
Usage: !editcmd <command> <response>
```

--------------------------------

### Handle $(ffzemotes) Error States

Source: https://docs.fossabot.com/variables/ffzemotes

Common error messages returned when the variable fails to fetch emote data.

```text
[Error: FrankerFaceZ API returned an error.]  
```

```text
[Error: Twitch API returned an error.]  
```

```text
[Error: User not found.]  
```

--------------------------------

### Retrieve current game directory

Source: https://docs.fossabot.com/variables/game

Fetches the game name for the broadcaster or a specified user.

```text
Just Chatting
```

```text
<no game>
```

--------------------------------

### $(user.login)

Source: https://docs.fossabot.com/variables/user

Returns the lowercase version of a user's username (login).

```APIDOC
## $(user.login)

### Description
Returns the lowercase version of a user's username (login).

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the sender if not provided.

### Example Output
`$(user.login)` -> `aiden`
`$(user.login fossabot)` -> `fossabot`

### Error Output
`[Error: Invalid username.]`
```

--------------------------------

### $(user)

Source: https://docs.fossabot.com/variables/user

Retrieves the display name of a user. If no parameter is provided, it defaults to the command sender.

```APIDOC
## $(user)

### Description
Returns the display name of a user. This variable can be used to fetch metadata for the command sender or a specified Twitch username.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the command sender if omitted.

### Example Usage
- `$(user)`: Returns the display name of the command sender.
- `$(user fossabot)`: Returns the display name of the user 'fossabot'.

### Error Handling
- If an invalid username is provided, returns: `[Error: Invalid username.]`
```

--------------------------------

### Usage of $(query) in command response

Source: https://docs.fossabot.com/variables/query

Place the variable in a command response to echo the arguments provided by the user.

```text
$(query)
```

--------------------------------

### Retrieve Twitch account creation date

Source: https://docs.fossabot.com/variables/user

Returns the UTC date of account creation. Defaults to the command sender if no username is provided.

```text
$(user.accountsince)
```

```text
Mon, 06 Apr 2015 23:09:03 UTC  
```

```text
$(user.accountsince fossabot)
```

```text
Tue, 10 Jul 2018 20:56:46 UTC  
```

--------------------------------

### $(followage)

Source: https://docs.fossabot.com/variables/followage

Returns the time that has passed since a user followed a broadcaster.

```APIDOC
## $(followage)

### Description
Returns the time that has passed since a user followed a broadcaster.

### Parameters
- **user** (string) - Optional - The Twitch username of the user in question.
- **broadcaster** (string) - Optional - The Twitch username of the broadcaster being followed.

### Example Usage
- `$(followage)`: Returns follow duration for the current user in the current channel.
- `$(followage aiden)`: Returns follow duration for 'aiden' in the current channel.
- `$(followage aiden fossabot)`: Returns follow duration for 'aiden' following 'fossabot'.

### Error Handling
- [Error: <user> is not following <broadcaster>.]
- [Error: One or more users not found.]
- [Error: Invalid username.]
- [Error: You cannot follow yourself.]
```

--------------------------------

### $(uptime)

Source: https://docs.fossabot.com/variables/uptime

Retrieves the time elapsed since a stream went live. If no username is provided, it defaults to the current broadcaster.

```APIDOC
## $(uptime)

### Description
Returns the time that has passed since a user's stream has gone live.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch the uptime for. Defaults to the current broadcaster if not provided.

### Usage Examples
- `$(uptime)`: Returns uptime for the current broadcaster.
- `$(uptime fossabot)`: Returns uptime for the specified user.

### Response
- **Success**: Returns a string representing the duration (e.g., "3 hours and 25 minutes").
- **Error**: Returns "[Error: Stream is offline.]" if the stream is not live.
```

--------------------------------

### Execute !filesaystop command

Source: https://docs.fossabot.com/commands/default/filesaystop

Usage of the command in chat to stop a filesay operation.

```text
!filesaystop
```

--------------------------------

### Retrieve full charity campaign details

Source: https://docs.fossabot.com/variables/charity

Returns a formatted string containing the charity name, description, and website.

```text
St Jude ChildCare Centres UK: St Jude India ChildCare Centres UK provides cost-free accommodation and holistic care to help disadvantaged children survive cancer. - https://www.stjudechild.org
```

```text
[Error: No campaign active.]
```

--------------------------------

### $(user.game)

Source: https://docs.fossabot.com/variables/user

Returns the current Twitch directory/game for a specified Twitch user.

```APIDOC
## $(user.game)

### Description
Returns the current Twitch directory a user is under. Defaults to the command sender if no username is provided.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for.

### Example Output
- `$(user.game)` -> Just Chatting
- `$(user.game fossabot)` -> <no game>

### Error Output
- [Error: Invalid username.]
```

--------------------------------

### Invalid volume error

Source: https://docs.fossabot.com/commands/default/volume

Displays usage instructions when an invalid volume value is provided.

```text
Usage: !volume <0-100>
```

--------------------------------

### Error Output for !followdate

Source: https://docs.fossabot.com/commands/default/followdate

Displays various error messages returned when the command fails due to invalid input or missing data.

```text
Error: You cannot follow yourself
```

```text
Error: Invalid username
```

```text
Error: One or more users not found
```

```text
UserName is not following ChannelName (or Fossabot does not have access to this broadcasters' following list)
```

--------------------------------

### $(sender.game)

Source: https://docs.fossabot.com/variables/sender

Returns the current Twitch directory/game of the sender.

```APIDOC
## $(sender.game)

### Description
Returns the current Twitch directory the sender is under.

### Parameters
- None
```

--------------------------------

### $(youtube)

Source: https://docs.fossabot.com/variables/youtube

Retrieves the latest YouTube video for a given channel or playlist identifier.

```APIDOC
## $(youtube)

### Description
Returns the latest YouTube video of a channel or a playlist.

### Parameters
- **identifier** (string) - Required - The channel name, channel ID, or playlist ID (prefixed with 'playlist=' for playlists).

### Usage Examples
- `$(youtube xqcow)`
- `$(youtube UCmDTrq0LNgPodDOFZiSbsww)`
- `$(youtube playlist=PLKeR9CeyAc9brDTtmz6DcCQpy5mA6m9AK)`

### Error Handling
If an invalid identifier is provided or the API fails, the variable returns: `[Error: YouTube API returned an error.]`
```

--------------------------------

### Insufficient parameters error

Source: https://docs.fossabot.com/commands/default/addcmd

The output displayed when the command is invoked without the required name and response parameters.

```text
Usage: !addcmd <command> <response>
```

--------------------------------

### $(charity.website)

Source: https://docs.fossabot.com/variables/charity

Returns the charity website URL.

```APIDOC
## $(charity.website)

### Description
Returns the website URL of the charity.

### Parameters
- None

### Response
- Success: String containing the website URL.
- Error: `[Error: No campaign active.]` if no campaign is running.
```

--------------------------------

### Create or Update a Custom Command

Source: https://docs.fossabot.com/commands/default/cmd

Use this command to define or modify a custom command response. The command name and response text are required parameters.

```text
Successfully added command "!hello"
```

```text
Successfully updated command "!hello"
```

--------------------------------

### Usage error output

Source: https://docs.fossabot.com/commands/default/permit

Displayed when the command is invoked without a required username.

```text
Usage: !permit [user] [seconds (default 60)]
```

--------------------------------

### $(charity)

Source: https://docs.fossabot.com/variables/charity

Returns a combined string of the charity name, description, and website.

```APIDOC
## $(charity)

### Description
Returns an alias combining the charity name, description, and website in the format: `$(charity.name): $(charity.description) - $(charity.website)`.

### Parameters
- None

### Response
- Success: String containing charity details.
- Error: `[Error: No campaign active.]` if no campaign is running.
```

--------------------------------

### $(channel.uptime)

Source: https://docs.fossabot.com/variables/channel

Returns the time that has passed since a broadcaster's stream has gone live.

```APIDOC
## $(channel.uptime)

### Description
Returns the time that has passed since a broadcaster's stream has gone live.

### Response
- **Success**: Returns the duration (e.g., 3 hours and 25 minutes)
- **Error**: Returns [Error: Stream is offline.] if the stream is offline.
```

--------------------------------

### $(valorant.rank)

Source: https://docs.fossabot.com/variables/valorant

Returns the current competitive rank of the broadcaster.

```APIDOC
## $(valorant.rank)

### Description
Returns the current competitive rank of the broadcaster.

### Parameters
- None

### Example Output
Platinum 1

### Error Handling
- If Riot API error: [Error: Riot API returned an error.]
- If rank label unknown: <unknown>
- If no competitive match history: [Error: Cannot determine rank - account does not appear to have any competitive match history.]
- If Riot account is not linked: [Error: The broadcaster must first link their Riot Games account in fossabot.com -> integrations.]
```

--------------------------------

### Retrieve word definition with !dictionary

Source: https://docs.fossabot.com/commands/default/dictionary

Executes a dictionary lookup for the specified word.

```text
!dictionary hello
```

```text
hello: A greeting used when meeting someone or answering the telephone.
```

--------------------------------

### Missing Parameter Error

Source: https://docs.fossabot.com/commands/default/filesay

Returned when the required URL parameter is not provided.

```text
Usage: !filesay <url>
```

--------------------------------

### $(sender.uptime)

Source: https://docs.fossabot.com/variables/sender

Returns the stream uptime of the sender.

```APIDOC
## $(sender.uptime)

### Description
Returns the time that has passed since the sender's stream has gone live. Returns an error if the stream is offline.

### Parameters
- None
```

--------------------------------

### $(gamesplayed)

Source: https://docs.fossabot.com/variables/gamesplayed

Returns a list of recorded game directories that a broadcaster's latest stream was, or current stream is under.

```APIDOC
## $(gamesplayed)

### Description
Returns a list of recorded game directories that a broadcaster's latest stream was, or current stream is under. This list is populated by Fossabot's tracking system when the bot is present during a game change.

### Parameters
This variable does not take any parameters.

### Example Output
`Grand Theft Auto V, Just Chatting`

### Error Output
If no games have been recorded, the variable returns: `[Error: User has no recorded games yet.]`
```

--------------------------------

### Usage of $(querystring) in a command response

Source: https://docs.fossabot.com/variables/querystring

Place the variable in a command response to encode subsequent arguments.

```text
$(querystring)
```

```text
look+at+this+cool+text
```

--------------------------------

### $(valorant.display_name)

Source: https://docs.fossabot.com/variables/valorant

Returns the current name and tag of the linked Riot Games account.

```APIDOC
## $(valorant.display_name)

### Description
Returns the current name and tag of the linked Riot Games account.

### Parameters
None.

### Example Output
Aiden#Dev

### Error Output
- If Riot API error: [Error: Riot API returned an error.]
- If not authorized: [Error: The broadcaster must first link their Riot Games account in fossabot.com -> integrations.]
```

--------------------------------

### Check current volume

Source: https://docs.fossabot.com/commands/default/volume

Displays the current playback volume percentage.

```text
!volume
```

```text
current volume: 75%
```

--------------------------------

### $(charity.target)

Source: https://docs.fossabot.com/variables/charity

Returns the fundraising goal amount.

```APIDOC
## $(charity.target)

### Description
Returns the fundraising goal set for the charity campaign.

### Parameters
- None

### Response
- Success: String representing the target amount.
- Error: `[Error: No campaign active.]` or `[Error: No fundraising goal set.]`.
```

--------------------------------

### Display error when no song is playing

Source: https://docs.fossabot.com/commands/default/song

The output returned when the media queue is empty.

```text
No song is playing
```

--------------------------------

### Retrieve Channel Login Name

Source: https://docs.fossabot.com/variables/channel

Returns the lowercase broadcaster username.

```text
$(channel)
```

```text
fossabot
```

--------------------------------

### Set Game Hardcoded

Source: https://docs.fossabot.com/variables/setgame

Use this syntax to set a specific game category whenever the command is triggered.

```text
$(setgame Grand Theft Auto V)
```

```text
Changed game to "Grand Theft Auto V"
```

--------------------------------

### $(ffzemotes)

Source: https://docs.fossabot.com/variables/ffzemotes

Retrieves a list of enabled FrankerFaceZ emotes for a given Twitch channel.

```APIDOC
## $(ffzemotes)

### Description
Returns a list of all currently enabled FrankerFaceZ emotes of a Twitch channel. Note that the maximum length of the output may cause not all emotes to be listed at all times.

### Parameters
- **username** (string) - Optional - The Twitch username of the channel to fetch emotes from. Defaults to the current broadcaster's username if not provided.

### Usage Examples
- `$(ffzemotes)`: Returns emotes for the current broadcaster.
- `$(ffzemotes aiden)`: Returns emotes for the user 'aiden'.

### Error Responses
- [Error: FrankerFaceZ API returned an error.] - Returned if the FrankerFaceZ API fails.
- [Error: Twitch API returned an error.] - Returned if an invalid username is provided.
- [Error: User not found.] - Returned if the user cannot be found or is unavailable.
```

--------------------------------

### $(charity.progress)

Source: https://docs.fossabot.com/variables/charity

Returns the fundraising progress as a percentage.

```APIDOC
## $(charity.progress)

### Description
Returns the progress towards the current fundraising goal as a percentage. This value may exceed 100%.

### Parameters
- None

### Response
- Success: String representing the percentage.
- Error: `[Error: No campaign active.]`, `[Error: No fundraising goal set.]`, or `[Error: Cannot calculate progress: Current and target currencies mismatch.]`.
```

--------------------------------

### $(references command_name)

Source: https://docs.fossabot.com/variables/references

Invokes the response of a specified custom command. This variable requires the name of the target command as a parameter.

```APIDOC
## $(references command_name)

### Description
Returns the parsed variable response from a custom command. Recursive invocations are blocked to prevent service abuse.

### Parameters
- **command_name** (string) - Required - The name of the custom command to be referenced.

### Example Usage
`$(references hello)`

### Success Response
Returns the string output of the referenced command.

### Error Responses
- **[Error: Command not found.]** - Returned if the specified custom command does not exist.
- **[Error: Input argument required.]** - Returned if no command name is provided as an argument.
```

--------------------------------

### $(user.provider_id)

Source: https://docs.fossabot.com/variables/user

Returns the platform ID of a user.

```APIDOC
## $(user.provider_id)

### Description
Returns the platform ID (e.g., the Twitch ID) of a user.

### Parameters
- **username** (string) - Optional - The Twitch username to fetch metadata for. Defaults to the sender if not provided.

### Example Output
`$(user.provider_id)` -> `87763385`
`$(user.provider_id fossabot)` -> `237719657`

### Error Output
`[Error: Invalid username.]`
```

--------------------------------

### $(channel.display_name)

Source: https://docs.fossabot.com/variables/channel

Returns the display name of the broadcaster.

```APIDOC
## $(channel.display_name)

### Description
Returns the uppercase or internationalized version of a broadcaster's username.

### Parameters
None.

### Example Output
Fossabot
```

--------------------------------

### $(channel.accountage)

Source: https://docs.fossabot.com/variables/channel

Returns the time elapsed since the broadcaster created their Twitch account.

```APIDOC
## $(channel.accountage)

### Description
Returns the time that has passed since a broadcaster created their Twitch account.

### Parameters
None.

### Example Output
3 years, 2 months and 1 day
```

--------------------------------

### $(sender.login)

Source: https://docs.fossabot.com/variables/sender

Returns the lowercase login name of the sender.

```APIDOC
## $(sender.login)

### Description
Returns the lowercase version of the sender's username (login).

### Parameters
- None
```

--------------------------------

### Fetch Metadata for Specific Users

Source: https://docs.fossabot.com/variables/user

Provide a username as a parameter to fetch metadata for a user other than the command sender.

```text
Shout out to $(user.display_name fossabot)! Go follow them at twitch.tv/$(user.login fossabot) - they were last seen playing $(user.game fossabot)!
```

```text
Shout out to Fossabot! Go follow them at twitch.tv/fossabot - they were last seen playing <no game>!
```

--------------------------------

### Output with fallback

Source: https://docs.fossabot.com/variables/fromindex

The result returned when the command is triggered without arguments.

```text
this is a fallback response
```

--------------------------------

### $(channel.provider_id)

Source: https://docs.fossabot.com/variables/channel

Returns the platform ID of a broadcaster.

```APIDOC
## $(channel.provider_id)

### Description
Returns the platform ID (e.g. the Twitch ID) of a broadcaster, not to be confused with the internal Fossabot ID.

### Parameters
This variable does not take any parameters.

### Example Output
237719657
```

--------------------------------

### Error output for missing commands

Source: https://docs.fossabot.com/variables/references

The error message displayed when the referenced command does not exist.

```text
[Error: Command not found.]
```

--------------------------------

### Handle !clip Command Errors

Source: https://docs.fossabot.com/commands/default/clip

Error messages returned when the broadcaster is offline or the bot lacks necessary permissions.

```text
Error: The broadcaster is not live
```

```text
Error: Fossabot does not have permission to create clips on this channel!
```

--------------------------------

### Set Game Error Output

Source: https://docs.fossabot.com/commands/default/setgame

The response returned when the specified game name is not found.

```text
Error: Game doesn't seem to exist
```

--------------------------------

### Fetch YouTube video by channel name

Source: https://docs.fossabot.com/variables/youtube

Retrieves the latest video for a specified channel name.

```text
$(youtube xqcow)
```

--------------------------------

### Invalid Emote Provider Error

Source: https://docs.fossabot.com/commands/default/emotes

Displays usage instructions when an invalid emote provider is specified.

```text

Usage: !emotes <reload|bttv|ffz|twitch|7tv>  


```

--------------------------------

### Enable a custom command

Source: https://docs.fossabot.com/commands/default/cmd

Enables a previously disabled custom command. Requires the command name as a parameter.

```text
!cmd enable hello
```

```text
Successfully enabled "!hello"
```

```text
Usage: !cmd enable <command>
```

```text
[Error: Command with that name or alias does not exist.]
```

```text
[Error: Command is already enabled!]
```

--------------------------------

### $(twitchreward)

Source: https://docs.fossabot.com/variables/twitchreward

Returns metadata for a specified Twitch Channel Point Reward. Note that rewards must be created through the Fossabot dashboard to be accessible.

```APIDOC
## $(twitchreward)

### Description
Returns metadata for a given Twitch Channel Point Reward. Note that only rewards created through the Fossabot dashboard are supported.

### Parameters
- **reward_name** (string) - Required - The name of the Twitch Channel Point Reward to fetch.

### Example Output
`$(twitchreward Play a game of VALORANT with me!)` -> 5

### Error Output
- Reward not found: `[Error: Unable to find a reward with that name.]`
- Reward not created via Fossabot: `[Error: Unable to access reward, make sure you create it through fossabot.com]`
```

--------------------------------

### $(sender.accountsince)

Source: https://docs.fossabot.com/variables/sender

Returns the creation date of the sender's Twitch account.

```APIDOC
## $(sender.accountsince)

### Description
Returns the date when the sender created their Twitch account in UTC.

### Parameters
- None
```

--------------------------------

### Retrieve sender provider

Source: https://docs.fossabot.com/variables/sender

Returns the platform name where the message originated.

```text
twitch
```

--------------------------------

### Retrieve User Views

Source: https://docs.fossabot.com/variables/user

Fetches the view count for the current user or a specified username.

```text
$(user.views)
```

```text
$(user.views fossabot)
```
Tokens:
Raw