Skip to content
StreamElements Docs

Create Commands That Use Viewer Input

Argument tokens let a custom command reuse what a viewer types after its trigger. You can capture one word, the rest of the message, or a range of words, then place that input in a reply or encode it for a URL.

Create a command that captures a message

Section titled “Create a command that captures a message”

This command turns !doing making pasta into ViewerName is currently making pasta.

  1. Open the bot command dashboard, select Custom commands, and click Add new command.

  2. Name the command doing and enter this reply:

    $(sender) is currently $(1:)

  3. Click Activate command.

  4. Test it with several words after the trigger:

Example chat
ViewerName:!doing making pasta and dancing
partner badgemoderator badgeStreamElements:ViewerName is currently making pasta and dancing

$(sender) identifies the viewer who used the command. $(1:) means every word from the first argument through the end of the message.

Choose the input you need

Section titled “Choose the input you need”

In !introduce Alice 25 from Copenhagen, the trigger itself is word 0:

Token Output
$(1) Alice
$(2) 25
$(3:) from Copenhagen
$(1:2) Alice 25

If a requested word is missing, the token outputs nothing. Add a pipe fallback when a default makes sense:

$(sender) hugs $(1|everyone)!

That command targets the first word after !hug, or everyone when no name was provided.

Validate a username

Section titled “Validate a username”

Use the username validator when an input must look like a Twitch-style username:

Check out $(1 username)'s channel at https://twitch.tv/$(1 username)

The validator accepts letters, digits, and underscores, optionally prefixed by @, up to 30 characters. It outputs nothing when the argument does not match that shape. See Argument tokens for the complete behavior.

Put viewer input in a URL

Section titled “Put viewer input in a URL”

Do not insert arbitrary multi-word input directly into a URL. Encode it for the part of the URL where it will be used.

Query parameters

Section titled “Query parameters”

Use $(queryescape) for values after ?:

Search results: https://google.com/search?q=$(queryescape $(1:))

!google StreamElements chatbot produces a URL ending in ?q=StreamElements+chatbot.

URL paths

Section titled “URL paths”

Use $(pathescape) for a path segment:

Read more: https://en.wikipedia.org/wiki/$(pathescape $(1:))

!wiki rocket league produces a path ending in /rocket%20league.

Use input with a public API

Section titled “Use input with a public API”

You can pass encoded input to $(customapi), which makes a GET request and prints the response. The following is a pattern, not a working endpoint—replace api.example.com with a public endpoint you trust:

$(customapi https://api.example.com/define?word=$(queryescape $(1)))

Use an API designed to return short plain text. $(customapi) cannot set headers, truncates responses after 400 bytes, and does not parse JSON. Do not put private API credentials in the command URL.

Section titled “Related”