Context Data

Context data is the data Kicklet injects into the current code run. Variables such as sender, args, or winner depend on where the code runs.

Each variable below lists where it is available.

Sender

Available in custom command responses. Also available in some alert messages, global command feedback messages, and shop code actions when that message passes a sender variable.

In engine v2, sender is exposed as a sender object whenever Kicklet can normalize the value. Use sender.username when code needs the username as a string.

In engine v1, the shape is not always the same. Command responses receive the full sender object. Alert messages receive a username string. Global/custom messages receive whatever that message type passes.

Engine v2

In custom command responses, sender is an object. Use sender.username for the displayed username.

Command sender nameAdvanced Script

async.messages.send(`Welcome ${sender.username}!`);

Command sender data structure:

id

number

Kick user ID.

username

string

Display username. Use this for point, counter, variable, and stats helpers that expect a username.

slug

string

Kick slug when available.

identity

objectnull

Chat identity data when Kicklet received it with the message.

color

string

Chat color as a hex string when available.

badges

array

Kick badges for this sender.

type

string

Badge type, for example moderator or subscriber.

text

string

Badge label shown by Kick.

count

number

Badge count or tier value when Kick provides one.

Example value

{
  "id": 123456,
  "username": "exampleUser",
  "slug": "exampleuser",
  "identity": {
    "color": "#8bd80d",
    "badges": [
      {
        "type": "moderator",
        "text": "Moderator",
        "count": 1
      }
    ]
  }
}

Alert messages also expose sender.username:

Alert sender nameAdvanced Script

async.messages.send(`Thanks for the follow, ${sender.username}!`);

Global command feedback receives whatever the feedback message passes. Current command feedback messages pass the command sender as an object, so use sender.username there.

Engine v1

In custom command responses, sender is the viewer who triggered the command. In templates it renders as the username, and sender.String explicitly returns the same username string.

Welcome {{sender}}!
Welcome {{sender.String}}!

JavaScript can read the command sender from the event object.

const sender = $event.getSender();

Alert messages expose sender as a username string through the alert variables:

Thanks for the follow, {{sender}}!

Global/custom messages expose variables by name. If the variable is a sender object, sender.String returns its username; if it is already a string, render sender directly.

Variables

Available in alert messages, global command feedback, shop code actions, giveaway winner messages, and other custom-message style renders.

In v2, variables contains the variables map for the current message. Most variables are also exposed directly by name, so variables.sender and sender often refer to the same value. If an older input provides sender as a plain string, v2 normalizes it to an object with username. In v1, these values are generally exposed directly by name.

amount

Available in subscription, gifted subscription, and host alert messages.

For subscription alerts, amount is the subscribed months. For gifted subscription alerts, it is the number of gifted subscriptions. For host alerts, it is the viewer count.

Thanks {{sender}} for {{amount}} months!

cost

Available in the global command feedback message for not enough points.

cost is the point cost that the viewer could not pay.

You need {{cost}} points for this command.

timeLeft

Available in the global command feedback message for cooldown or period-not-reached responses.

timeLeft is the remaining cooldown duration. Format it with the time/duration helper for the engine version you use.

usability

Available in the global command feedback message for usage mismatch responses.

usability is the expected command usage mode in lowercase.

This command can only be used while the stream is {{usability}}.

item

Available in shop code actions.

item is the shop item name that triggered the code action.

customFields

Available in shop code actions.

customFields contains the custom field values submitted for the shop item.

winner

Available in giveaway winner messages.

winner is the winner username.

The giveaway winner is {{winner}}!

Configuration Values

Use command or message configuration values when the response should read user-editable settings.

Engine v2

Read configuration value

Reads a configured value by key. Returns null when the key is missing.

Read a configured greetingAdvanced Script

const greeting = getConfig("greeting") ?? "Hello";
async.messages.send(`${greeting}, ${sender.username}!`);

API reference

getConfig

getConfig(key)

Input

key

string

Configuration key.

Output

stringnumberbooleanobjectnull

Configured value, or null when the key is not present.

Read configuration value alias

Alias for getConfig(key).

Read configuration through config objectAdvanced Script

const greeting = config.get("greeting") ?? "Hello";
async.messages.send(`${greeting}, chat!`);

API reference

config.get

config.get(key)

Input

key

string

Configuration key.

Output

stringnumberbooleanobjectnull

Configured value, or null when the key is not present.

Engine v1

Engine v1 templates usually receive configured values directly as variables from the surrounding message or command form.

Periodic Message

Available in periodic messages as periodicMessage.

It contains the periodic message settings for the message being rendered, such as its ID, active state, period, message threshold, and pin setting. Use it when the response should mention or inspect the current periodic message configuration.

This periodic message runs every {{periodicMessage.period}} seconds.

