Viewer Points

Points are the channel currency for viewers. Code can read balances, modify balances, and display the configured currency name.

Get a viewer's points

If the viewer has no point record yet, points.get() returns 0.

Engine v2

Reads a viewer point balance.

Get a viewer's pointsAdvanced Script

const balance = points.get("alice");
const currency = points.currency();

async.messages.send(`Alice has ${balance} ${currency}.`);

Missing viewer defaults to zeroAdvanced Script

const balance = points.get("zoe");
const currency = points.currency();

async.messages.send(`Zoe has ${balance} ${currency}.`);

API reference

points.get

points.get(userName)

Input

userName

string

Viewer username.

Output

number

Current point balance.

Engine v1

Engine v1 response example:

{{sender.String}} has {{kicklet.Points sender.String}} {{kicklet.Currency}}.

Advanced Script example:

Kicklet.getPoints($event.getSender()).then((resp) => resp.data.points);

Async point wrappers

Async wrapper for points.get(userName).

API reference

async.points.get

async.points.get(userName)

Input

userName

string

Viewer username.

Output

number

Current point balance.

Async wrapper for points.exists(userName).

API reference

async.points.exists

async.points.exists(userName)

Input

userName

string

Viewer username.

Output

boolean

True when the viewer has a point record.

Async wrapper for points.set(userName, points).

API reference

async.points.set

async.points.set(userName, points)

Input

userName

string

Viewer username.

points

number

New point balance.

Output

number

Stored point balance.

Async wrapper for points.add(userName, points).

API reference

async.points.add

async.points.add(userName, points)

Input

userName

string

Viewer username.

points

number

Points to add. Use a negative value to remove points. The balance cannot go below zero.

Output

number

Updated point balance.

Async wrapper for points.remove(userName, points).

API reference

async.points.remove

async.points.remove(userName, points)

Input

userName

string

Viewer username.

points

number

Points to remove.

Output

number

Updated point balance.

Async wrapper for points.addActiveViewers(points).

API reference

async.points.addActiveViewers

async.points.addActiveViewers(points)

Input

points

number

Points to add to each active viewer.

Output

number

Number of viewers that received points.

Async wrapper for points.currency().

API reference

async.points.currency

async.points.currency()

Input

This helper does not take input parameters.

Output

string

Configured point currency name.

Async wrapper for points.settings().

API reference

async.points.settings

async.points.settings()

Input

This helper does not take input parameters.

Output

object

Point settings for the channel.

pointsPerMessage

number

Points awarded for one eligible chat message.

pointsPerWatchTimeMinute

number

Points awarded for one active watchtime minute.

subscriberMultiplier

number

Reward multiplier for subscribers.

Example output

{
  "pointsPerMessage": 1,
  "pointsPerWatchTimeMinute": 5,
  "subscriberMultiplier": 2
}

Check whether a viewer has points

Use points.exists() when 0 and "no point record yet" need different handling.

Engine v2

Checks whether a viewer has an existing point record.

Existing point recordAdvanced Script

if (points.exists("alice")) {
  const balance = points.get("alice");
  const currency = points.currency();

  async.messages.send(`Alice has a point record with ${balance} ${currency}.`);
} else {
  async.messages.send("Alice has no point record yet.");
}

Missing point recordAdvanced Script

if (points.exists("zoe")) {
  const balance = points.get("zoe");
  const currency = points.currency();

  async.messages.send(`Zoe has a point record with ${balance} ${currency}.`);
} else {
  async.messages.send("Zoe has no point record yet.");
}

API reference

points.exists

points.exists(userName)

Input

userName

string

Viewer username.

Output

boolean

True when the viewer has a point record.

Engine v1

Engine v1 helpers in Engine v1 read missing point records as 0.

Set a point balance

Use this when you want to replace the current balance with an exact value.

Engine v2

Replaces a viewer point balance with an exact value.

Set a point balanceAdvanced Script

const balance = points.set(sender.username, 100);
const currency = points.currency();

async.messages.send(`${sender.username} now has ${balance} ${currency}.`);

API reference

points.set

points.set(userName, points)

Input

userName

string

Viewer username.

points

number

New point balance.

Output

number

Stored point balance.

Engine v1

Engine v1 response example:

