Kappapps SDK

Appearance

Class: User ​

Rich model of a channel viewer (Player): Twitch identity, Kappapps role, internal currency, ranking, items, app data, moderation, etc.

Remarks ​

A User is almost never built by hand: it is provided to you by the SDK in the chat callbacks (k.chat.onMessage, k.chat.onCommand), retrieved via k.users.get(...), or via the static factories fromLogin / fromId.

Some properties (currency, ranking, items…) are not always loaded: their async getters fetch the missing data from the backend on the first call.

Example ​

ts
k.chat.onCommand('solde', async (user) => {
    const currency = await user.getCurrency();
    await k.chat.say(`@${user.display_name} has ${currency} coins`);
});

Properties ​

display_name ​

ts
display_name: string;

Twitch display name (with original casing and characters).

id ​

ts
id: number;

Numeric Twitch identifier of the viewer.

is_moderator ​

ts
is_moderator: boolean;

true if the viewer is a moderator of the channel.

login ​

ts
login: string;

Twitch login (lowercase username, without @).

raw_creation_data ​

ts
raw_creation_data: 
  | UserData
  | CoreUserData;

Raw data used to build this object (as received from the backend).

role ​

ts
role: KappappsRoleType;

Kappapps role of the viewer (e.g. 'admin', 'mod', 'player').

Methods ​

addCurrency() ​

ts
addCurrency(amount): Promise<User>;

Adds internal currency to the viewer's balance.

Parameters ​

amount ​

number

The amount to credit.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Example ​

ts
await user.addCurrency(50);

See ​

removeCurrency, setCurrency

addItem() ​

ts
addItem(item, quantity?): Promise<User>;

Adds one or more copies of an item to the viewer's inventory.

Parameters ​

item ​

Pick<ChannelItemData, "id">

The channel item to add; only its id is required.

quantity? ​

number = 1

The number of copies to add.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Default Value ​

1

See ​

removeItem, getItems

getAiBotContext() ​

ts
getAiBotContext(): Promise<string>;

Returns the viewer's AI context: custom text provided to the AI bot to tailor its responses to this viewer.

Returns ​

Promise<string>

The viewer's AI context.

Remarks ​

Loads the data from the backend if it is not already in memory.

getAppData() ​

ts
getAppData(): Promise<AppDataData>;

Returns the app data specific to this viewer (persistent state that your app stores for them).

Returns ​

Promise<AppDataData>

The viewer's app data, or null if none is defined.

Remarks ​

Reserved for the app context: throws an AppMethodError if called outside an app. Loads the data from the backend if it is not already in memory.

See ​

setAppData

Deprecated ​

Use kapp.userDataStorageV2.get(user.id); User keeps the V1 snapshot.

getAvatarData() ​

ts
getAvatarData(): Promise<AvatarData>;

Returns the viewer's avatar data (equipment, character parts…).

Returns ​

Promise<AvatarData>

The avatar data.

Remarks ​

Loads the data from the backend if it is not already in memory.

getAvatarPng() ​

ts
getAvatarPng(options?): Promise<string>;

Returns the viewer's Kappapps avatar rendered as a PNG image.

Parameters ​

options? ​

AvatarPngOptions = {}

Render options (size, animation, equipment, trimming…).

Returns ​

Promise<string>

A data:image/png;base64,… URL, usable straight as an <img> source inside the app, or convertible to a Blob with k.Utils.Media.base64ToBlob(png, 'image/png') (to upload it, for instance).

Default Value ​

{}

Remarks ​

This is the Kappapps avatar (the character the viewer customizes), not their Twitch profile picture — for that one, see getProfileImageUrl.

The first call loads the Phaser engine and the avatar module (a few hundred KB), then renders one frame off-screen. Reuse the returned string instead of calling this on every use.

The image lives in the app only: announcement/notification visuals accept neither data URLs nor external URLs, so it cannot be passed as a visual.

Example ​

ts
const png = await user.getAvatarPng({ height: 256 });
document.querySelector('img.avatar').src = png;

See ​

getAvatarData for the raw pieces.

getBanTime() ​

ts
getBanTime(): Promise<number>;

Returns the viewer's remaining ban (timeout) duration.

Returns ​

Promise<number>

The current ban duration (in seconds).

Remarks ​

Loads the data from the backend if it is not already in memory.

getBroadcasterType() ​

ts
getBroadcasterType(): Promise<string>;

