Kappapps SDK

Appearance

Class: AnnounceModel ​

Composite announcement: a single event can be broadcast simultaneously across multiple channels — chat message, colored Twitch announcement, on-screen notification or banner, text-to-speech (TTS), Discord message and service calls. Each channel can have its own text variations, picked at random when played.

Remarks ​

An announcement is built via `AnnounceModel.create` (from an AnnounceCreateData object) then broadcast with `play`. If no channel is enabled, the channel's default tracks (k.channel.preferences.default_announce_tracks) are used. The #tag# tags present in the messages are replaced on the fly (provided variables + channel variables like #channel_name#, #currency_name#…).

Broadcasting happens server-side: play sends one request and the platform fans it out to every enabled track. An announcement read from the app's preferences carries a reference to it, so the server replays the streamer's own configuration — including the Discord webhook, which never reaches the app.

Example ​

ts
// Announce a viewer's arrival in the chat AND via TTS
AnnounceModel.create({
    messages: ['Welcome #user# to the stream!'],
    chatMessage: { enabled: true },
    textToSpeech: { enabled: true },
}).play({ user: 'Sam' });

See ​

AnnounceCreateData for the complete structure of the available channels.

Methods ​

play() ​

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

Broadcasts the announcement across all enabled channels. For each channel, a message is chosen (a random variation, otherwise a base message) then its #tag# tags are replaced before sending.

Parameters ​

tags? ​

Record<string, string> = {}

Replacement variables for the #tag# tags in the messages. Channel variables (#command_symbol#, #currency_symbol#, #currency_name#, #channel_name#) are added automatically.

title? ​

string = null

Title passed to the service calls (the service channel), otherwise ignored.

metadata? ​

Record<string, any> = {}

Free-form metadata passed to the service calls.

Returns ​

Promise<void>

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

Default Value ​

{}

Default Value ​

null

Default Value ​

{}

Remarks ​

If the announcement is disabled (enabled: false), nothing is broadcast. If no channel is enabled, the channel's default tracks (k.channel.preferences.default_announce_tracks) are used. The channels subject to the channel's stream_delay (chat, Twitch announcement, Discord) wait for that delay before sending, and if textTransform is aiEnrich the message is first enriched by the AI.

Because of those two, broadcasting is asynchronous: awaiting play means "the platform took it", not "it is already on screen".

This method never rejects — a refused announcement is reported in the overlay console and your code carries on. Use AnnounceService.play | `k.announces.play` if you would rather handle the failure yourself.

Example ​

ts
await AnnounceModel.create({
    messages: ['#user# just followed the channel!'],
    chatAnnounce: { enabled: true, color: 'green' },
}).play({ user: 'Sam' });

create() ​

ts
static create(data): AnnounceModel;

Creates an announcement from its configuration (enabled channels, messages, variations, color, webhook…).

Parameters ​

data ​

AnnounceCreateData

Announcement configuration — see AnnounceCreateData.

Returns ​

AnnounceModel

A new AnnounceModel instance ready to be played.

Example ​

ts
const announce = AnnounceModel.create({
    messages: ['New game!'],
    screenAnnounce: { enabled: true },
});
await announce.play();

See ​

play to broadcast the announcement.