Custom Commands / Context Menus

Under Settings - Commands you can add Custom Commands and customize some Context Menus (and the User Info Dialog) with your own entries.

Custom Commands

Custom commands allow you to specify aliases for anything you could also enter directly into the inputbox, like chat messages or regular commands (with the exception of other custom commands, which is a limitation implemented to prevent infinite loops).

To add a Custom Command add a new entry to the list labeled "Custom Commands", in the following format:

/<commandName> <what the command should do>

Everything up to the first space is the name of the command, and everything after the first space is what the command will do or execute. For example:

/hello Hello World!

If you added that to the Custom Commands list and enter /hello in the inputbox, then it would send Hello World! to chat, just as if you would have written it yourself and pressed Enter.

Adding a # and a channel name you can restrict the command to that channel:

/hello#joshimuz Hello Joshimuz Chat!

This /hello command would only be executed in #joshimuz, however if you still have the version without a channel in the Custom Commands list as well, it will fallback to that in other channels. This way to can add variations of commands for specific channels.

Replacements

Anything starting with $ in the <what the command should do> section is treated as some sort of replacement. Each replacement must contain an identifier which identifies what the replacement should be replaced with.

For the short notation the identifier is written directly after the dollar sign: $<identifier> . In thise case it may only consist of a number and a dash: $<1-9-> . Numeric identifiers refer to the parameters supplied to the command.

For the regular notation the identifier is written after the $ in parentheses: $(<identifier>) . This type of notation makes a more clear distinction between replacement and the rest of the (literal) text and may contain numbers (including higher than 9) and other identifiers, depending on the context.

Put $$ (the $ twice) for any required replacement (for example $$1 ), which means the whole Custom Command will only be run if that replacement turns into a non-empty value. This can be used to make sure that a parameter that is necessary for the command to make sense is actually being supplied.

Note: If you want to use a dollar sign $ without it having a special meaning, you can escape it with a backslash: \$ . To use a backslash literally instead of as an escaping character, it must be escaped as well: \\ .

Simple Replacements

A basic use of replacements is using the short notation to put in parameters supplied when executing the command. Consider this Custom Command:

/slap /me slaps $$1 around a bit with a large trout

Then, when you enter /slap moobot in the inputbox, it will replace $$1 with the first word after the command, which in this case would be moobot, making the resulting command:

/me slaps moobot around a bit with a large trout

This is the syntax for specifying parameters (word in this context means anything seperated by a space):

$1, $2, $3
First word, second word, third word etc.
$(1), $(2), $(3) is the equivalent in the regular notation
$1-
First word, and all the words after it
$2-, $3- is also possible
$(1-), $(2-), $(3-) is the equivalent in the regular notation
$$1
First word, but required, meaning the command will only be executed if this parameter is actually present
$$2, $$3- is also possible
$$(1), $$(2), $$(3-) is the equivalent in the regular notation

The short notation ( $1 ) only works for the numbers 1 to 9, which usually should be enough. For other kinds of replacements you must use the regular notation including parentheses: $(1) .

Pre-defined Parameters

Custom Commands can be used in a number of different places. Depending on the context there are different pre-defined parameters available. The following table shows which identifiers that can be used in which context. To use an identifier put it in a replacement, for example $(chan) or $$join(1-,/).

