Viewer Activity

Viewer activity data comes from Kicklet's stored viewer activity and channel state. These helpers read data; helpers that change balances or variables are documented on Viewer Points and Variables.

sender is the viewer who triggered the current command or message context. Use sender.username when you need the current command sender, and use channel.user(username) when you need channel data for another username. username is the Kick username shown for that viewer.

Viewer Helpers

Engine v2

Check viewer badge

Checks a viewer identity badge. When called with one argument, it checks the current sender.

Check sender badgeAdvanced Script

if (channel.hasBadge("moderator")) {
  async.messages.send("Moderator badge detected.");
}

API reference

channel.hasBadge

channel.hasBadge(viewer?, badge)

Input

vieweroptional

object

Viewer object.

badge

string

Badge type or label.

Output

boolean

Whether the badge is present.

Viewer badges

Returns the Kick badges from a viewer object.

List sender badgesAdvanced Script

const badges = channel.badges(sender).map((badge) => badge.text || badge.type).join(", ");
async.messages.send(badges || "No badges found.");

API reference

channel.badges

channel.badges(viewer)

Input

viewer

object

Viewer object such as sender or channel.user(username).

Output

object[]

Viewer badges.

Load channel user

Returns channel data for a username. The returned object includes helper methods like hasBadge() and hasPermission().

Check another viewerAdvanced Script

const viewer = channel.user("exampleUser");

if (viewer.hasBadge("moderator")) {
  async.messages.send(`${viewer.username} is a moderator.`);
}

API reference

channel.user

channel.user(username)

Input

username

string

Kick username.

Output

object

Channel viewer object.

Engine v1

Use sender for the current command sender and Kick helpers for channel user lookups.

Watchtime

Returns the watchtime stored by Kicklet for a viewer.

Engine v2

Viewer watchtime

Returns the stored watchtime for a viewer as formatted text.

Viewer watchtimeAdvanced Script

const watchtime = stats.watchtime(sender.username);
async.messages.send(`Watchtime: ${watchtime}`);

API reference

stats.watchtime

stats.watchtime(viewer)

Input

viewer

string

Viewer username.

Output

string

Formatted watchtime such as 4h 18m.

Viewer watchtime seconds

Returns the stored watchtime for a viewer as seconds.

Viewer watchtime secondsAdvanced Script

const seconds = stats.watchtimeSeconds(sender.username);
async.messages.send(`Watchtime seconds: ${seconds}`);

API reference

stats.watchtimeSeconds

stats.watchtimeSeconds(viewer)

Input

viewer

string

Viewer username.

Output

number

Watchtime in seconds.

Engine v1

Your watchtime: {{kicklet.Watchtime sender.String}}
The watchtime of exampleUser is {{kicklet.Watchtime "exampleUser"}}.

Advanced Script:

const watchtime = Kicklet.watchtime("userName").then((resp) => resp.data.watchtime);

Follow Age

Returns how long a viewer has followed the channel.

Engine v2

Returns how long a viewer has followed the channel.

API reference

channel.followAge

channel.followAge(username)

Input

username

string

Kick username.

Output

string

Formatted follow age, or an empty string when unavailable.

Viewer follow ageAdvanced Script

const followAge = channel.followAge(sender.username);
async.messages.send(`You are following since ${followAge}.`);

channel.followAge(viewer) returns formatted text. Use channel.followAgeSeconds(viewer) for a numeric age, or channel.followingSince(viewer) when you need the raw follow timestamp.

Returns how long a viewer has followed the channel in seconds.

API reference

channel.followAgeSeconds

channel.followAgeSeconds(username)

Input

username

string

Kick username.

Output

number

Follow age in seconds, or 0 when unavailable.

Viewer follow age secondsAdvanced Script

const seconds = channel.followAgeSeconds(sender.username);
async.messages.send(`Follow age seconds: ${seconds}`);

Returns when a viewer started following the channel.

API reference

channel.followingSince

channel.followingSince(username)

Input

username

string

Kick username.

Output

string

Follow start timestamp, or an empty string when unavailable.

Viewer follow timestampAdvanced Script

const followedAt = channel.followingSince(sender.username);
async.messages.send(`Following since: ${followedAt}`);

channel.user(viewer) returns the full channel viewer object, including:

{
  "username": "exampleUser",
  "slug": "exampleuser",
  "isStaff": false,
  "isChannelOwner": false,
  "isModerator": false,
  "subscribedFor": 0,
  "followingSince": "2026-04-08T11:43:14Z",
  "followAgeSeconds": 2592000,
  "followAge": "30d 0h 0m",
  "hasBadge": "function",
  "hasPermission": "function"
}

Send channel user dataAdvanced Script

const viewer = channel.user(sender.username);
async.messages.send(`${viewer.username} subscribed for ${viewer.subscribedFor} months.`);

Engine v1

You are following since {{kick.FollowAge sender.String}}.

Advanced Script:

const sender = $event.getSender();
const followAge = Kick.getChannelUser(sender).then((resp) => resp.following_since);

