Kappapps SDK

Appearance

Class: TwitchService ​

Service for interacting with the Twitch channel: change the stream title/category, run polls and predictions, create clips, place markers, read other channels' info, and trigger raids.

Remarks ​

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

Example ​

ts
// Change the stream title and create a clip
await k.twitch.setInfos({ title: "Let's start the game!" });
const clip = await k.twitch.clip();
console.log(`Clip created: ${clip.edit_url}`);

Implements ​

Properties ​

ads ​

ts
readonly ads: AdsService;

Twitch ad schedule, actions, and real-time ad break events.

bits ​

ts
readonly bits: BitsService;

Twitch Bits leaderboard, Cheermotes, and custom Power-ups.

charity ​

ts
readonly charity: CharityService;

Active Twitch charity campaign and real-time donations.

goals ​

ts
readonly goals: GoalsService;

Twitch Creator Goals status and real-time events.

hypeTrain ​

ts
readonly hypeTrain: HypeTrainService;

Twitch Hype Train status and real-time events.

infos ​

ts
infos: TwitchInfos;

moderation ​

ts
readonly moderation: TwitchModerationService;

Twitch AutoMod checks and Shield Mode controls.

schedule ​

ts
readonly schedule: ScheduleService;

Read-only access to the broadcaster's Twitch schedule.

sharedChat ​

ts
readonly sharedChat: SharedChatService;

Active Shared Chat session and Kappapps delivery semantics.

videos ​

ts
readonly videos: VideosService;

Twitch VODs, highlights, and uploads.

Methods ​

channel() ​

ts
channel(channel): Promise<TwitchChannelInformations>;

Retrieves the public information of a Twitch channel (title, game, language, tags…) with its current stream, or stream: null when offline.

Parameters ​

channel ​

string

The login (Twitch username) of the channel to query.

Returns ​

Promise<TwitchChannelInformations>

The channel information (TwitchChannelInformations).

Remarks ​

Delegates to channels and returns one object. Uses the same 30-second server cache per Twitch channel, including offline results. Rejects with status 404 if the channel cannot be found. Twitch failures also reject the promise; they are never reported as an offline channel.

Example ​

ts
const info = await k.twitch.channel('twitchdev');
console.log(`${info.broadcaster_name} is playing ${info.game_name}`);
if (info.stream) console.log(`${info.stream.viewer_count} viewers`);

channels() ​

ts
channels(channels): Promise<TwitchChannelInformations[]>;

Retrieves public channel information and current streams for 1 to 100 Twitch logins.

Parameters ​

channels ​

string[]

Twitch logins, without URLs or @ prefixes.

Returns ​

Promise<TwitchChannelInformations[]>

Found channels in input order, with case-insensitive duplicates removed. Unknown logins are omitted. Each object has stream: null when offline, or the complete public Helix stream data while live.

Remarks ​

One SDK request groups the channel and stream lookups server-side. No app scope is required. Channel information and stream data are cached together for 30 seconds per Twitch ID, shared between apps/widgets, both channel methods and team.getChannels(). Offline results (stream: null) are cached too. Only missing or expired entries are fetched, in a batch. Cache hits do not extend the lifetime. Live status, viewers, title and category may therefore lag by up to 30 seconds; returned objects do not update automatically. Invalid input (including an empty list or more than 100 entries) rejects with status 400. Twitch failures reject instead of producing partial/offline data and are not cached.

Example ​

ts
const channels = await k.twitch.channels(['twitchdev', 'another_streamer']);
for (const channel of channels) {
    if (channel.stream) console.log(channel.broadcaster_login, channel.stream.viewer_count);
}

clip() ​

Call Signature ​

ts
clip(has_delay?): Promise<ClipCreateResponse>;

Creates a clip of the current stream.

Parameters ​
has_delay? ​

boolean

Returns ​

Promise<ClipCreateResponse>

By default the creation receipt (ClipCreateResponse): the clip's id and its edit_url. With wait, the published clip (ReadyClip) instead.

Remarks ​

Twitch captures a window of about 90 seconds around the call (~85 s before, ~5 s after). Give a title and a duration to publish the clip exactly as you want it; without them Twitch keeps the last 30 seconds under a title derived from the stream's. The edit_url covers what the API cannot — re-cutting the excerpt, featuring the clip — and stays valid 24 h, or until the clip is published.

