Kappapps SDK

Appearance

Class: ChatEvent ​

Represents a chat event: a message (or a command) written by a viewer, along with its author, its Twitch tags (emotes, cheers/bits, badges…) and helpers to parse it (text, command, arguments, HTML with emotes).

Remarks ​

A ChatEvent is provided to you by the SDK in the chat callbacks (k.chat.onMessage, k.chat.onCommand) as the second argument, and by k.chat.getChatEvents(). You never have to instantiate it yourself.

Example ​

ts
// !say hello everyone
k.chat.onCommand('say', (user, event) => {
    const text = event.getArg(1).string();
    console.log(event.getCommand(), text); // 'say', 'hello'
});

Properties ​

datetime ​

ts
datetime: number;

Timestamp (in milliseconds) when the event was received.

message ​

ts
message: string;

twitch_tags ​

ts
twitch_tags: TwitchTagsData;

user ​

ts
user: User;

The author of the message (User).

Methods ​

getArg() ​

ts
getArg(index): ChatEventArg;

Returns the command argument at the given position, wrapped in a ChatEventArg (which offers string(), number(), user(), date(), url()…).

Parameters ​

index ​

number

Argument position, starting from 1.

Returns ​

ChatEventArg

A ChatEventArg (its internal value is null if the argument is absent).

Example ​

ts
// !give @viewer 50
const target = await event.getArg(1).user();
const amount = event.getArg(2).number();

See ​

getArgs, hasArg

getArgs() ​

ts
getArgs(): ChatEventArg[];

Returns all the command arguments, each wrapped in a ChatEventArg.

Returns ​

ChatEventArg[]

The list of arguments (empty if the event is not a command).

See ​

getArg for a single argument.

getArgsCount() ​

ts
getArgsCount(): number;

Returns the number of arguments of the command.

Returns ​

number

The number of arguments (0 if the event is not a command).

getArgsRaw() ​

ts
getArgsRaw(): string[];

Returns the raw command arguments as strings (the command itself and the @ characters are stripped out).

Returns ​

string[]

The list of arguments (empty if the event is not a command).

See ​

getArgs for enriched arguments.

getBadges() ​

ts
getBadges(): TwitchBadge[];

Returns the badges worn by the message's author, parsed from the Twitch tags.

Returns ​

TwitchBadge[]

The list of badges { set_id, version }, in Twitch display order (empty if the author wears none).

Example ​

ts
k.chat.onMessage(async (user, event) => {
    const badges = await k.emotes.getBadges(event.getBadges());
    // -> resolved badges with image URLs and titles
});

See ​

k.emotes.getBadges to resolve them into displayable images.

getCheer() ​

ts
getCheer(): number;

Returns the number of bits (cheer) attached to the message.

Returns ​

number

The bits amount, or 0 if the message is not a cheer.

See ​

isCheer

getCommand() ​

ts
getCommand(): string;

Returns the command name (without the symbol, lowercased and without accents).

Returns ​

string

The command name, or null if the event is not a command.

Example ​

ts
// message: "!Dé 6"  ->  getCommand() === 'de'

See ​

isCommand, getArg

getDatetime() ​

ts
getDatetime(): number;

Returns the timestamp when the event was received.

Returns ​

number

The timestamp in milliseconds.

getEmotes() ​

ts
getEmotes(): TwitchTagsEmotesData;

Returns the emotes present in the message (mapping of emote id → positions).

Returns ​

TwitchTagsEmotesData

The message emotes, or null if there are none.

getMessage() ​

ts
getMessage(purify?): string;

Returns the message text, sanitized by default against HTML injection.

Parameters ​

purify? ​

boolean = true

If true, the text is run through DOMPurify before being returned.

Returns ​

string

The message text, or null if the event is a command.

Default Value ​

true

Remarks ​

Returns null for commands: use getCommand and getArgs in that case.

See ​

getMessageAsHtml for an HTML rendering with emotes.

getMessageAsHtml() ​

ts
getMessageAsHtml(options?): string;

Returns the message as HTML, where Twitch emotes are replaced by their images and the text is escaped.

Parameters ​

options? ​

GetMessageAsHtmlOptions = {}

Rendering options — see GetMessageAsHtmlOptions for the details of each field (emotes_size, replace_functions).

Returns ​

string

The message HTML, or null if the event is a command.

Example ​

ts
k.chat.onMessage((user, event) => {
    document.querySelector('#chat').innerHTML += event.getMessageAsHtml({ emotes_size: 48 });
});

See ​

getMessage for the raw text.

getMessageId() ​

ts
getMessageId(): string;

Returns the Twitch identifier of the message (used in particular to reply to it in a thread).

Returns ​

string

The message id.

See ​

respond

getSubscriberMonths() ​

ts
getSubscriberMonths(): number;

Returns the author's exact subscription tenure in months (read from the badge-info tag — more precise than the milestone badge displayed, which only changes at 2, 3, 6, 9 months…).

Returns ​

number

The number of months, or 0 if the author is not a subscriber.

See ​

isSubscriber, getSubscriberTier

getSubscriberTier() ​

ts
getSubscriberTier(): 1 | 2 | 3;

Returns the author's subscription tier, derived from the subscriber badge version (3xxx → tier 3, 2xxx → tier 2, otherwise tier 1).

Returns ​

1 | 2 | 3

1, 2 or 3, or null if not determinable — the author wears no subscriber badge (not a subscriber, or a founder displaying the founder badge instead).

See ​

isSubscriber, getSubscriberMonths

getTwitchTags() ​

ts
getTwitchTags(): TwitchTagsData;

Returns the raw Twitch tags associated with the message (badges, color, bits…).

Returns ​

TwitchTagsData

The Twitch tags (TwitchTagsData).

getUser() ​

ts
getUser(): User;

Returns the author of the message.

Returns ​

User

The User who wrote the message.

hasArg() ​

ts
hasArg(index): boolean;

Indicates whether the command has a non-empty argument at the given position.

Parameters ​

index ​

number

Argument position, starting from 1 (1 = first argument after the command).

Returns ​

boolean

true if a non-empty argument exists at this position.

See ​

getArg

isCheer() ​

ts
isCheer(): boolean;

Indicates whether the message contains a cheer (Twitch bits donation).

Returns ​

boolean

true if bits are attached to the message.

See ​

getCheer

isCommand() ​

ts
isCommand(): boolean;

Indicates whether the event is a command: its message starts with the command symbol configured for the channel (! by default).

Returns ​

boolean

true if it is a command.

See ​

isMessage, getCommand

isMessage() ​

ts
isMessage(): boolean;

Indicates whether the event is a regular message (not a command).

Returns ​

boolean

true if it is a regular message.

See ​

isCommand

isSubscriber() ​

ts
isSubscriber(): boolean;

Indicates whether the author is a subscriber (or founder) of the channel.

Returns ​

boolean

true if the author subscribes to the channel.

See ​

getSubscriberMonths, getSubscriberTier

respond() ​

ts
respond(message): Promise<void>;

Replies to the message in the chat. If the Twitch tags are available, the reply is sent as a thread (reply to the original message); otherwise, it mentions the author (@nickname, …).

Parameters ​

message ​

string

The reply text.

Returns ​

Promise<void>

A promise resolved once the reply has been sent.

Example ​

ts
k.chat.onCommand('ping', (user, event) => event.respond('pong 🏓'));