User

Available in render contexts as user.

user is the Kicklet channel/account that owns the template execution. It is not the command sender. Use sender for the viewer who triggered a command, and user for the channel context.

Data structure:

userId

number

Kicklet account/user ID.

chatroomId

number

Kick chatroom ID used for chat-related operations.

channelId

number

Kick channel ID.

kickUserId

number

Kick user ID of the channel owner/account.

kickUsername

string

Kick username of the channel owner/account.

kickSlug

string

Kick slug of the channel owner/account.

Example value

{
  "userId": 123,
  "chatroomId": 456,
  "channelId": 789,
  "kickUserId": 101112,
  "kickUsername": "channelName",
  "kickSlug": "channelname"
}

Command Data

Available in custom command responses.

command contains the command configuration and helper methods for argument access. message contains the Kick chat message that triggered the command.

Use the higher-level helpers from the Arguments section for normal argument access. Reach for message only when you need the raw command event data.

command

command contains the saved command configuration that matched the viewer message.

Common fields:

id

number

Internal command ID.

command

string

Main trigger without the leading exclamation mark.

active

boolean

Whether the command is active.

aliases

string[]

Alternative triggers.

permissions

string[]

Required permission names.

arguments

object[]

Configured argument definitions. Each item has name and required.

globalPeriod

number

Global cooldown/period in milliseconds.

userPeriod

number

Per-viewer cooldown/period in milliseconds.

costs

number

Point cost.

usage

string

Usage mode configured for the command.

asResponse

boolean

Whether the rendered response should reply to the triggering chat message.

templateVersion

string

Code engine version for the response.

templateType

string

Authoring surface, template for visual-builder source or script for Advanced Script.

args

string[]

Positional arguments after the command name.

namedArgs

object

Configured argument names mapped to entered values.

Example value

{
  "id": 42,
  "command": "song",
  "active": true,
  "aliases": [
    "music"
  ],
  "permissions": [],
  "arguments": [
    {
      "name": "query",
      "required": true
    }
  ],
  "globalPeriod": 10,
  "userPeriod": 30,
  "costs": 0,
  "usage": "online",
  "asResponse": true,
  "templateVersion": "v2",
  "templateType": "script",
  "args": [
    "never",
    "gonna",
    "give",
    "you",
    "up"
  ],
  "namedArgs": {
    "query": "never"
  }
}

message

message is the Kick chat message that triggered the command.

Data structure:

id

string

Kick message ID.

chatroom_id

number

Kick chatroom ID.

content

string

Raw chat message content.

created_at

string

Message creation timestamp.

type

string

Kick message type.

sender

object

Sender object for the chat message.

id

number

Kick user ID.

username

string

Display username. Use this for point, counter, variable, and stats helpers that expect a username.

slug

string

Kick slug when available.

identity

objectnull

Chat identity data when Kicklet received it with the message.

color

string

Chat color as a hex string when available.

badges

array

Kick badges for this sender.

type

string

Badge type, for example moderator or subscriber.

text

string

Badge label shown by Kick.

count

number

Badge count or tier value when Kick provides one.

Example value

{
  "id": "message-id",
  "chatroom_id": 123,
  "content": "!hello test",
  "created_at": "2026-05-06T12:00:00Z",
  "type": "message",
  "sender": {
    "id": 123456,
    "username": "exampleUser",
    "slug": "exampleuser",
    "identity": null
  }
}

Use message.content when you need the raw chat text. Use message.id when script code should send a reply to the original message. Use sender directly when you only need the viewer.

Arguments

Available in custom command responses.

Arguments are the words a viewer enters after the command name. For example, in !song never gonna give you up, the arguments are never, gonna, give, you, and up.

Kicklet also maps positional arguments to named arguments when the command has configured argument names. Named arguments are best for single values such as target, amount, choice, or game. Multi-word text such as a song title or search query is usually better read with command.argsText(start), because one named argument only receives one positional word. Required configured arguments are checked before the code runs.

Engine v2

Use args when you need a specific word by position. The example runs as the command message !song never gonna give you up; args[0] is the first word after the command name, so it returns never.

First argumentAdvanced Script

async.messages.send(`First argument: ${args[0] || ""}`);

Use command.argsText(start) when every argument from start onward should become one readable string. With the command message !song never gonna give you up, command.argsText(0) turns all arguments into never gonna give you up.

Argument textAdvanced Script

const title = command.argsText(0);
async.messages.send(`Song title: ${title}`);

Use command.argsQuery(start) for the same slice of arguments when it should be inserted into a URL query. With the command message !song never gonna give you up, it URL-encodes each argument and joins the result with %20, so the query becomes never%20gonna%20give%20you%20up.

URL queryAdvanced Script

const query = command.argsQuery(0);
async.messages.send(`Search query: ${query}`);

