Custom commands: from a tag to a condition
A bot command is the text it says in chat. That text can carry substitutions — the viewer's name, the stream title, a random number — and blocks: conditions, arithmetic, a random pick. Everything the bot understands is below, with examples.
Where commands are made
On the site: control panel → "Channel commands" → "Add command". Rights, cooldown, aliases and auto-repeat live there too, and the text is checked as you type.
From chat — for a channel moderator:
!создать !обнял ${user} обнял ${arg1}
Substitutions
A substitution is ${…} inside the command text. The bot replaces it with a value at the moment it answers.
| ${notag} | no mention The bot will not address the person who ran the command. |
| ${user} | viewer name Who the command is addressed to: the caller, or the name given after the command. |
| ${randomchatter} | random viewer A random name from chat. Twitch: the bot needs moderator rights. Kick: not supported. |
| ${title} | stream title The current stream title. |
| ${game} | category The current stream category. |
| ${arg1} | 1st word The first word after the command. |
| ${arg2} | 2nd word The second word after the command. |
| ${arg3} | 3rd word The third word after the command. |
| ${args} | everything after Everything written after the command. |
| ${rand 1 100} | random number A random number from the first to the second, both included. |
| ${arg1:кто-нибудь} | word or fallback The first word after the command, or — when there is none — whatever stands after the colon. Also works with ${arg2}, ${arg3}, ${args}, ${user}. |
Blocks
A block is {word …} inside the command text. Blocks are worked out before values are filled in, and they do what a substitution cannot: choose, count and compare.
| {if} | if A different answer depending on a condition. {elif} and {else} are allowed; {end} closes it. |
| {math} | math Add, subtract, multiply, divide, remainder. No powers. |
| {pick} | pick One of the options listed with a vertical bar. |
| {countdown} | time left How much time is left until a date: DD.MM or DD.MM.YYYY, optionally with a time. |
| {countup} | time since How much time has passed since a date. |
| {upper} | UPPERCASE The text in capital letters. |
| {lower} | lowercase The text in small letters. |
| {len} | length How many characters the text has. |
| {urlencode} | for a link The text made safe to put inside a URL. |
{if} must be closed with {end}; between them there may be any number of {elif} and one {else}. The other blocks close themselves.
What a condition may contain
Inside {if} and {math} you may use numbers, quoted text, substitutions, round brackets and these operations:
| == != | equal and not equal; letter case does not matter |
| < > <= >= | greater, smaller — numbers as numbers, text alphabetically |
| contains | whether the left text contains the right one |
| starts ends | starts with … and ends with … |
| and or not | and, or, not |
| + - * / % | add, subtract, multiply, divide, remainder |
Ready-made examples
Hug someone — and ask again when no name is given:
{if ${arg1} == ""}кого обнимать-то?{else}${user} обнял ${arg1}{end}
The same thing shorter, with a fallback:
${arg1:кого-нибудь} получает пирожок
How long until a date:
До Нового года {countdown 01.01}
Two dice:
выпало {math ${rand 1 6} + ${rand 1 6}}
A random pick:
${user}, сегодня ты {pick кот|пёс|бобр}
Several branches in a row:
{if ${args} contains "спасибо"}и тебе!{elif ${args} == ""}чего молчишь?{else}не понял{end}
When the bot answers with braces
The text did not parse — most often {end} is missing. The editor on the site checks the text as you type, points at what is wrong and where, and refuses to save the broken version without erasing what you wrote.
Chat will not take it either: !create and !edit answer that the text has an error.