Appearance
Class: ChatService
Service for interacting with the channel's Twitch chat: send messages, make announcements, react to viewers' messages and commands, and list the active viewers.
Remarks
Available everywhere via k.chat. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.
The `onMessage` and `onCommand` methods are the foundation of most interactive apps: they hook you into what the chat types. These methods only receive messages authored in this channel. Use onSharedMessage and onSharedCommand to opt into other channels' Shared Chat messages, without changing the local chat behavior.
Example
ts
// Greet every new message and react to the !ping command
k.chat.onMessage((user) => {
console.log(`${user.display_name} spoke`);
});
k.chat.onCommand('ping', async (user) => {
await k.chat.say(`pong @${user.display_name} 🏓`);
});Implements
Properties
twitch
ts
twitch: ChatTwitchService;Twitch chat settings and low-level chat operations.
Accessors
activity
Get Signature
ts
get activity(): ChatActivity;The current chat activity level (ChatActivity), readable synchronously at any time (no need to wait for a change via onActivityChange).
Example
ts
if (k.chat.activity?.isHot()) {
k.overlay.notification('Chat is on fire! 🔥');
}See
getActivityState for just the bucket name.
Returns
The current ChatActivity, or null if none has been received yet (right at app startup, before the platform's first computation).
Methods
announce()
ts
announce(message, color?): Promise<void>;Publishes a Twitch announcement: a message highlighted in the chat, with a colored banner (equivalent to the /announce command).
Parameters
message
string
The announcement text.
color?
AnnounceColor = 'primary'
Color of the announcement banner.
Returns
Promise<void>
A promise resolved once the announcement has been sent.
Default Value
'primary'
Example
ts
await k.chat.announce('The game starts in 1 minute!', 'green');See
say for a regular message.
getActiveUsers()
ts
getActiveUsers(options?): User[];Returns the list of active viewers: those who have written in this channel's chat recently. Handy for drawing random participants, displaying the present community, etc.
Parameters
options?
Filters and sorting applied to the selection — see GetActiveUsersOptions for the details of each field (time, excludes, count, randomize, property).
Returns
User[]
An array of active Users (empty if no one has spoken recently).
Examples
ts
// Draw 1 random active viewer to give them a gift
const [winner] = k.chat.getActiveUsers({ count: 1, randomize: true });
if (winner) {
await k.chat.say(`🎁 ${winner.display_name} wins the draw!`);
}ts
// The viewers who spoke in the last 5 minutes, except the streamer
const active = k.chat.getActiveUsers({
time: 300,
excludes: [{ login: k.channel.twitchUser.login }],
});getActivityState()
ts
getActivityState(): ChatActivityState;The current chat activity bucket ('silent', 'calm', 'active' or 'hot'), readable synchronously at any time.
Returns
The current ChatActivityState, defaulting to 'calm' if none has been received yet (right at app startup).
See
activity for the full ChatActivity object.
getChatEvents()
ts
getChatEvents(count?): Promise<ChatEvent[]>;Retrieves the recent history of local chat events (messages and commands) from the backend.
Parameters
count?
number = 100
Maximum number of events to retrieve (the most recent ones).
Returns
Promise<ChatEvent[]>
The list of recent ChatEvents, from oldest to most recent.
Default Value
100
Remarks
Unlike onMessage (real-time), this method makes a network call to replay the past — useful when an app starts to rebuild a state. Messages originating in other Shared Chat channels are live-only and excluded.
Example
ts
const events = await k.chat.getChatEvents(50);
console.log(`${events.length} events retrieved`);onActivityChange()
ts
onActivityChange(callback): void;Registers a callback invoked whenever the chat activity level changes (e.g. calm → active).
Parameters
callback
Function called with the new ChatActivity each time the platform recomputes the channel's activity bucket.
Returns
void
Remarks
The activity level is relative to the channel's own baseline message rate (see ChatActivity), not an absolute message count. For the current value without waiting for a change, read activity (or getActivityState) directly.
Example
ts
k.chat.onActivityChange((activity) => {
if (activity.hasRisen() && activity.isHot()) {
k.overlay.notification('Chat is on fire! 🔥');
}
});onCommand()
ts
onCommand(
keywords,
callback,
options?): void;Registers a callback triggered by a chat command (a message starting with !), with optional permission handling and one-time triggering.
Parameters
keywords
The command(s) to listen for, without the !:
- a string (
'roll'→ listens for!roll), - an array (
['roll', 'dice']→ listens for!rolland!dice), null→ listens for all commands.
callback
Function called with the author (User) and the event (ChatEvent, which gives access to the arguments via event.getArg(n)).
options?
ChatCommandOptions = {}
Triggering options.
Returns
void
Examples
ts
// Public command with an argument: !say hello
k.chat.onCommand('say', (user, event) => {
const text = event.getArg(1).string();
k.chat.say(`${user.display_name} says: ${text}`);
});ts
// Command restricted to channel admins
k.chat.onCommand('reset', () => resetGame(), { grantedRole: 'admin' });See
onMessage to react to normal messages.
onMessage()
ts
onMessage(callback): void;Registers a callback invoked on every message in the chat (excluding commands).
Parameters
callback
Function called on each message, with the author (User) and the full event (ChatEvent).
Returns
void
Remarks
Only "normal" messages trigger this callback; messages that are commands (starting with !) go through onCommand.
Example
ts
k.chat.onMessage((user, event) => {
if (event.getMessage().includes('🐧')) {
k.chat.say(`${user.display_name} loves penguins!`);
}
});onSharedCommand()
ts
onSharedCommand(
keywords,
callback,
options?): void;Listens to live commands originating in other Shared Chat channels.
Parameters
keywords
Command name(s) without the symbol, or null for all commands.
callback
Called with the author and the event, as for onCommand.
options?
ChatCommandOptions = {}
Same once and grantedRole options as onCommand.
Returns
void
Remarks
Permissions and the command symbol belong to this app's channel, not the source channel. Only this callback opts in: local commands, triggers, history and active viewers remain local. No Core activation is sent.
onSharedMessage()
ts
onSharedMessage(callback): void;Listens to live messages originating in other channels of the Shared Chat session. Commands go through onSharedCommand.
Parameters
callback
Called with the author and the event, as for onMessage.
Returns
void
Remarks
This subscription only affects this app. It does not enable a Core mode, feed local active viewers or provide history. Origin identifiers are in event.getTwitchTags()['source-room-id'] and ['source-id']. Replies still target this app's channel. Source-channel badges confer no local permissions.
say()
ts
say(message): Promise<void>;Sends a text message to the channel's Twitch chat, on behalf of the bot.
Parameters
message
string
The text to post (displayed as-is in the chat).
Returns
Promise<void>
A promise resolved once the message has been sent to Twitch.
Example
ts
await k.chat.say('Welcome to the stream! 🎉');See
announce for a highlighted message (colored announcement).
shoutout()
ts
shoutout(channel): Promise<void>;Performs a shoutout to another Twitch channel (equivalent to /shoutout).
Parameters
channel
string
The login (Twitch username) of the channel to promote.
Returns
Promise<void>
A promise resolved once the shoutout has been sent.
Example
ts
await k.chat.shoutout('twitchdev');