Variables

Variables store custom data. Use global variables for channel-wide state and viewer variables for per-viewer state.

Variable names can be up to 200 characters. Viewer names for viewer-scoped variables can be up to 50 characters. Total stored variable value size is limited per account: 100 KB for default accounts and 5 MB for premium accounts. Values with ttl still count toward that limit until they expire and cleanup removes them.

Set a global variable

Use a global variable when the value belongs to the whole channel.

Engine v2

Stores a global variable, or a viewer variable when a viewer option is provided.

Set a global variableAdvanced Script

vars.set("mode", "ranked");
async.messages.send("Mode saved.");

API reference

vars.set

vars.set(name, value, options?)

Input

name

string

Variable name.

value

stringnumberbooleanobjectarraynull

Value to store.

optionsoptional

object

Storage scope and expiration.

vieweroptional

string

Viewer username for a viewer-scoped value.

ttloptional

number

Lifetime in seconds before the value expires.

Output

void

The value is stored as a side effect.

Engine v1

Engine v1 response example:

{{kicklet.SetGlobalVar "mode" "ranked" 0}}
Mode saved.

Advanced Script example:

Kicklet.setGlobalVar("mode", "ranked");

Read a global variable

If the variable does not exist, vars.get() returns null.

Engine v2

Reads a global variable, or a viewer variable when a viewer name is provided.

Read a global variableAdvanced Script

const mode = vars.get("mode");
async.messages.send(`Mode: ${mode}`);

Missing global variableAdvanced Script

const season = vars.get("season") ?? "not set";
async.messages.send(`Season: ${season}`);

API reference

vars.get

vars.get(name, viewer?)

Input

name

string

Variable name.

vieweroptional

string

Viewer username for a viewer-scoped value.

Output

stringnumberbooleanobjectarraynull

Stored value, or null when the variable is missing.

Example output

{
  "streak": 3,
  "lastSeen": "2026-05-11"
}

Engine v1

Engine v1 response example:

Mode: {{kicklet.GetGlobalVar "mode"}}

Advanced Script example:

Kicklet.getGlobalVar("mode").then((resp) => resp.data);

Check whether a variable exists

Use vars.exists() when null is a valid stored value or when you need different text for missing values.

Engine v2

Checks whether a variable exists without reading a missing value as null.

Existing global variableAdvanced Script

if (vars.exists("mode")) {
  const mode = vars.get("mode");
  async.messages.send(`Mode exists: ${mode}`);
} else {
  async.messages.send("Mode is missing.");
}

Missing global variableAdvanced Script

if (vars.exists("season")) {
  const season = vars.get("season");
  async.messages.send(`Season exists: ${season}`);
} else {
  async.messages.send("Season is missing.");
}

API reference

vars.exists

vars.exists(name, viewer?)

Input

name

string

Variable name.

vieweroptional

string

Viewer username for a viewer-scoped value.

Output

boolean

True when the variable exists.

Engine v1

Engine v1 helpers in Engine v1 return the backend value directly.

Delete a global variable

Engine v2

Deletes a global variable, one viewer variable, or all viewer values for a variable.

Delete a global variableAdvanced Script

vars.delete("mode");
async.messages.send("Mode deleted.");

API reference

vars.delete

vars.delete(name, options?)

Input

name

string

Variable name.

optionsoptional

object

Delete scope.

vieweroptional

string

Viewer username for one viewer-scoped value.

allViewersoptional

boolean

Delete this variable for every viewer.

Output

void

The value is deleted as a side effect.

Engine v1

Engine v1 response example:

{{kicklet.DeleteGlobalVar "mode"}}
Mode deleted.

Advanced Script example:

Kicklet.deleteGlobalVar("mode");

Set a viewer variable

Use a viewer variable when every viewer needs their own value for the same variable name. Add ttl when the value should expire automatically after a number of seconds.

Engine v2

Stores a global variable, or a viewer variable when a viewer option is provided.

Set a viewer variableAdvanced Script

