Kappapps SDK

Appearance

Class: AnnounceService ​

Announcements service: broadcasts a message to one or more channels (Twitch chat, Twitch announcement, text-to-speech, on-screen notification/announcement, or a full multi-channel announcement).

Remarks ​

Available everywhere via k.announces. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

Most methods are shortcuts to other services (k.chat, k.overlay, k.textToSpeech). The announce method, on the other hand, lets you broadcast to several channels at once.

Example ​

ts
// Multi-channel announcement: message in chat + text-to-speech
await k.announces.announce({
    messages: ['Welcome to the stream!'],
    chatMessage: { enabled: true },
    textToSpeech: { enabled: true },
});

Implements ​

Methods ​

announce() ​

ts
announce(
   data, 
   tags?, 
   title?, 
metadata?): Promise<AnnounceModel>;

Broadcasts a multi-channel announcement: the same message can be sent simultaneously to chat, as a Twitch announcement, via text-to-speech, on screen, to Discord, etc., depending on the enabled tracks.

Parameters ​

data ​

AnnounceCreateData

Configuration of the announcement and its tracks — see AnnounceCreateData.

tags? ​

Record<string, string> = {}

Replacement values injected into the message (the #tag# patterns in the text are replaced by tags.tag). Some channel tags (e.g. channel_name, currency_symbol) are added automatically.

title? ​

string = null

Title passed to the tracks that use it (e.g. service calls).

metadata? ​

Record<string, any> = {}

Free-form metadata passed to the tracks that use it.

Returns ​

Promise<AnnounceModel>

The AnnounceModel that was built and played.

Default Value ​

{}

Default Value ​

null

Default Value ​

{}

Remarks ​

If no track is enabled in data, the announcement falls back to the default tracks configured in the channel's preferences.

Example ​

ts
await k.announces.announce({
    messages: ['#channel_name# thanks you!'],
    chatAnnounce: { enabled: true, color: 'green' },
    screenNotification: { enabled: true },
});

play() ​

ts
play(
   preference, 
   tags?, 
   title?, 
metadata?): Promise<void>;

Plays the announcement the streamer configured for this app, designated by the path of its preference — the same path you would pass to k.preferences.get.

Parameters ​

preference ​

string

Path of the announces preference to play (e.g. 'messages.onWin').

tags? ​

Record<string, string> = {}

Replacement values injected into the message (#tag# patterns).

title? ​

string = null

Title passed to the tracks that use it (e.g. service calls).

metadata? ​

Record<string, any> = {}

Free-form metadata passed to the tracks that use it.

Returns ​

Promise<void>

A promise resolved once the announcement has been accepted by the platform.

Default Value ​

{}

Default Value ​

null

Default Value ​

{}

Remarks ​

The app says when, the streamer says what and where: messages, variations, enabled tracks and the Discord webhook are read server-side from the channel's settings, so nothing sensitive is handed to the app. This is the shorthand for reading the preference and playing it — k.announces.announce(k.preferences.get(path), tags) does exactly the same, except that announce swallows a refusal whereas this method rejects, so you can react to a wrong path or a missing scope.

Example ​

ts
// The streamer decided whether this goes to chat, on screen, on Discord…
await k.announces.play('messages.onWin', { user: 'Sam', amount: '250' });

See ​

announce to broadcast an announcement your app builds itself.

screenAnnounce() ​

ts
screenAnnounce(message, options?): Promise<void>;

Displays an on-screen announcement (shortcut to k.overlay.announce).

Parameters ​

message ​

string

Text (or HTML) of the announcement.

options? ​

AnnounceOptions = {}

Display options — see AnnounceOptions.

Returns ​

Promise<void>

A promise resolved once the request has been sent.

Default Value ​

{}

screenNotification() ​

ts
screenNotification(message, options?): Promise<void>;

Displays an on-screen notification (shortcut to k.overlay.notification).

Parameters ​

message ​

string

Text (or HTML) of the notification.

options? ​

NotificationOptions = {}

Display options — see NotificationOptions.

Returns ​

Promise<void>

A promise resolved once the request has been sent.

Default Value ​

{}

speech() ​

Call Signature ​

ts
speech(message, moderate?): Promise<void>;

Reads a message aloud via text-to-speech (shortcut to k.textToSpeech.speech).

Parameters ​
message ​

string

The text to voice.

moderate? ​

boolean

If true, the text is moderated before being read.

Returns ​

Promise<void>

A promise resolved once the request has been sent.

Default Value ​

false

Call Signature ​

ts
speech(message, options?): Promise<void>;

Reads a message aloud via text-to-speech (shortcut to k.textToSpeech.speech).

Parameters ​
message ​

string

The text to voice.

options? ​

SpeechOptions

Returns ​

Promise<void>

A promise resolved once the request has been sent.

Default Value ​

false

twitchAnnounce() ​

ts
twitchAnnounce(message, color?): Promise<void>;

Posts a colored Twitch announcement in chat (shortcut to k.chat.announce).

Parameters ​

message ​

string

The announcement text.

color? ​

AnnounceColor = 'primary'

Color of the announcement banner (see AnnounceColor).

Returns ​

Promise<void>

A promise resolved once the announcement has been sent.

Default Value ​

'primary'

twitchChat() ​

ts
twitchChat(message): Promise<void>;

Sends a message to the channel's Twitch chat (shortcut to k.chat.say).

Parameters ​

message ​

string

The text to post in chat.

Returns ​

Promise<void>

A promise resolved once the message has been sent.