Returns the viewer's Twitch broadcaster type (e.g. 'affiliate', 'partner', or empty string).

Returns ​

Promise<string>

The Twitch broadcaster_type.

Remarks ​

Loads the data from the backend if it is not already in memory.

getCurrency() ​

ts
getCurrency(): Promise<number>;

Returns the viewer's internal currency balance on the channel.

Returns ​

Promise<number>

The amount of currency held.

Remarks ​

Loads the data from the backend if it is not already in memory.

See ​

addCurrency, removeCurrency, setCurrency

getDisplayName() ​

ts
getDisplayName(): string;

Returns the Twitch display name of the viewer.

Returns ​

string

The display name (with original casing).

getFollowAnnounce() ​

ts
getFollowAnnounce(): Promise<boolean>;

Indicates whether the viewer has enabled the follow announcement.

Returns ​

Promise<boolean>

true if the follow announcement is enabled for this viewer.

Remarks ​

Loads the data from the backend if it is not already in memory.

getFollowStatus() ​

ts
getFollowStatus(): Promise<UserFollowStatus>;

Retrieves the viewer's current Twitch follow status on this channel.

Returns ​

Promise<UserFollowStatus>

Whether the viewer follows the channel and the ISO-8601 follow date.

Remarks ​

This is a live Twitch lookup: every call performs a new network request and no result is cached. Applications must declare the channel-stats:read scope, and the streamer must have granted Twitch's moderator:read:followers scope. Missing permissions and Twitch errors reject the promise instead of returning a negative status.

Example ​

ts
const status = await user.getFollowStatus();
if (status.following) {
    console.log(`Follower since ${status.followed_at}`);
}

getGamesPlayed() ​

ts
getGamesPlayed(): Promise<number>;

Returns the number of games played by the viewer.

Returns ​

Promise<number>

The number of games played.

Remarks ​

Loads the data from the backend if it is not already in memory.

See ​

getGamesWon

getGamesWon() ​

ts
getGamesWon(): Promise<number>;

Returns the number of games won by the viewer.

Returns ​

Promise<number>

The number of games won.

Remarks ​

Loads the data from the backend if it is not already in memory.

See ​

getGamesPlayed

getId() ​

ts
getId(): number;

Returns the numeric Twitch identifier of the viewer.

Returns ​

number

The Twitch identifier.

getItems() ​

ts
getItems(): Promise<UserItemData[]>;

Returns the items owned by the viewer (inventory).

Returns ​

Promise<UserItemData[]>

The list of the viewer's items.

Remarks ​

Loads the data from the backend if it is not already in memory.

See ​

addItem, removeItem

getLogin() ​

ts
getLogin(): string;

Returns the Twitch login of the viewer.

Returns ​

string

The login (lowercase username).

getProfileImageUrl() ​

ts
getProfileImageUrl(): Promise<string>;

Returns the URL of the viewer's Twitch avatar.

Returns ​

Promise<string>

The URL of the profile image.

Remarks ​

If the data is not yet loaded, a network call is made to fetch it.

getRankingPoints() ​

ts
getRankingPoints(): Promise<number>;

Returns the viewer's number of ranking points on the channel.

Returns ​

Promise<number>

The ranking points.

Remarks ​

Loads the data from the backend if it is not already in memory.

getRole() ​

ts
getRole(): KappappsRoleType;

Returns the Kappapps role of the viewer.

Returns ​

KappappsRoleType

The role (e.g. 'admin', 'mod', 'player').

See ​

setRole to modify it.

getSubscriptionStatus() ​

ts
getSubscriptionStatus(): Promise<UserSubscriptionStatus>;

Retrieves the viewer's current Twitch subscription status on this channel.

Returns ​

Promise<UserSubscriptionStatus>

Whether the viewer is subscribed, their tier and whether the sub was gifted.

Remarks ​

This is a live Twitch lookup: every call performs a new network request and no result is cached. Applications must declare the channel-stats:read scope, and the streamer must have granted Twitch's channel:read:subscriptions scope. Missing permissions and Twitch errors reject the promise instead of returning a negative status.

Example ​

ts
const status = await user.getSubscriptionStatus();
if (status.subscribed) {
    console.log(`Tier ${status.tier}${status.is_gift ? ' (gift)' : ''}`);
}

isActive() ​

ts
isActive(duration?): boolean;

