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
  • Restrict to channel
  • Anonymous Custom Commands
  • Chaining Commands
• Replacements
  • Simple Replacements
  • Pre-defined Parameters
  • Functions
  • Custom Replacements
• Custom Context Menus / User Dialog Buttons
  • Format 1: List Custom Command Names
  • Format 2: Inline-Commands
  • Format 3: Submenus
  • Separators
  • Shortcuts
  • Positioning
  • Special Commands

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.

See Replacements for more advanced usage.

Restrict to channel

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.

Anonymous Custom Commands

Custom Commands that aren't defined in the Custom Commands list do not have a name and can thus only be executed from the context they are defined, for example when adding Inline-Commands to the User Dialog or Context Menus.

You can also execute Anynomous Custom Commands directly from the inputbox, by prepending //, which allows you to use Replacements:

/echo Open Channels: $(chans)

Executes as a normal command (nothing replaced)

Outputs Open Channels: $(chans)

//echo Open Channels: $(chans)

Executes as an Anonymous Custom Command

Outputs Open Channels: joshimuz lotsofs cirno_tv

Chaining Commands

Executing several commands in a row is not a feature of Custom Commands, although the /chain command can be used to achieve something like that.

Replacements

• Simple Replacements
• Pre-defined Parameters
• Functions
• Custom 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 an optional 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 separated 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: $(10) .

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 can be used in which context. To use an identifier put it in a replacement, for example $(chan) or $$join(1-,/).

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.

$lower(<identifier>)

Makes the given input lowercase.

Example: $lower(1) with 1 referring to Fremily turns into fremily.

$rand(<output1>,<output2>,<output3>,..)

Randomly chooses one of the outputs.

Example: $rand(cheesecake,strawberry cake,$1-) with 1- referring to apple pie turns into either cheesecake, strawberry cake or apple pie.

$randnum(<from>,<to>) or $randnum(<to>)

Randomly chooses a number in the given range (inclusive). If only one number is given, it the range is 0 to the given number. If the "from" is not a number, it defaults to 0, if the "to" is not a number it defaults to a really big number.

Example: $randnum(600,800) chooses a random number between 600 and 800.

Example: $randum($$1) chooses a random number between 0 and what is the first parameter.

$datetime([format],[timezone],[locale])

Outputs the current date/time. You can optionally give a format pattern (based on DateTimeFormatter), a timezone (based on ZoneId, although something like "New York" should also work) and a locale (a language tag such as "en").

Predefined formats:

• Short: date, time, datetime
• With timezone: date2, time2, datetime2
• Locale-specific: Append _short, _medium, _long or _full, e.g. datetime_full

Examples:

$datetime()

Wednesday, March 13, 2019 3:11:48 PM CET

(Default format depends on the locale, in this case using the system default.)

$datetime(,,de)

Mittwoch, 13. März 2019 15:12 Uhr MEZ

(Default format depends on the locale, in this case explicitly specified.)

$datetime(time)

23:31:27

(Using one of the pre-defined formats "time".)

$datetime(datetime2,Vancouver)

2019-03-12 15:31:45 PDT GMT-0700

(Using the more verbose "datetime2" pre-defined format, with a timezone specified.)

$datetime(datetime_full,Rome,it)

mercoledì 13 marzo 2019 15.32.03 CET

(Using one of the locale-specific pre-defined formats, with timezone and locale specified.)

$datetime(,london)

Wednesday, March 13, 2019 2:16:36 PM GMT

(Empty format to be able to specify timezone.)

$datetime(HH:mm:ss zzzz,Tokyo,en)

07:50:20 Japan Standard Time

(Output is usually based on your system language, but you can also explicitely specify it.)

$datetime(eeee\, dd. MMMM yyyy,,de)

Dienstag, 12. März 2019

(Custom format, , escaped since it normally separates function parameters, empty timezone in order to be able to specify locale.)

Tip: Enter e.g. //echo $datetime() into the chat inputbox to test a function directly, use arrow up/down keys to cycle through previous inputs. Of course you won't be able to use some context dependant parameters this way.

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-,/)

Addendum: As of v0.8.7 the <identifier> parameter will also accept replacements as input (anything starting with $).

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

• Format 1: List Custom Command Names
• Format 2: Inline-Commands
• Format 3: Submenus
• Separators
• Shortcuts
• Positioning
• Special Commands

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). Note the Special Commands you can use for this setting.

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.

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.

Separators

In Context menus you can add separators between entries. When you use a commands list, you can add a vertical bar (|) between entries.

You can also add a separator by adding a single dash (-) on it's own line.

Example (separator before Timeout menu, before Message and before Vods):

/Ban /Purge
-
@Timeout
.5s 10m
-
/Message /Report | /Vods

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 .. (depending on the line format)

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. Examples: alt+Q, shift+1, INSERT

Note: The lowercase/uppercase matters for it to be parsed correctly.

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.

Special Commands

In the User Dialog Buttons setting you can use some special commands:

• Add the command /modunmod to ada 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 up).
• The commands /Automod_approve and /Automod_deny only appear as buttons when you opened the User Dialog by clicking on the username of a message rejected by AutoMod.

To make use of these you only need to enter the command, you don't need any parameters (Chatty will take care of that). For example simply add /Modunmod or Approve=/Automod_approve to add it to the layout (using the syntax shown on this help page). Chatty will then recognize the command names and the buttons will only show up when they are needed.