Context Identifier Description
All chan The current channel context (without leading #)
streamstatus Stream Status (Title/Game or Offline)
streamtitle Stream Title (only if live)
streamgame Stream Game (only if live)
streamviewers Number of viewers (only if live)
streamuptime Stream Uptime (only if live)
The stream info is of the current channel context
User Context Menu 1 Name of the user
User Dialog 1 Name of the user
2- Ban reason (if selected)
Channel Context menu 1 Name of the currently active channel (without leading #)
Streams Context menu 1- Names of selected streams
Hotkey 1 The currently selected user (if present)

Example with pre-defined parameters:

/streaminfo /echo [Stream Status] $(streamstatus) [Uptime] $(streamuptime)
Entering /streaminfo outputs an info message (only for you) with the current stream status and uptime.

In addition, there is an implicit channel context, which means channel-aware commands like /ban are executed in the appropriate channel.

Functions

There is a very limited amount of functions available. Functions are replacements, however they have a function name before the identifier (there is no short notation for functions):

$<functionName>(<identifier>,<some parameters>,[optional parameters])

The following functions are available:

$if(<identifier>,<output if exists>,[output if not])
If the value the identifier refers to exists (non-empty), it will return the first function parameter, the second otherwise.
Example: $if(1,$1,nope) with command parameters cheese cake turns into cheese, with no parameters turns into nope, the optional [output if not] function parameter.
$ifeq(<identifier>,<comparison>,<output if equal>,[output if not])
Similar to $if, but instead of just checking fot the existence of a parameter it compares it to a given value (<comparison>).
Example: $ifeq(1,cheesecake,yummy) with parameters cheesecake turns into yummy, with parameters cheese cake turns into an an empty string, since the optional [output if not] has not been specified.
$join(<identifier>,<separator>)
Joins together the arguments the identifier refers to, using the given separator.
Example: $join(1-,/) with 1- referring to flour sugar eggs turns into flour/sugar/eggs
This effectively replaces spaces in the parameters with the separator.

Note: The <identifier> parameter means only the identifier, without any $, while the other parameters may contain replacements (including functions). You can think of this function syntax as an extension to the regular replacement: $(1-) -> $join(1-,/)

Examples of Custom Commands with these functions:

/slap /me slaps $$1 around a bit with a large $if(2,$2,trout)
Entering /slap Nightbot turns into /me slaps Nightbot around a bit with a large trout
Entering /slap Nightbot cheesecake turns into /me slaps Nightbot around a bit with a large cheesecake
/mt /openUrlPrompt http://multitwitch.tv/$$join(1-,/)
Entering /mt outputs an "insufficient parameters" message because the $$join is required to return something, which it can't from the identifier 1- if there are no parameters
Entering /mt joshimuz lotsofs opens the URL http://multitwitch.tv/joshimuz/lotsofs

Note: A backslash can be used to escape parenthesis in function parameters. Example: $if(streamuptime,$(streamuptime),(n/a\)). In this example only the closing one after n/a has to be escaped, because the opening one doesn't have a special meaning in this context and the ones around streamuptime have a special meaning that takes precedence (opening/closing the replacement).

Custom Replacements

You can create your own identifiers for replacements by adding an entry to the Custom Commands list starting with an underscore:

_m $ifeq(1,$(chan),,$$1: )

Instead of a command, this creates an identifier that can be used in a replacement:

/faq $(_m)FAQ: https://pastebin.com/KySx3KDu

When the /faq command is run, the $(_m) gets replaced with whatever is defined in _m, in this case it creates a mention if the first parameter isn't equal to the current channel.

Note: Custom identifiers always start with an underscore and can themselves not contain replacements with custom identifiers (well they technicially can, but they won't get replaced).

Custom Context Menus / User Dialog Buttons

Under Settings - Commands there are several settings that allow you to add additional entries/buttons in a few different places:

User Context Menu
Entries get appended to the menu that opens when you right-click on a user in chat or the userlist.
Channel Context Menu
Entries get appended to the menu that opens when you right-click on the chat.
Streams Context Menu
Entries get appended to any menu that contains a "Twitch Stream" submenu (for example the User Context Menu, Live Streams Dialog Context Menu).
User Dialog Buttons
Defines which buttons are visible in the dialog that opens when you click on a user in chat (or double-click in the userlist).

All those settings share the same format (with some slight differences noted separately). A setting can contain several lines, and each line can contain one of the available formats:

/Ban[B] /Unban[U] 5s[1] 2m[2] 10m[3] 30m[4]
Spoiler[S]=/timeout $$1 600 No spoilers

@b1
./Message /Report
.Warn User=$$1: Plz no spammerino

Note: Command Names/Labels may not contain the characters [ ] { } except for their special meaning of Shortcuts and Positioning.

Format 1: List Custom Command Names

You can list the name of several Custom Commands in one line, for example:

/Slap /Permit

Which means the command with the name "slap" will be added first, then "permit" after that. These must be existing commands, either pre-defined Chatty commands or Custom Commands you added yourself.

Note that you may only specify the command names, no parameters. The parameters will be supplied automatically depending on the context. For example when you have /Slap added to the User Dialog and then open the dialog on the user tailsgaming and click the "Slap" button, it's as if you entered /slap tailsgaming.

/Slap /Permit
Command names should be prepended with a forward slash / (although it may also work without).
//Slap
Prepending two forward slashes // will put the command in the special submenu More.. (for Context Menus) or in a second line of buttons (for the User Dialog).
/Set_color is displayed as Set color
Underscores in commands are replaced with a space for display in a Context menu or on a button.

In the same line, you can also specify Timeout Buttons:

5 2m 10m
Times are added just like Custom Commands, except that they must not start with a slash / and must be a number followed by an optional suffix. They are interpreted as seconds by default, unless you add a suffix: s - seconds, m - minutes, h - hours, d - days.
120s 120 is displayed as two buttons with the label 120s and 2m
Both definitions create a button with a 120 seconds timeout, however if you use a suffix, then the definition is used as button label directly, otherwise the label is automatically created based on the time.

The command /modunmod has a special meaning in the User Dialog and is used to add a Mod/Unmod-Button which automatically changes depending on the selected user and whether you are the broadcaster on the channel (so the button doesn't always show). Reposition this command to change where the Mod/Unmod-Button appears, or remove it altogether if you don't want it.

Format 2: Inline-Commands

You can define commands directly in the setting, without having to add them as a named Custom Command first. The syntax for this is:

<label with spaces>=<what the command should do>

Note that as opposed to Custom Command names the label may contain spaces, and for that purpose the separating character is an equals sign =. The label may not contain an equals sign itself. Example:

Warn User=$$1: Plz no spammerino

As with Custom Commands, the <what the command should do> part can contain replacements using identifiers for the current context.

Format 3: Submenus

Any line starting with @ defines a custom submenu. Any following lines that start with a dot . will then be put in that menu (both command name lists and inline commands). For example:

@Rules
./No_Spam /No_Spoilers
.Spoiler=/timeout $$1 600 no spoilers

For Context Menus you can add submenus with custom names (only 1 level though), or even add entries to existing submenus by specifying the name (for example @Twitch Stream).

For User Dialog Buttons there are no named submenus, however this notation can be used to put the buttons in separate rows. Any submenu name starting with a will create a row on the top, all other ones on the bottom. The menu name a1 is the default for buttons that don't have a menu defined, and b1 is the default for the //Command notation. Example:

/Ban /Unban
@a1
.Spoiler=/timeout $$1 600 no spoilers
@a2
.5s[1] 2m[2] 10m[3] 30m[4]
@b1
./Slap

In this case the Ban and Unban commands are in the default a1 row, which means they are in the same row as the Spoiler button (these are just different ways of writing it). This also adds a second top row a2 for the timeout buttons as well as a single bottom row for the Slap command.

Shortcuts

You can add a shortcut to the end of a label or command name by enclosing it with [ ] (square brackets):

/Ban[B] or Spoiler[S]=/timeout $$1 ..

For User Dialog Buttons those can be used while the dialog is open and focused. They are interpreted by getKeyStroke() which means anything that function understands can be used. However spaces are not allowed, so a plus sign + can be used instead.

Adding a vertical bar | after the shortcut will use the text after it as label for the shortcut on the button (no spaces allowed). If you include the | but don't specify any text, then no label will be displayed for that shortcut:

/Slap[NUMPAD1|Np1] /Permit[NUMPAD2|]

For the User Dialog Buttons you can also include the string nokeylabels anywhere in the setting, which removes any labels for the shortcuts, unless they are explicitly defined.

For Context Menus a single character can be used as a Mnemonic, for quick access to menu entries. For this purpose, submenus may also contain the same syntax: @Rules[R] (which would allow you to open that submenu by pressing R on your keyboard when the context menu is open).

Positioning

You can define an absolute position in the menu the entry should appear at by enclosing it with { } (curly brackets) at the end of the label or command name (but before a shortcut if there is any):

Mention{1}=/insertword $$1: \

This will put the Mention menu entry at the second position in the menu (counting starts from 0).

Another example:

@Twitch Stream[s]
.Videos{2}[v]=/openUrlPrompt https://www.twitch.tv/$$1/videos/past-broadcasts
@Important{0}
.Slap=/me slaps $$1 around a bit with a large trout
@Really Important{0}
.FAQ=FAQ: https://pastebin.com/KySx3KDu

This puts the Videos entry into the pre-defined Twitch Stream submenu at the third position in the submenu (also adding the accelerator key s to the menu and v to the entry).

It also adds the Important submenu at the first position (since it hasn't been added yet) and after that adds the Really Important submenu at the first position as well, moving down Important. This demonstrates that the positioning is based on the current state of the menu, so it can matter when you add entries with absolute positioning.