Giveaways

Use the giveaway helpers when a script should create, enter, roll, or end an existing Kicklet giveaway.

Engine v2

Enter giveaway

Adds a viewer to a giveaway. Defaults to sender.username when username is omitted.

Enter current senderAdvanced Script

giveaway.enter(123);
async.messages.send(`${sender.username} joined the giveaway.`);

API reference

giveaway.enter

giveaway.enter(id, username?)

Input

id

number

Giveaway ID.

usernameoptional

string

Viewer username.

Output

boolean

True when the backend accepted the entry.

List giveaway entries

Lists entries for one giveaway.

API reference

giveaway.entries

giveaway.entries(id, options?)

Input

id

number

Giveaway ID.

optionsoptional

object

Optional page, pageSize, search, and state settings.

pageoptional

number

Page number. Defaults to 1.

pageSizeoptional

number

Maximum entries to return. Defaults to 50 and is clamped to 100.

searchoptional

string

Search text for entry filtering.

stateoptional

string

Entry state filter.

Output

object

Giveaway entry list with count and entries.

Remove giveaway entry

Removes one entry from a giveaway.

API reference

giveaway.removeEntry

giveaway.removeEntry(giveawayId, entryId)

Input

giveawayId

number

Giveaway ID.

entryId

number

Giveaway entry ID.

Output

boolean

True when the entry was removed.

Clear giveaway entries

Clears entries from a giveaway. Pass state when only entries in one state should be cleared.

API reference

giveaway.clear

giveaway.clear(id, state?)

Input

id

number

Giveaway ID.

stateoptional

string

Optional entry state filter.

Output

boolean

True when entries were cleared.

Roll giveaway winner

Rolls a winner for a giveaway.

Roll winnerAdvanced Script

const winner = giveaway.roll(123);
async.messages.send(`Winner: ${winner.username}`);

API reference

giveaway.roll

giveaway.roll(id)

Input

id

number

Giveaway ID.

Output

object

Winning giveaway entry.

List giveaways

Lists active or archived giveaways.

API reference

giveaway.list

giveaway.list(options?)

Input

optionsoptional

object

Optional page, pageSize, and state settings. State can be active or archived.

Output

object

Giveaway list with count and giveaways.

Create giveaway

Creates a Kicklet giveaway.

API reference

giveaway.create

giveaway.create(options)

Input

options

object

Giveaway settings such as entryType, keyword, costs, inactivityTimeout, and chatMessage.

Output

object

Created giveaway.

Reroll giveaway winner

Replaces the last winner with a new winner.

API reference

giveaway.reroll

giveaway.reroll(id)

Input

id

number

Giveaway ID.

Output

object

New winning giveaway entry.

End giveaway

Ends an active giveaway.

API reference

giveaway.end

giveaway.end(id)

Input

id

number

Giveaway ID.

Output

boolean

True when the giveaway was ended.

Async giveaway wrappers

Async wrapper for giveaway.enter(id, username).

API reference

async.giveaway.enter

async.giveaway.enter(id, username?)

Input

id

number

Giveaway ID.

usernameoptional

string

Viewer username.

Output

boolean

True when the backend accepted the entry.

Async wrapper for giveaway.list(options?).

API reference

async.giveaway.list

async.giveaway.list(options?)

Input

optionsoptional

object

Optional page, pageSize, and state settings. State can be active or archived.

Output

object

Giveaway list with count and giveaways.

Async wrapper for giveaway.create(options).

API reference

async.giveaway.create

async.giveaway.create(options)

Input

options

object

Giveaway settings such as entryType, keyword, costs, inactivityTimeout, and chatMessage.

Output

object

Created giveaway.

Async wrapper for giveaway.entries(id, options?).

API reference

async.giveaway.entries

async.giveaway.entries(id, options?)

Input

id

number

Giveaway ID.

optionsoptional

object

Optional page, pageSize, search, and state settings.

pageoptional

number

Page number. Defaults to 1.

pageSizeoptional

number

Maximum entries to return. Defaults to 50 and is clamped to 100.

searchoptional

string

Search text for entry filtering.

stateoptional

string

Entry state filter.

Output

object

Giveaway entry list with count and entries.

Async wrapper for giveaway.removeEntry(giveawayId, entryId).

API reference

async.giveaway.removeEntry

async.giveaway.removeEntry(giveawayId, entryId)

Input

giveawayId

number

Giveaway ID.

entryId

number

Giveaway entry ID.

Output

boolean

True when the entry was removed.

Async wrapper for giveaway.clear(id, state?).

API reference

async.giveaway.clear

async.giveaway.clear(id, state?)

Input

id

number

Giveaway ID.

stateoptional

string

Optional entry state filter.

Output

boolean

True when entries were cleared.

Async wrapper for giveaway.roll(id).

API reference

async.giveaway.roll

async.giveaway.roll(id)

Input

id

number

Giveaway ID.

Output

object

Winning giveaway entry.