Requires the channel to be live, with clipping enabled in the creator's settings — follower-only and subscriber-only restrictions apply. Otherwise the promise rejects with Twitch's own reason. A title refused by AutoMod fails the call too.

Creation is asynchronous on Twitch's side: the call returns a receipt, and the clip only becomes readable a few seconds later. Pass wait to let the SDK poll until it is published and hand you the full clip — it costs a handful of extra API calls, so keep it for the cases where you actually need the url or the thumbnail.

Example ​
ts
// Fire and forget: fast, but the clip is not viewable yet
const receipt = await k.twitch.clip({ title: 'Insane clutch', duration: 20 });
console.log(`Edit the clip here: ${receipt.edit_url}`);

// Wait for a ready-to-use clip
const clip = await k.twitch.clip({ title: 'Best of', wait: true });
k.chat.say(`New clip: ${clip.url}`);
See ​

getClip to read an existing clip.

Call Signature ​

ts
clip(options): Promise<ReadyClip>;

Creates a clip of the current stream.

Parameters ​
options ​

ClipCreateOptions & { wait: true; }

An options object (ClipCreateOptions), or a boolean for the legacy has_delay argument.

Returns ​

Promise<ReadyClip>

By default the creation receipt (ClipCreateResponse): the clip's id and its edit_url. With wait, the published clip (ReadyClip) instead.

Remarks ​

Twitch captures a window of about 90 seconds around the call (~85 s before, ~5 s after). Give a title and a duration to publish the clip exactly as you want it; without them Twitch keeps the last 30 seconds under a title derived from the stream's. The edit_url covers what the API cannot — re-cutting the excerpt, featuring the clip — and stays valid 24 h, or until the clip is published.

Requires the channel to be live, with clipping enabled in the creator's settings — follower-only and subscriber-only restrictions apply. Otherwise the promise rejects with Twitch's own reason. A title refused by AutoMod fails the call too.

Creation is asynchronous on Twitch's side: the call returns a receipt, and the clip only becomes readable a few seconds later. Pass wait to let the SDK poll until it is published and hand you the full clip — it costs a handful of extra API calls, so keep it for the cases where you actually need the url or the thumbnail.

Example ​
ts
// Fire and forget: fast, but the clip is not viewable yet
const receipt = await k.twitch.clip({ title: 'Insane clutch', duration: 20 });
console.log(`Edit the clip here: ${receipt.edit_url}`);

// Wait for a ready-to-use clip
const clip = await k.twitch.clip({ title: 'Best of', wait: true });
k.chat.say(`New clip: ${clip.url}`);
See ​

getClip to read an existing clip.

Call Signature ​

ts
clip(options?): Promise<ClipCreateResponse>;

Creates a clip of the current stream.

Parameters ​
options? ​

ClipCreateOptions

An options object (ClipCreateOptions), or a boolean for the legacy has_delay argument.

Returns ​

Promise<ClipCreateResponse>

By default the creation receipt (ClipCreateResponse): the clip's id and its edit_url. With wait, the published clip (ReadyClip) instead.

Remarks ​

Twitch captures a window of about 90 seconds around the call (~85 s before, ~5 s after). Give a title and a duration to publish the clip exactly as you want it; without them Twitch keeps the last 30 seconds under a title derived from the stream's. The edit_url covers what the API cannot — re-cutting the excerpt, featuring the clip — and stays valid 24 h, or until the clip is published.

Requires the channel to be live, with clipping enabled in the creator's settings — follower-only and subscriber-only restrictions apply. Otherwise the promise rejects with Twitch's own reason. A title refused by AutoMod fails the call too.

Creation is asynchronous on Twitch's side: the call returns a receipt, and the clip only becomes readable a few seconds later. Pass wait to let the SDK poll until it is published and hand you the full clip — it costs a handful of extra API calls, so keep it for the cases where you actually need the url or the thumbnail.

Example ​
ts
// Fire and forget: fast, but the clip is not viewable yet
const receipt = await k.twitch.clip({ title: 'Insane clutch', duration: 20 });
console.log(`Edit the clip here: ${receipt.edit_url}`);

// Wait for a ready-to-use clip
const clip = await k.twitch.clip({ title: 'Best of', wait: true });
k.chat.say(`New clip: ${clip.url}`);
See ​

getClip to read an existing clip.

followerCount() ​

ts
followerCount(): Promise<number>;

Retrieves the total number of followers of the channel.

Returns ​

Promise<number>

The follower count, or 0 if it cannot be read (e.g. the streamer has not re-authorized the channel since this permission was added).