Indicates whether the viewer is active, i.e. whether they have written in the chat within the last duration seconds.

Parameters ​

duration? ​

number = Options.ACTIVE_USER_DURATION

Activity window in seconds.

Returns ​

boolean

true if the viewer has spoken recently.

Default Value ​

The duration configured by the platform (Options.ACTIVE_USER_DURATION).

See ​

k.chat.getActiveUsers to list all active viewers.

isBlacklist() ​

ts
isBlacklist(): Promise<boolean>;

Indicates whether the viewer is on the channel's blacklist.

Returns ​

Promise<boolean>

true if the viewer is blacklisted.

Remarks ​

Loads the data from the backend if it is not already in memory.

See ​

setBlacklist, removeBlacklist

isDeveloper() ​

ts
isDeveloper(): Promise<boolean>;

Indicates whether the viewer is a Kappapps developer.

Returns ​

Promise<boolean>

true if they are a developer.

Remarks ​

Loads the data from the backend if it is not already in memory.

isGranted() ​

ts
isGranted(grantedRole): boolean;

Indicates whether the viewer has at least the requested role (according to the Kappapps role hierarchy).

Parameters ​

grantedRole ​

KappappsRoleType

The minimum required role (e.g. 'mod', 'admin').

Returns ​

boolean

true if the viewer's role is sufficient.

Example ​

ts
k.chat.onCommand('reset', (user) => {
    if (user.isGranted('mod')) resetGame();
});

isModerator() ​

ts
isModerator(): boolean;

Indicates whether the viewer is a moderator of the channel.

Returns ​

boolean

true if they are a moderator.

isOfficialDeveloper() ​

ts
isOfficialDeveloper(): Promise<boolean>;

Indicates whether the viewer is a Kappapps official developer.

Returns ​

Promise<boolean>

true if they are an official developer.

Remarks ​

Loads the data from the backend if it is not already in memory.

onChatCommand() ​

ts
onChatCommand(keywords, callback): void;

Registers a callback triggered by a command written by this specific viewer.

Parameters ​

keywords ​

ChatCommandKeywords

The command(s) to listen for, without the ! (string, array, or null for all commands).

callback ​

OnChatCommandFunction

Function called with the event (ChatEvent).

Returns ​

void

See ​

onChatMessage to react to their messages.

onChatMessage() ​

ts
onChatMessage(callback): void;

Registers a callback called on each message (other than commands) written by this specific viewer in the chat.

Parameters ​

callback ​

OnChatMessageFunction

Function called with the message text and the event (ChatEvent).

Returns ​

void

See ​

onChatCommand to react to their commands.

onUpdate() ​

ts
onUpdate(callback): void;

Registers a callback called on each update of this viewer (currency, role, items… modified on the backend side).

Parameters ​

callback ​

OnUserUpdateFunction

Function called with the freshly updated User.

Returns ​

void

Example ​

ts
user.onUpdate((u) => console.log('Profile updated', u.display_name));

removeBan() ​

ts
removeBan(): Promise<User>;

Lifts the viewer's ban.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Remarks ​

Uses kapp.users.moderation.unban() and the same moderation:ban permission as setBan() from manifest contract 4. Earlier contracts remain exempt; widgets do not declare app scopes. Twitch removes the active chat sanction, including a timeout. A backend refusal rejects the promise.

See ​

setBan

removeBlacklist() ​

ts
removeBlacklist(): Promise<User>;

Removes the viewer from the channel's blacklist.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

setBlacklist

removeCurrency() ​

ts
removeCurrency(amount): Promise<User>;

Removes internal currency from the viewer's balance.

Parameters ​

amount ​

number

The amount to debit.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

addCurrency, setCurrency

removeItem() ​

ts
removeItem(item): Promise<User>;

Removes an item from the viewer's inventory.

Parameters ​

item ​

Pick<ChannelItemData, "id">

The channel item to remove; only its id is required.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

addItem, getItems

removeModerator() ​

ts
removeModerator(): Promise<User>;

Removes the moderator status from the viewer.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

setModerator

removeTimeout() ​

ts
removeTimeout(): Promise<User>;

Lifts the viewer's current timeout.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Remarks ​

Uses the legacy moderation:manage route, which also lifts permanent Twitch bans. For the moderation:ban permission, use removeBan() instead.

See ​

setTimeout

removeVip() ​

ts
removeVip(): Promise<User>;