vars.set("streak", 3, { viewer: sender.username, ttl: 3600 });
async.messages.send("Streak saved for one hour.");

API reference

vars.set

vars.set(name, value, options?)

Input

name

string

Variable name.

value

stringnumberbooleanobjectarraynull

Value to store.

optionsoptional

object

Storage scope and expiration.

vieweroptional

string

Viewer username for a viewer-scoped value.

ttloptional

number

Lifetime in seconds before the value expires.

Output

void

The value is stored as a side effect.

Engine v1

{{kicklet.SetViewerVar "streak" sender.String 3 3600}}
Streak saved for one hour.

Read a viewer variable

Pass the viewer name as the second argument. If that viewer does not have a value for the variable, vars.get() returns null.

Engine v2

Reads a global variable, or a viewer variable when a viewer name is provided.

Read a viewer variableAdvanced Script

const streak = vars.get("streak", "alice");
async.messages.send(`Alice streak: ${streak}`);

Missing viewer variableAdvanced Script

const streak = vars.get("streak", "zoe") ?? "not set";
async.messages.send(`Zoe streak: ${streak}`);

API reference

vars.get

vars.get(name, viewer?)

Input

name

string

Variable name.

vieweroptional

string

Viewer username for a viewer-scoped value.

Output

stringnumberbooleanobjectarraynull

Stored value, or null when the variable is missing.

Example output

{
  "streak": 3,
  "lastSeen": "2026-05-11"
}

Engine v1

Your streak: {{kicklet.GetViewerVar "streak" sender.String}}

Delete viewer variables

Delete one viewer's value when only that viewer should be reset. Delete all viewer values when you want to clear the variable for everyone.

Engine v2

Deletes a global variable, one viewer variable, or all viewer values for a variable.

Delete viewer variablesAdvanced Script

vars.delete("streak", { viewer: sender.username });
async.messages.send("Your streak was reset.");

vars.delete("streak", { allViewers: true });
async.messages.send("All streaks were reset.");

API reference

vars.delete

vars.delete(name, options?)

Input

name

string

Variable name.

optionsoptional

object

Delete scope.

vieweroptional

string

Viewer username for one viewer-scoped value.

allViewersoptional

boolean

Delete this variable for every viewer.

Output

void

The value is deleted as a side effect.

Engine v1

{{kicklet.DeleteViewerVar "streak" sender.String}}
Your streak was reset.

{{kicklet.ClearViewerVar "streak"}}
All streaks were reset.

Async variable wrappers

Async wrapper for vars.get(name, viewer?).

API reference

async.vars.get

async.vars.get(name, viewer?)

Input

name

string

Variable name.

vieweroptional

string

Viewer username for a viewer-scoped value.

Output

stringnumberbooleanobjectarraynull

Stored value, or null when the variable is missing.

Example output

{
  "streak": 3,
  "lastSeen": "2026-05-11"
}

Async wrapper for vars.exists(name, viewer?).

API reference

async.vars.exists

async.vars.exists(name, viewer?)

Input

name

string

Variable name.

vieweroptional

string

Viewer username for a viewer-scoped value.

Output

boolean

True when the variable exists.

Async wrapper for vars.set(name, value, options?).

API reference

async.vars.set

async.vars.set(name, value, options?)

Input

name

string

Variable name.

value

stringnumberbooleanobjectarraynull

Value to store.

optionsoptional

object

Storage scope and expiration.

vieweroptional

string

Viewer username for a viewer-scoped value.

ttloptional

number

Lifetime in seconds before the value expires.

Output

void

The value is stored as a side effect.

Async wrapper for vars.delete(name, options?).

API reference

async.vars.delete

async.vars.delete(name, options?)

Input

name

string

Variable name.

optionsoptional

object

Delete scope.

vieweroptional

string

Viewer username for one viewer-scoped value.

allViewersoptional

boolean

Delete this variable for every viewer.

Output

void

The value is deleted as a side effect.