Under Settings - Commands you can add Custom Commands and
customize some Context Menus (and the User Info Dialog) with your own entries.
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.
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: \\ .
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$(1), $(2), $(3) is the equivalent in the regular notation$1-$2-, $3- is also possible$(1-), $(2-), $(3-) is the equivalent in the regular notation$$1$$2, $$3- is also possible$$(1), $$(2), $$(3-) is the equivalent in the regular notationThe 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) .
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-,/).
| 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)/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.
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(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])$if, but instead of just checking fot the
existence of a parameter it compares it to a given value
(<comparison>).$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>)$join(1-,/) with 1- referring to
flour sugar eggs turns into flour/sugar/eggs$lower(<identifier>)$lower(1) with 1
referring to Fremily turns into fremily.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)/slap Nightbot turns into /me slaps Nightbot around a bit with a large trout/slap Nightbot cheesecake turns into /me slaps Nightbot around a bit with a large cheesecake/mt /openUrlPrompt http://multitwitch.tv/$$join(1-,/)/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/mt joshimuz lotsofs opens the URL http://multitwitch.tv/joshimuz/lotsofsNote: 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).
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).
Under Settings - Commands there are several settings that
allow you to add additional entries/buttons in a few different places:
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.
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/
(although it may also work without).//Slap// 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 colorIn the same line, you can also specify Timeout Buttons:
5 2m 10m/ 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 2mYou 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.
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.
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
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).
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.
In the User Dialog Buttons setting you can use some special commands:
/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)./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.