Removes the VIP status from the viewer.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

setVip

setAppData() ​

ts
setAppData(data): Promise<User>;

Saves the app data specific to this viewer.

Parameters ​

data ​

AppDataData

The data to persist for this viewer.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

getAppData

Deprecated ​

Use kapp.userDataStorageV2.set(user.id, data).

setBan() ​

ts
setBan(reason?): Promise<User>;

Permanently bans the viewer from the chat.

Parameters ​

reason? ​

string = null

Optional reason for the ban.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Remarks ​

This is a permanent Twitch chat ban. Available to widgets and all apps; apps require moderation:ban from manifest contract 4, with older versions exempt until their next newly created version, like kapp.users.moderation.ban().

Default Value ​

null

See ​

removeBan, setTimeout

setBlacklist() ​

ts
setBlacklist(value?): Promise<User>;

Sets whether the viewer is on the channel's blacklist.

Parameters ​

value? ​

boolean = true

true to add the viewer, false to remove them. Defaults to true.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

removeBlacklist

setCurrency() ​

ts
setCurrency(amount): Promise<User>;

Sets the viewer's internal currency balance to an exact value.

Parameters ​

amount ​

number

The new balance.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

addCurrency, removeCurrency

setModerator() ​

ts
setModerator(duration?): Promise<User>;

Grants the moderator status to the viewer.

Parameters ​

duration? ​

number = null

Status duration in seconds, or null for a status without expiration.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Default Value ​

null

See ​

removeModerator

setRole() ​

ts
setRole(role): Promise<User>;

Modifies the Kappapps role of the viewer (persisted on the backend side).

Parameters ​

role ​

KappappsRoleType

The new role to assign.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Remarks ​

Available to widgets and official Kappapps apps only; third-party apps receive 403. Assign animator, admin, or null to remove the role. Uses kapp.users.role.set() with the same access contract.

See ​

getRole to read it.

setTimeout() ​

ts
setTimeout(duration, reason?): Promise<User>;

Puts the viewer in timeout (temporary ban) on the chat.

Parameters ​

duration ​

number

Timeout duration in seconds.

reason? ​

string

Optional reason shown on the Twitch side.

Returns ​

Promise<User>

The current instance (User), to chain calls.

See ​

removeTimeout, setBan

setVip() ​

ts
setVip(duration?): Promise<User>;

Grants the VIP status to the viewer.

Parameters ​

duration? ​

number = null

VIP duration in seconds, or null for a VIP without expiration.

Returns ​

Promise<User>

The current instance (User), to chain calls.

Default Value ​

null

See ​

removeVip

setWarning() ​

ts
setWarning(reason): Promise<User>;

Sends a warning to the viewer.

Parameters ​

reason ​

string

Reason for the warning.

Returns ​

Promise<User>

The current instance (User), to chain calls.

fromCoreUserData() ​

ts
static fromCoreUserData(data): User;

Builds a lightweight User from a viewer's minimal data (id, login, display name, role, moderator). The rich fields (currency, items…) will be loaded on demand on the first call to their getter.

Parameters ​

data ​

CoreUserData

The viewer's "core" data (typically from a chat message).

Returns ​

User

The ready-to-use User instance.

Remarks ​

This is the factory used for viewers received via the chat, where the full profile data is not yet needed.

See ​

fromUserData for the complete version.

fromId() ​

ts
static fromId(id): Promise<User>;

Retrieves a viewer from their numeric Twitch identifier.

Parameters ​

id ​

number

The viewer's Twitch identifier.

Returns ​

Promise<User>

The matching User, or null if not found.

See ​

fromLogin for a search by login.

fromLogin() ​

ts
static fromLogin(login): Promise<User>;

Retrieves a viewer from their Twitch login.

Parameters ​

login ​

string

The login (Twitch username, without @).

Returns ​

Promise<User>

The matching User, or null if not found.

Example ​

ts
const user = await User.fromLogin('twitchdev');
if (user) {
    await user.addCurrency(100);
}

See ​

fromId for a search by identifier.

fromUserData() ​

ts
static fromUserData(data): User;

Builds a complete User from a viewer's detailed data (Twitch identity + currency, ranking, items, avatar…) and wires it to updates.

Parameters ​

data ​

UserData

Complete viewer data as returned by the backend.

Returns ​

User

The ready-to-use User instance.

See ​

fromCoreUserData for a lightweight version (chat).