Use command.arg(name) for a named argument configured on the command. Named arguments do not come from the chat message by themselves; the command must define argument names first. The example runs !shoutout alice on a command that defines one argument named target, so Kicklet maps the first positional argument, alice, to target.

Named argumentAdvanced Script

const target = command.arg("target");
async.messages.send(`Target: ${target}`);

The same helpers are available in Advanced Script command code.

Validate command targetAdvanced Script

const target = command.arg("target") || args[0] || "";

if (!target) {
  async.messages.send(`${sender.username}, please enter a target username.`);
} else {
  async.messages.send(`Target selected: ${target}`);
}

Argument data structure:

args

string[]

Positional arguments after the command name.

namedArgs

object

Configured argument names mapped to the viewer's entered values.

command.args

string[]

Same positional argument array exposed through the command helper object.

command.namedArgs

object

Same named argument map exposed through the command helper object.

Named command argument

Reads a named command argument.

Read named argumentAdvanced Script

const target = command.arg("target");
async.messages.send(`Target: ${target}`);

API reference

command.arg

command.arg(name)

Input

name

string

Argument name.

Output

stringnull

Argument value, or null when the argument is missing.

Integer command argument

Reads a named or positional argument as an integer.

Read integer argumentAdvanced Script

const sides = command.argInt(0, { default: 6, min: 2, max: 100 });
async.messages.send(`Rolling a d${sides}.`);

API reference

command.argInt

command.argInt(nameOrIndex, options?)

Input

nameOrIndex

stringnumber

Named argument key or positional argument index.

optionsoptional

object

default, min, and max settings.

Output

number

Parsed integer.

Number command argument

Reads a named or positional argument as a number.

API reference

command.argNumber

command.argNumber(nameOrIndex, options?)

Input

nameOrIndex

stringnumber

Named argument key or positional argument index.

optionsoptional

object

default, min, and max settings.

Output

number

Parsed number.

Boolean command argument

Reads a named or positional argument as a boolean. Accepts values like yes/no, on/off, true/false, and 1/0.

Read boolean argumentAdvanced Script

const enabled = command.argBool(0);
async.messages.send(enabled ? "Alerts enabled." : "Alerts disabled.");

API reference

command.argBool

command.argBool(nameOrIndex, fallback?)

Input

nameOrIndex

stringnumber

Named argument key or positional argument index.

fallbackoptional

boolean

Value returned for unknown input.

Output

boolean

Parsed boolean.

Choice command argument

Returns the matching allowed choice for an argument, or null/default when it does not match.

Read choice argumentAdvanced Script

const team = command.argChoice(0, ["red", "blue"]);
async.messages.send(team ? `Team: ${team}` : "Choose red or blue.");

API reference

command.argChoice

command.argChoice(nameOrIndex, choices, options?)

Input

nameOrIndex

stringnumber

Named argument key or positional argument index.

choices

string[]

Allowed values.

optionsoptional

object

default and caseSensitive settings.

Output

stringnull

Matching choice.

Require argument count

Checks whether the command has at least count positional arguments. Optionally sends a message when arguments are missing.

Require argumentsAdvanced Script

if (!command.requireArgs(1, "Usage: !shoutout USER")) {
  async.messages.send("Missing shoutout target.");
} else {
  async.messages.send(`Follow ${args[0]}!`);
}

API reference

command.requireArgs

command.requireArgs(count, message?)

Input

count

number

Minimum positional argument count.

messageoptional

string

Message to send when the check fails.

Output

boolean

True when enough arguments are present.

Command arguments as text

Returns command arguments as a single text string.

Read multi-word argument textAdvanced Script

const title = command.argsText(0);
async.messages.send(`Song title: ${title}`);

API reference

command.argsText

command.argsText(start?)

Input

startoptional

number

Zero-based argument index to start from.

Output

string

Joined command arguments.

Command arguments as URL query

Returns command arguments as a URL-encoded query fragment joined with %20.

Read URL query argument textAdvanced Script

const query = command.argsQuery(0);
async.messages.send(`Search query: ${query}`);

API reference

command.argsQuery

command.argsQuery(start?)

Input

startoptional

number

Zero-based argument index to start from.

Output

string

URL-encoded command arguments.

Engine v1

Use args with index when you need a specific word by position. Use argsString start when every argument from start onward should become one readable string. Use argsUrlQuery start when the same slice should be inserted into a URL query; it joins the arguments with %20. Use arg name for a configured named argument.

First argument: {{index args 0}}
All arguments: {{argsString 0}}
URL query: {{argsUrlQuery 0}}
Named argument: {{arg "target"}}

Advanced Script example:

const sender = $event.getSender();
const args = $event.getCommandArgs();
const firstArg = args[0];