Remarks ​

Fetched on demand (never at boot) and cached ~60 s server-side, so the value can lag reality by up to a minute — don't use it for exact real-time counting; listen to onFollow for that.

Example ​

ts
const followers = await k.twitch.followerCount();
k.chat.say(`We're at ${followers} followers! 💜`);

See ​

subscriberCount, viewerCount

game() ​

ts
game(game, method?): Promise<TwitchGameData>;

Looks up a Twitch game by name, Twitch ID, or IGDB ID.

Parameters ​

game ​

string

The game identifier, interpreted according to method.

method? ​

GameMethod = TwitchService.GAME_METHODS.NAME

How to interpret game: 'name', 'id', or 'igbd_id'.

Returns ​

Promise<TwitchGameData>

The game data (TwitchGameData): id, name, box art, IGDB id.

Default Value ​

'name'

Example ​

ts
const game = await k.twitch.game('Minecraft');
console.log(game.box_art_url);

getClip() ​

ts
getClip(clip_id): Promise<ClipData>;

Retrieves the data of an existing clip from its identifier.

Parameters ​

clip_id ​

string

The clip identifier.

Returns ​

Promise<ClipData>

The full clip data (ClipData), or null if the clip does not exist (yet).

Remarks ​

After clip, Twitch takes a few seconds to make the clip available (assume it failed past 60 s); until then this method resolves null. Rather than writing that polling loop yourself, call clip({ wait: true }).

A clip taken from the ongoing live has no VOD cut yet: expect vod_offset to be null and video_id to be an empty string.

See ​

getClips to list a channel's clips.

getClips() ​

ts
getClips(options): Promise<ClipsPage>;

Retrieves a page of clips, for a channel or for a Twitch category.

Parameters ​

options ​

ClipsListOptions

Source and filters (ClipsListOptions). Exactly one of channel (login) or game_id is required.

Returns ​

Promise<ClipsPage>

A ClipsPage: the clips, plus a cursor for the next page.

Remarks ​

Clips come back by descending view count, not newest first — there is no way to sort by date. To get recent clips, narrow the window with started_at / ended_at.

Beware two Twitch defaults: an started_at without ended_at covers 7 days, not "up to now"; and paging caps out at roughly 1000 clips total, past which you must split into several time windows rather than keep following the cursor.

Results are cached ~10 s server-side, which is shorter than the delay Twitch itself takes to publish a clip.

Example ​

ts
const page = await k.twitch.getClips({ channel: 'twitchdev', first: 20 });
for (const clip of page.clips) console.log(clip.title, clip.url);

if (page.cursor) {
    const next = await k.twitch.getClips({ channel: 'twitchdev', first: 20, after: page.cursor });
}

See ​

getClip for a specific clip.

getMarkers() ​

ts
getMarkers(options?): Promise<StreamMarkersStatus>;

Lists markers from the channel's latest VOD or from a specific video.

Parameters ​

options? ​

StreamMarkersOptions = {}

Returns ​

Promise<StreamMarkersStatus>

marker() ​

ts
marker(description): Promise<void>;

Places a marker on the VOD of the current stream, to easily find a moment again during editing.

Parameters ​

description ​

string

Text describing the marked moment.

Returns ​

Promise<void>

A promise that resolves once the marker is created.

Example ​

ts
await k.twitch.marker('Incredible clutch');

onFollow() ​

ts
onFollow(callback): void;

Registers a callback fired on every new follower of the channel.

Parameters ​

callback ​

OnFollowCallback

Receives a FollowEvent.

Returns ​

void

Example ​

ts
k.twitch.onFollow((event) => {
    k.chat.say(`Thanks for the follow, ${event.user_name}! 💜`);
});

See ​

onSub, onRaid

onRaid() ​

ts
onRaid(callback): void;

Registers a callback fired on every incoming raid (another channel raids yours).

Parameters ​

callback ​

OnRaidCallback

Receives a RaidEvent.

Returns ​

void

Example ​

ts
k.twitch.onRaid((event) => {
    k.chat.say(`Raid from ${event.from_broadcaster_user_name} (+${event.viewers})! 🚀`);
});

onResub() ​

ts
onResub(callback): void;

Registers a callback fired on every re-subscription with a shared message (Twitch channel.subscription.message).

Parameters ​

callback ​

OnResubCallback

Receives a ResubEvent.

Returns ​

void

See ​