Async wrapper for giveaway.reroll(id).

API reference

async.giveaway.reroll

async.giveaway.reroll(id)

Input

id

number

Giveaway ID.

Output

object

New winning giveaway entry.

Async wrapper for giveaway.end(id).

API reference

async.giveaway.end

async.giveaway.end(id)

Input

id

number

Giveaway ID.

Output

boolean

True when the giveaway was ended.

Engine v1

Use the configured giveaway commands and giveaway winner message templates.

Async viewer activity wrappers

Async wrapper for stats.watchtime(viewer).

API reference

async.stats.watchtime

async.stats.watchtime(viewer)

Input

viewer

string

Viewer username.

Output

string

Formatted watchtime such as 4h 18m.

Async wrapper for stats.watchtimeSeconds(viewer).

API reference

async.stats.watchtimeSeconds

async.stats.watchtimeSeconds(viewer)

Input

viewer

string

Viewer username.

Output

number

Watchtime in seconds.

Async wrapper for stats.activeViewers().

API reference

async.stats.activeViewers

async.stats.activeViewers()

Input

This helper does not take input parameters.

Output

number

Current active chatter count.

Async wrapper for stats.randomActiveViewers(count).

API reference

async.stats.randomActiveViewers

async.stats.randomActiveViewers(count)

Input

count

number

Maximum number of active viewers to return.

Output

object[]

Random active viewer objects.

id

number

Kick user ID when available.

username

string

Viewer username.

slug

string

Viewer slug when available.

Async wrapper for stats.messages(viewer).

API reference

async.stats.messages

async.stats.messages(viewer)

Input

viewer

string

Viewer username.

Output

number

Tracked message count.

Async wrapper for stats.subscriptions(days).

API reference

async.stats.subscriptions

async.stats.subscriptions(days)

Input

days

number

Time range in days.

Output

number

Subscription count in the selected time range.

Active Viewers Count

Returns how many viewers Kicklet currently considers active in chat. This is not the same as Kick's live viewer count.

Engine v2

Active chatter count

Returns how many viewers Kicklet currently considers active in chat. This is not Kick's live viewer count.

Active chatter countAdvanced Script

const activeChatters = stats.activeViewers();
async.messages.send(`Active chatters: ${activeChatters}`);

API reference

stats.activeViewers

stats.activeViewers()

Input

This helper does not take input parameters.

Output

number

Current active chatter count.

Engine v1

Active chatters: {{kicklet.ActiveViewersCount}}

Advanced Script:

Kicklet.activeViewersCount().then((resp) => resp.data);

Random Active Viewers

Returns random viewers from Kicklet's active chatter list. Use it for giveaways, random shoutouts, and roulette-style commands.

Engine v2

Random active viewers

Returns random viewers from Kicklet's active chatter list.

Random active viewersAdvanced Script

const viewers = stats.randomActiveViewers(3).map((viewer) => viewer.username);
const viewerNames = viewers.join(", ");

async.messages.send(`Random active viewers: ${viewerNames}`);

API reference

stats.randomActiveViewers

stats.randomActiveViewers(count)

Input

count

number

Maximum number of active viewers to return.

Output

object[]

Random active viewer objects.

id

number

Kick user ID when available.

username

string

Viewer username.

slug

string

Viewer slug when available.

Engine v1

Several active viewers:

Randomly selected viewers:
{{range $viewer := kicklet.ActiveViewersRandom 10}}
ID: {{$viewer.ID}}, Username: {{$viewer.Username}}
{{end}}

One active viewer:

Randomly selected active viewer: {{kicklet.ActiveViewerRandom.Username}}

Advanced Script:

Kicklet.activeViewersRandom(10).then((resp) => resp.data);

Messages Count

Returns how many chat messages Kicklet has tracked for a viewer.

Engine v2

Viewer message count

Returns how many chat messages Kicklet has tracked for a viewer.

Viewer message countAdvanced Script

const messageCount = stats.messages(sender.username);
async.messages.send(`Messages sent: ${messageCount}`);

API reference

stats.messages

stats.messages(viewer)

Input

viewer

string

Viewer username.

Output

number

Tracked message count.

Engine v1

Messages sent: {{kicklet.MessagesCount sender.String}}

Advanced Script:

Kicklet.messagesCount("viewerName").then((resp) => resp.data);

Subscriber Count

Returns how many subscriptions Kicklet counted in the given number of days.

Engine v2

Subscription count

Returns how many subscriptions Kicklet counted in the given number of days.

Recent subscriptionsAdvanced Script

const subscriptions = stats.subscriptions(30);
async.messages.send(`Subscriptions in the last 30 days: ${subscriptions}`);

API reference

stats.subscriptions

stats.subscriptions(days)

Input

days

number

Time range in days.

Output

number

Subscription count in the selected time range.

Engine v1

Subscriptions in the last 30 days: {{kicklet.SubCount 30}}

Advanced Script:

Kicklet.subCount(30).then((resp) => resp.data.count);