{{sender.String}} now has {{kicklet.SetPoints sender.String 100}} {{kicklet.Currency}}.

Advanced Script example:

Kicklet.setPoints($event.getSender(), 100).then((resp) => resp.data);

Add points to a viewer

Use this for rewards, bonuses, or custom commands that grant points.

Engine v2

Adds points to a viewer.

Add points to a viewerAdvanced Script

const balance = points.add(sender.username, 10);
const currency = points.currency();

async.messages.send(`Reward sent. New balance: ${balance} ${currency}.`);

API reference

points.add

points.add(userName, points)

Input

userName

string

Viewer username.

points

number

Points to add. Use a negative value to remove points. The balance cannot go below zero.

Output

number

Updated point balance.

Engine v1

Engine v1 response example:

Reward sent. New balance: {{kicklet.AddPoints sender.String 10}} {{kicklet.Currency}}.

Advanced Script example:

Kicklet.addPoints($event.getSender(), 10).then((resp) => resp.data);

Remove points from a viewer

Use this for purchases, bets, or command costs. The balance cannot go below zero.

Engine v2

Removes points from a viewer. The balance cannot go below zero.

Remove points from a viewerAdvanced Script

const balance = points.remove(sender.username, 25);
const currency = points.currency();

async.messages.send(`Purchase complete. New balance: ${balance} ${currency}.`);

API reference

points.remove

points.remove(userName, points)

Input

userName

string

Viewer username.

points

number

Points to remove.

Output

number

Updated point balance.

Engine v1

Engine v1 response example:

Purchase complete. New balance: {{kicklet.RemovePoints sender.String 25}} {{kicklet.Currency}}.

Advanced Script example:

Kicklet.removePoints($event.getSender(), 25).then((resp) => resp.data);

Add points to active viewers

Use this to reward everyone currently considered active in chat. The helper returns how many viewers were affected.

Engine v2

Adds points to every viewer currently considered active in chat.

Add points to active viewersAdvanced Script

const viewers = points.addActiveViewers(50);
const currency = points.currency();

async.messages.send(`Added 50 ${currency} to ${viewers} active viewers.`);

API reference

points.addActiveViewers

points.addActiveViewers(points)

Input

points

number

Points to add to each active viewer.

Output

number

Number of viewers that received points.

Engine v1

Added 50 {{kicklet.Currency}} to {{kicklet.AddPointsViewers 50}} active viewers.

Read point settings

Use this when a command needs the configured currency name or reward settings.

Engine v2

Read point currency

Returns the channel configured point currency name.

Use points.currency() when a response should use the channel's configured point currency name instead of hard-coding points.

Currency nameAdvanced Script

const currency = points.currency();
async.messages.send(`Points are called ${currency} in this channel.`);

API reference

points.currency

points.currency()

Input

This helper does not take input parameters.

Output

string

Configured point currency name.

Read point settings

Returns the channel point reward settings.

Use points.settings().pointsPerMessage when a command needs to explain or calculate the configured reward for one chat message.

Message rewardAdvanced Script

const settings = points.settings();
const currency = points.currency();

async.messages.send(`Each chat message gives ${settings.pointsPerMessage} ${currency}.`);

Use points.settings().pointsPerWatchTimeMinute when a command needs the configured reward for one active watchtime minute.

Watchtime rewardAdvanced Script

const settings = points.settings();
const currency = points.currency();

async.messages.send(
  `Each active watchtime minute gives ${settings.pointsPerWatchTimeMinute} ${currency}.`,
);

Use points.settings().subscriberMultiplier when reward logic should mention or account for the subscriber bonus multiplier.

Subscriber multiplierAdvanced Script

const settings = points.settings();
async.messages.send(`Subscribers earn ${settings.subscriberMultiplier}x points.`);

API reference

points.settings

points.settings()

Input

This helper does not take input parameters.

Output

object

Point settings for the channel.

pointsPerMessage

number

Points awarded for one eligible chat message.

pointsPerWatchTimeMinute

number

Points awarded for one active watchtime minute.

subscriberMultiplier

number

Reward multiplier for subscribers.

Example output

{
  "pointsPerMessage": 1,
  "pointsPerWatchTimeMinute": 5,
  "subscriberMultiplier": 2
}

Engine v1

Currency: {{kicklet.Currency}}