onSub for brand-new subscriptions.

Example ​

ts
k.twitch.onResub((event) => {
    k.chat.say(`${event.user_name} resubbed (${event.getCumulativeMonths()} months)!`);
});

onSub() ​

ts
onSub(callback): void;

Registers a callback fired on every new subscription (not gifts, not re-subs with a message).

Parameters ​

callback ​

OnSubCallback

Receives a SubEvent.

Returns ​

void

Remarks ​

To react to every kind of sub, also register onResub and onSubGift.

Example ​

ts
k.twitch.onSub((event) => {
    k.chat.say(`Welcome ${event.user_name} — tier ${event.getTier()} sub! 🎉`);
});

onSubGift() ​

ts
onSubGift(callback): void;

Registers a callback fired on every gift subscription (a viewer gifts one or more subs).

Parameters ​

callback ​

OnSubGiftCallback

Receives a SubGiftEvent.

Returns ​

void

Example ​

ts
k.twitch.onSubGift((event) => {
    const who = event.isAnonymous() ? 'An anonymous viewer' : event.user_name;
    k.chat.say(`${who} gifted ${event.total} sub(s)! 🎁`);
});

poll() ​

ts
poll(poll): Promise<TwitchPoll>;

Creates and starts a Twitch poll on the channel.

Parameters ​

poll ​

TwitchPollCreateData

The poll creation data (TwitchPollCreateData).

Returns ​

Promise<TwitchPoll>

The created TwitchPoll, already active; you can listen for its end or end/archive it via its own methods.

Example ​

ts
const poll = await k.twitch.poll({ ... });
poll.events.on(poll.EVENTS.END, () => console.log('Poll finished'));

See ​

prediction for a prediction.

prediction() ​

ts
prediction(prediction): Promise<TwitchPrediction>;

Creates and starts a Twitch prediction on the channel.

Parameters ​

prediction ​

TwitchPredictionCreateData

The prediction creation data (TwitchPredictionCreateData).

Returns ​

Promise<TwitchPrediction>

The created TwitchPrediction, already active; you can lock it, resolve it, or cancel it via its own methods.

Example ​

ts
const prediction = await k.twitch.prediction({ ... });

See ​

poll for a poll.

raid() ​

ts
raid(channel): Promise<void>;

Starts a raid toward another Twitch channel.

Parameters ​

channel ​

string

The login (Twitch username) of the channel to raid.

Returns ​

Promise<void>

A promise that resolves once the raid is triggered.

See ​

unraid to cancel an in-progress raid.

setInfos() ​

ts
setInfos(infos): Promise<void>;

Updates the stream information: title and/or category (game).

Parameters ​

infos ​

Fields to change.

category? ​

string

New category (game name).

title? ​

string

New stream title.

Returns ​

Promise<void>

A promise that resolves once the update has been forwarded to Twitch.

Example ​

ts
await k.twitch.setInfos({ title: 'Speedrun tonight!', category: 'Just Chatting' });

subscriberCount() ​

ts
subscriberCount(): Promise<SubscriberCount>;

Retrieves the channel's subscriber summary: the current number of subscribers and the total number of sub points.

Returns ​

Promise<SubscriberCount>

A SubscriberCount ({ count, points }). Both are 0 if the data cannot be read (e.g. the streamer has not re-authorized the channel).

Remarks ​

Fetched on demand (never at boot) and cached ~60 s server-side.

Example ​

ts
const subs = await k.twitch.subscriberCount();
k.chat.say(`${subs.count} subs — ${subs.points} points 🎉`);

unraid() ​

ts
unraid(): Promise<void>;

Cancels the raid currently being prepared.

Returns ​

Promise<void>

A promise that resolves once the raid is canceled.

See ​

raid to start a raid.

viewerCount() ​

ts
viewerCount(): Promise<number>;

Retrieves the current viewer count of the stream.

Returns ​

Promise<number>

The number of live viewers, or 0 if the channel is offline.

Remarks ​

Fetched on demand (never at boot) and cached ~30 s server-side.

The other "stream" data is already available without a network call and in real time: the title and category/game live in k.twitch.infos (title, category_name, category_id), and the start time in k.stream.stream_started_at (compute uptime from it). Only the viewer count requires this call.

Example ​

ts
const viewers = await k.twitch.viewerCount();
const title = k.twitch.infos.title;          // real-time, no network call
const game = k.twitch.infos.category_name;   // real-time, no network call