Live Event Reference

This page documents the canonical event payloads that Social Stream Ninja emits for major platforms. Use it as a shared source of truth when wiring new sources, troubleshooting integrations, or aligning UI labels.

Important: Stream events (follows, memberships, milestones, viewer counts, etc.) are always captured and forwarded. To hide all events in dock or featured overlays, add &hideevents (dock also accepts &hideallevents). To hide selected events, use &filterevents=subscription_gift,new_follower,gifted. Donation-style items always pass through the dock filter regardless of settings.
WebSocket Mode Required: For YouTube, Twitch, and Kick, most stream events (followers, subscriptions, raids, etc.) require WebSocket mode to be enabled in the extension settings. DOM capture alone mostly provides chat, viewer counts, and a limited set of heuristically detected system events. Gift and donation event capture (including YouTube gifts), however, is shared across Standard and WebSocket modes; WebSocket adds broader event coverage. See platform sections below for details.
Building Automations? Check out the Event Flow Guide to learn how to use these event payloads in custom triggers, alerts, and workflows. The guide includes a Template Variables Reference for text formatting.
Payload shape: Donation-style chat rows should use hasDonation and optional donoValue. Do not set event: "donation" just because a normal chat/tip row has value; use specific event names only for real platform actions or paid item types, such as superchat, supersticker, gift, or jeweldonation. Use meta only for additional structured data that consumers actually need and that existing fields do not already cover.

Quick Feature Availability

Use this table to see which alert types each capture method currently delivers. Detailed payload notes follow below.

The dedicated Multi-Stream Alert Box groups live events into five shared alert categories: Follow, Subscription/Member, Donation, Bits/Cheers, and Raid/Host. It derives those categories from the existing event, membership, subtitle, hasDonation, and meta fields documented here; no separate payload format is required.

Source New Subs / Members New Followers Donations Counts & Extras
YouTube (Data API bridge) Membership joins, renewals, gifts Individual subscriber alerts* + totals Super Chats & Super Stickers Viewer, subscriber, and view totals (polled)
Twitch – DOM capture Gift bundle lines & gifted-to notices — Bits flagged via hasDonation Viewer count, reward cards, and community highlight cards
Twitch – EventSub/Websocket Instant subs, resubs, and gifts Instant follows + follower total Cheers and channel point redemptions Viewer/sub/follower totals, stream status, ad notices
TikTok Live — Follow cards (when TikTok shows them) Gifts converted to coin totals Viewer count, join alerts, and like storms
YouNow — Fan and audience activity — Viewer count from the live audience panel
Favorited Studio — — — Viewer count from the live viewers tab
Whatnot — — — Viewer count, join alerts, live auction metadata, products, and giveaway snapshots
eBay Live — — — Viewer count, follower count, live event card snapshots, auction footer metadata (when exposed), reaction hearts, and upcoming event metadata
Streamlabs Alert Box Subs, gifts, sponsors, follows Cheer/bits, donations (with currency) Cheer/bits, donations (hasDonation) While an alert box is open; also available via sources/websocket/streamlabs.html socket token
OBS Flow Actions — — — OBS stream started/stopped events for Event Flow when actions.html is connected to OBS WebSocket
Kick – DOM — — — Viewer count plus basic reward/gift system notices; use the Kick bridge for richer alerts
Kick – Websocket/Bridge New subs, renewals, and gifts Follow alerts + follower total Support/tip events (amount + currency) Stream status, reward redemptions, and profile metadata
Facebook Live — — Stars when visible in DOM Chat rows, Stars, and viewer count polls
Rumble – DOM capture — — — Chat rows plus viewer count polls
Rumble – Websocket/API URL New subs and gifted subs Follow alerts + follower total Rants/tips (amount + currency) Viewer totals, subscriber totals, live status, and chat feed
Streamplace — — — Viewer count plus chat names, colors, badges, replies, and links
WorldsWave — — — Rendered live chat plus opt-in viewer count updates
CHZZK — — Visible cheese donation rows Chat rows, badge images, emotes, and viewer count polls
BEAM — — — Chat rows and viewer count polls when the chat-only page exposes a viewer counter
Seal Team Sloth — — — Rendered pop-out chat rows plus viewer_update polls when viewer counts are enabled
FLEX TV — — — Rendered chat rows with names, author colors, badge images, and member metadata

*YouTube subscriber alerts have a 4-hour API delay and only show subscribers with public subscription lists. This is a YouTube API limitation that also affects Streamlabs and other apps.

Field Overview

Field Shape Usage
data.type string Source identifier used by overlays, filters, and Event Flow. Instagram keeps live chat as instagramlive and non-live comments as instagram. See the Source Types Guide for variants, generic sources, and outbound routing.
data.event string | boolean Identifier for system activity (for example viewer_update, subscription_gift, giftpurchase). Regular chat should leave this empty/false so overlays can distinguish system notices from conversational text.
data.chatmessage string Message body. It may contain sanitized/renderable HTML only when data.textonly is false.
data.textonly boolean Applies only to data.chatmessage. true means render chatmessage as plain text; false means chatmessage may contain sanitized/renderable HTML. Other normal fields are expected to be plain text, except media fields such as chatimg and contentimg.
data.membership string Readable membership state such as MEMBERSHIP, new_sponsor, gift_recipient. Surfaces use it for badges, filters, and announcements.
data.subtitle string Supplemental descriptor (membership tenure, tier upgrades, gifted by...). Keep it short and text-only so overlays can slot it under the display name.
data.hasDonation string Monetary or virtual gift amount ($5.00, 500 bits, 300 coins). Populate even when data.event is blank so donation overlays can detect it.
data.meta number | object Structured payload for downstream automations. Use plain integers for single counters (viewer, follower, subscriber) and objects for richer context (raid viewers, reward redemption details, donation currency).
data.firsttime boolean Set to true when First-time chatter detection is enabled, the local database is enabled, and this is the first stored chat message for that user/source. The dock uses it for first-time highlighting and first-time beep filters; the optional first-time badge setting prepends a leaf badge to chatbadges.
data.lastactivity number Unix timestamp in seconds for that user's previous stored chat activity, when First-time chatter detection and the local database are enabled. Omitted for brand-new users.

Meta Conventions

To keep dashboards and automations aligned, follow these conventions when extending data.meta:

  • viewer_update, follower_update, subscriber_update, and likes_update use a plain integer meta value. The background script aggregates viewer counts into viewer_updates with an object keyed by data.type.
  • video_stats uses a structured meta object for external encoder/server health, including provider, label, online, bitrateKbps, rttMs, bufferMs, packet loss/drop counters, and optional codec details.
  • Donation-style events include a descriptive object: for example { amount, currency, supporter } for Kick, { bits } for Twitch cheers, { supporter, eventType } for YouTube memberships.
  • Normalized Stripe, Ko-fi, Buy Me a Coffee, and Fourthwall webhook messages include provider-scoped meta.webhookId, copied from the provider's stable event identifier, so downstream pages can suppress retry and mixed-transport duplicates.
  • Raids and hosts pass { fromId, fromLogin, viewers } so overlays can display both streamer name and audience size.
  • Reward redemptions expose { rewardId, cost, alias } alongside the prepared chat message.
  • user_banned is metadata-only for moderation widgets. It intentionally omits chatname and chatmessage; use meta.username, meta.displayName, meta.avatarUrl, and meta.profileUrl.
  • Chat transports that support source-control delete sync should expose the platform-native chat identifier as meta.messageId instead of relying on the dock's internal data-mid value.
  • SSApp source identity metadata may add meta.ssnAccountRole, meta.ssnSourceId, and meta.ssnSession when a source is assigned a non-normal account role.
  • Event Flow can request a highlight by setting meta.featured = true on the chat payload, which auto-features the message in dock/featured overlays.
  • Event Flow can request dock pinning by setting meta.pinned = true; optional meta.pinnedTarget limits that pin to a dock with the matching label.
  • AI stage overlay commands use { action: "aiOverlay", target, meta } or dock-controlled co-host playout uses { action: "cohostOverlay", target, meta }; keep all command details such as command, text, emotion, avatar, and tts inside meta.
  • If a platform exposes multiple counters together, prefer a structured object with explicit keys (meta.viewer_count, meta.follower_count) instead of overloading strings.
  • Commerce overlays should use snapshot objects under meta (for example auction_update and commerce_update) and avoid ad-hoc top-level fields.

Platform Coverage

YouTube – Standard DOM Capture

Implementation: sources/youtube.js

  • Needs the live chat tab open in a signed-in browser session. Membership and gift cards only render for the channel owner or authorized moderators.
  • Viewer counts require Show viewer count or Hype Mode to be enabled in settings.
  • For follower alerts and additional events, enable WebSocket mode in extension settings.
Event When it Fires Payload Notes
sponsorship Membership welcome header without explicit chat text (new members, gifted bundles landing). membership populated with translated “MEMBERSHIP”; subtitle contains streak/tier when detected.
giftpurchase Gift bundle purchase banner (ytd-sponsorships-live-chat-gift-purchase). membership becomes gift_giver; subtitle carries the gift count when known; no hasDonation or donoValue.
giftredemption Gift redemption announcement for recipients. membership becomes “MEMBERSHIP”; subtitle includes “Gifted by …”.
sponsorship Structured welcome cards or localized “Welcome to …” text. membership “MEMBERSHIP”; subtitle carries tier/title; nameColor uses membership green when allowed.
resub Upgrade banners that include “upgraded to …”. subtitle captures new tier label; membership remains “MEMBERSHIP”.
superchat, supersticker, jeweldonation Super Chats, Super Stickers, donation announcement cards, and YouTube Gifts powered by Jewels (yt-gift-message-view-model). hasDonation carries the value; event identifies the YouTube paid item type. YouTube Gifts use N Jewels when present, or 1 YouTube Gift when YouTube hides the count. Gift images use contentimg, gift labels use subtitle, and minimal gift details are mirrored under meta.youtubeGift.
thankyou Fallback message when a donation amount exists but no chat text was supplied. Keeps hasDonation and auto-injects “Thank you for your donation!” for overlays.
redirect YouTube redirect banner appears in live chat (the closest equivalent to a raid notice). DOM-only capture from yt-live-chat-banner-redirect-renderer. Sets event to redirect and uses membership as the label so overlays render it like other system notices.
viewer_update 30s poll of Social Stream’s viewer endpoint (fallback to page scrape on quota errors). meta is the live viewer integer; contributes to aggregated viewer_updates in the background script.

Membership blocks also set membership for moderator/member chat, while subtitle carries either month counts or tier names. sourceName/sourceImg populate once getChannelInfo succeeds. Standard DOM chat now includes meta.messageId when YouTube exposes a native live-chat message ID, which the dock uses for delete sync.

YouTube – Websocket/Data API Capture

Implementation: sources/websocket/youtube.html, shared helpers under shared/

  • Defaults to OAuth scopes youtube.readonly and youtube.channel-memberships.creator. Optional write access adds youtube.force-ssl for chat sending, moderation, bans, and stream-detail edits; Google may present this as broad YouTube management permission because YouTube does not provide a chat-only write scope.
  • Channel statistics respect the per-setting toggles (showsubscount, showviewercount).
  • The API cannot deliver custom badge imagery; badge fallbacks use emoji icons noted below.
  • New subscriber alerts use the myRecentSubscribers API (polled every 5 minutes). Note: YouTube API has up to 4-hour delay and only shows subscribers with public subscription lists.
  • YouTube redirect banners are not exposed by the Data API, so redirect remains available only from Standard DOM capture.
Event When it Fires Payload Notes
superchat Super Chat entries from the Data API backlog or stream polling. hasDonation preserves site amount (currency + value); event is superchat. Older WebSocket builds used event: "donation" for this row, so consumers may keep accepting that as a legacy alias.
supersticker Super Stickers (message text fallback only, no image from API). hasDonation holds the amount; chatmessage contains decoded description text.
jeweldonation YouTube giftEvent messages when viewers redeem Jewels for Gifts. hasDonation holds N Jewels, or 1 YouTube Gift when YouTube hides the count; contentimg uses the gift asset URL when exposed; subtitle carries the gift label; meta.youtubeGift carries extra gift details.
sponsorship New member joins via newSponsorEvent. membership becomes new_sponsor or new_member; meta includes originalEventType, durations, and level info.
resub Member renewals or tier upgrades. membership becomes renewed_member (renewals) or upgraded_member (upgrades); subtitle shows tier.
giftpurchase Gift bundles purchased via the API. membership set to gift_giver; subtitle lists count/tier; no hasDonation or donoValue.
giftredemption Gift redemption notifications. membership gift_recipient; badges default to 🎁; subtitle indicates gifted tier.
membermilestone Milestone chats (memberMonth or displayMessage present). membership member_milestone; subtitle summarizes months + tier; meta captures the raw milestone mapping.
viewer_update Streaming stats (concurrent viewers) when viewer reporting is enabled. meta is integer count; mirrors DOM scripting so downstream consumers can merge both flows.
likes_update Official video statistics poll when Show YouTube video like count in dashboard is enabled. meta is the current video like-count integer. It emits when the count changes and periodically while unchanged so dashboard state stays fresh.
subscriber_update Channel stats poll (subscribers) when showsubscount not explicitly disabled. meta is total subscriber count; UI updates dashboard counters.
view_update Channel stats poll (lifetime views) when showviewercount or hype mode is active. meta is view count integer.
live_chat_ended Live chat becomes unavailable for the bound broadcast. meta.streamTitle populated when stream metadata was cached.
user_banned userBannedEvent from the live-chat API or gRPC stream. Metadata-only event for moderation widgets. meta includes username/display name, channel ID, avatar/profile URL, moderator, ban/timeout duration, and permanence.
new_follower New subscriber detected via myRecentSubscribers API (polled every 5 minutes). chatname is subscriber's channel name; chatmessage is empty unless subscriber alert messages are enabled in the YouTube source page. meta includes channelId, title, subscribedAt, and grouped bursts add grouped, count, others, and subscribers. Note: YouTube API has up to 4-hour delay; only shows subscribers with public subscription lists.

Chat relays from the API reuse meta.plainText for sanitized content so future adapters can render emote-free summaries. Membership badges fall back to emoji (⭐, 💝, 🏅, etc.) to remain consistent with DOM capture. Regular chat payloads also include meta.messageId so dock-side delete actions can round-trip back to the YouTube moderation API.

YouTube Subscriber Alerts (new_follower)

Social Stream can now detect new YouTube subscribers using the myRecentSubscribers API endpoint. This works similarly to Streamlabs subscriber alerts.

How it works:

  • Polls the YouTube API every 5 minutes for recent subscribers
  • Tracks seen subscribers in localStorage to detect new ones
  • Emits new_follower events with the subscriber's name, avatar, and channel ID
  • Keeps subscriber alert messages disabled by default; enabling them uses the current translation string for alert-just-subscribed
  • Groups bursts larger than three new subscribers by default so reconnects do not flood overlays or Event Flow
  • Requires WebSocket mode to be enabled in extension settings

Limitations (these are YouTube API restrictions, not Social Stream limitations):

  • Up to 4-hour delay – YouTube intentionally delays subscriber data in their API. This affects all apps including Streamlabs.
  • Public subscriptions only – Subscribers who have set their subscription list to private will not trigger alerts. Subscriptions are private by default on YouTube.
  • Channel owner only – You can only receive subscriber alerts for channels you own and are authenticated as.
  • API quota usage – Each poll costs 1 API unit. At 5-minute intervals, this uses approximately 288 units per day (out of the default 10,000 daily quota).

Event Flow Editor trigger: Use data.event === "new_follower" and data.type === "youtube"

YouTube Websocket: Event & Membership Quick Reference

data.event data.membership Scenario
sponsorshipnew_sponsorNew member via newSponsorEvent
sponsorshipnew_memberNew member via processMembership
resubrenewed_memberMembership renewal
resubupgraded_memberTier upgrade
giftpurchasegift_giverGifted memberships to channel
giftredemptiongift_recipientReceived a gifted membership
membermilestonemember_milestoneMembership anniversary chat
superchat—Super Chat
supersticker—Super Sticker
user_banned—Metadata-only ban/timeout event
new_follower—New subscriber (up to 4hr delay)

Twitch – Standard DOM Capture

Implementation: sources/twitch.js

  • Requires Twitch chat open with the user logged in. Membership/user notice elements only render for broadcaster accounts or moderators.
  • Viewer count requests hit https://api.socialstream.ninja/twitch/viewers every 30 seconds.
  • For follower alerts, raids, and full event support, enable WebSocket mode in extension settings.
Event When it Fires Payload Notes
reward Channel point redemption cards (including 7TV reward container). chatmessage contains redemption text; membership unchanged.
giftpurchase System lines such as “User gifting X Subs in the channel”. chatmessage is the system line, enabling overlays to highlight gifter campaigns.
subscription_gift Gifted subscription notices (“User gifted a Sub to …”). Marks the event for highlight filters; membership remains the recipient badge label.
viewer_update 30s fetch to Social Stream viewer proxy (fallback 0 on error). meta integer viewer count.
hype_train Twitch sticky community highlight shows an active Hype Train in popout chat. Metadata-only DOM fallback with meta.sourceMode set to dom. Uses visible level, timer, and meta.progressPercent when Twitch does not expose EventSub point totals.
community_highlight Elements inside Twitch’s “Community Highlight” widget. meta is the extracted highlight text for automation hooks.
knock Stream Together collaboration invites displayed above chat. chatmessage contains the invite text; chatname is derived from the alert user when available.

Bits/Cheers populate hasDonation (for example “500 bits”) even though data.event remains empty; rely on that field when rendering donation widgets. Subscriber streak information appears in subtitle when badges expose months.

Twitch – EventSub/Websocket

Implementation: sources/websocket/twitch.js with shared core providers/twitch/chatClient.js

  • OAuth scopes: chat:read, chat:edit, bits:read, moderator:read:followers, channel:read:subscriptions, channel:read:hype_train, channel:moderate, moderator:manage:banned_users, moderator:manage:chat_messages, channel:read:redemptions, channel:read:ads, channel:manage:ads. Broadcaster tokens unlock subscriber/follower counts.
  • Events delivered by EventSub, plus Helix polling for viewer/follower/subscriber totals.
  • WebSocket mode provides real-time follower alerts, subscription events, raids, cheers, channel point redemptions, and hype train metadata.
  • Shared Chat rows use Twitch IRC source-room-id to populate sourceName/sourceImg with the originating channel when it differs from the connected channel.
Event When it Fires Payload Notes
cheer EventSub channel.cheer notifications. hasDonation “N bits”; meta.bits numeric; chatmessage preserves raw message.
new_subscriber channel.subscribe or USERNOTICE with msg-id=sub. meta includes { userId, tier, isGift }; viewer/subscriber totals increment automatically.
resub channel.subscription.message or USERNOTICE msg-id=resub. meta carries streak and cumulative months; chatmessage includes the resub text.
subscription_gift channel.subscription.gift or USERNOTICE msg-id=subgift. meta exposes gifted total and tier; chatmessage summarizes the action.
reward channel.channel_points_custom_reward_redemption.add. meta includes reward id, cost, and legacy alias; reward object mirrors redemption body. Older consumers may still surface channel_points as a deprecated alias.
raid EventSub channel.raid or USERNOTICE msg-id=raid. meta = { fromId, fromLogin, viewers }.
new_follower channel.follow EventSub notifications. Auto-increments follower_update; meta records { userId, followedAt }.
viewer_update Helix streams poll every 30 seconds. meta integer viewer count; suppressed unless viewer stats enabled in settings.
follower_update Helix follower total, triggered after follow events or periodic poll. meta integer follower count.
subscriber_update Helix subscriber total (requires broadcaster token with subscription scope). meta integer subscriber count.
stream_online / stream_offline EventSub stream.online/stream.offline. meta.startedAt present for online events; offline uses empty object.
ad_break / ad_request / ad_schedule Ad manager API responses (channel.ad_break.begin, manual POST channels/ads, GET channels/ads). meta details duration, requester, and schedule payload for dashboards.
hype_train EventSub channel.hype_train.begin, channel.hype_train.progress, and channel.hype_train.end v2 notifications. Metadata-only event: no chatname or chatmessage. meta.phase is begin, progress, or end; meta includes train id, level, progress, goal, total, contributors, timing fields, shared-train flag, and trainType. Treasure trains are surfaced through meta.trainType when Twitch labels them.
user_banned EventSub channel.ban, or IRC CLEARCHAT fallback when EventSub ban events are unavailable. Metadata-only event for moderation widgets. meta includes username/display name, user ID, avatar/profile URL, moderator, reason, ban/timeout duration, and permanence.

Chat payloads reuse the shared provider, so data.event is populated for `/me` (action) and legacy bits tags even outside EventSub flows. Dedupe logic uses message IDs; ensure downstream consumers honor data.id.

Twitch Hype Train Metadata

hype_train is metadata-only and does not include chatname or chatmessage. Dashboards should update an existing train display by meta.id instead of appending each progress update as chat. The Meta Data Bar (meta.html) renders these events as a top progress bar.

Field Type Notes
typestringAlways twitch.
eventstringAlways hype_train.
meta.phasestringbegin, progress, or end.
meta.idstringStable train id. Use this to upsert/update one visible train widget.
meta.broadcasterUserIdstringTwitch broadcaster user id.
meta.broadcasterUserLoginstringTwitch broadcaster login.
meta.broadcasterUserNamestringTwitch broadcaster display name.
meta.totalnumber | nullTotal support value reported by Twitch for the train.
meta.progressnumber | nullCurrent progress toward the level goal.
meta.goalnumber | nullCurrent level goal.
meta.progressPercentnumber | nullDOM fallback percentage when Twitch only exposes the visible popout progress bar.
meta.levelnumber | nullCurrent or ending train level.
meta.topContributionsarrayTop contributors. Each entry includes userId, userLogin, userName, type, and numeric total.
meta.lastContributionobject | nullMost recent contribution, using the same contribution shape as topContributions.
meta.sharedTrainParticipantsarrayRaw shared-train participant data from Twitch when provided.
meta.startedAtstringISO timestamp for train start.
meta.expiresAtstringISO timestamp for current train expiry.
meta.endedAtstringISO timestamp for train end, or empty before end.
meta.cooldownEndsAtstringISO timestamp for cooldown end, or empty before end.
meta.isSharedTrainbooleanTrue when Twitch marks the train as shared.
meta.trainTypestringUsually regular; treasure trains are surfaced here when Twitch labels them.
meta.allTimeHighLevelnumber | nullAll-time high train level when Twitch provides it.
meta.allTimeHighTotalnumber | nullAll-time high train total when Twitch provides it.
meta.sourceModestringOptional source marker such as dom.
meta.eventSubTypestringOriginal EventSub type: channel.hype_train.begin, channel.hype_train.progress, channel.hype_train.end, or dom.community_highlight.

Twitch EventSub: Event Quick Reference

data.event Scenario
new_followerUser followed channel
new_subscriberNew subscription
resubResubscription with message
subscription_giftGifted subs to channel
cheerBits cheered
rewardChannel point redemption
raidIncoming raid
viewer_updateConcurrent viewer count
follower_updateTotal follower count
subscriber_updateTotal subscriber count
stream_onlineStream went live
stream_offlineStream ended
ad_breakAd break started
hype_trainHype Train/Treasure Train status metadata
user_bannedUser was banned or timed out

OBS Flow Actions

Implementation: actions.html through OBS WebSocket v5 events, with dock.html OBS Browser Source events as a fallback

  • Keep the Flow Actions overlay open with the same Social Stream session as the Event Flow editor/background, or keep the dock loaded inside OBS.
  • Configure OBS WebSocket v5 on OBS 28+; the default URL is ws://127.0.0.1:4455.
  • These are Event Flow system events. They do not include chatname or chatmessage, and extra OBS details stay inside meta.
Event When it Fires Payload Notes
stream_started OBS reports the stream output reached the started state. type is obs; event is stream_started; meta.source is obs-websocket or obs-browser-source; meta.outputState may carry the raw OBS output state.
stream_stopped OBS reports the stream output reached the stopped state. type is obs; event is stream_stopped; meta.outputActive may be false.
recording_started OBS reports recording started. type is obs; meta.obsEvent identifies the OBS event source.
recording_stopped OBS reports recording stopped. type is obs; meta.outputState may carry the raw WebSocket state.
scene_changed OBS changes the active program scene. type is obs; meta.sceneName contains the scene name when OBS provides it.
replay_buffer_saved OBS saves the replay buffer. type is obs; meta.savedReplayPath may contain the saved replay path.

Streamlabs Alert Box

Implementation: sources/streamlabs.js (alert-box DOM); optional socket bridge at sources/websocket/streamlabs.html

  • Keep your Streamlabs alert box open in a tab or browser source so alerts render; the content script reads the alert DOM for message/image/tokens.
  • Donation-style alerts set hasDonation (e.g., “$10 USD” or “100 bits”) and donoValue when numeric.
  • Event types inferred: follow, subscription, gift, cheer, donation, superchat, raid, redeem, merch, sponsor.
  • For the socket bridge, paste your Streamlabs Socket API token and connect; alerts relay without the alert-box page.
Event When it Fires Payload Notes
donation Tips, charity, JustGiving, or generic “donated” alerts. hasDonation preserves the currency text (e.g., “$36” or “$10 CAD”); donoValue numeric when parsable.
cheer Twitch bit/cheer alerts. hasDonation becomes “100 bits” and donoValue captures the USD value.
subscription Subscription alerts. Standard fields set; chatmessage is the alert line; meta.tokens carries tokenized values (name, amount, levelName, etc.).
gift Gifted memberships/subs. meta.tokens.amount may show gift count; meta.tokens.levelName can hold tier.
follow Follower alerts. No donation fields; chatname reflects the alert name token.
raid Raid alerts. meta.tokens.count holds the raider count when present.
redeem Cloudbot redemption alerts. meta.tokens.product captures the redemption item.
merch Merch purchase alerts. meta.tokens.product contains the purchased item name.
superchat Super Chat style alerts from YouTube or supported alert integrations. hasDonation carries the amount; consumers may keep accepting legacy donation aliases.
sponsor Sponsor/member style alerts surfaced by Streamlabs. Standard fields; no donation unless the text includes an amount.

TikTok Live – DOM Capture and TikFinity Feed

Implementation: sources/tiktok.js for native TikTok pages and sources/tikfinity.js for TikFinity's activity-feed widget/iframe. SSApp still has a native TikTok integration with the widest event coverage (see SSApp docs).

  • Works on the broadcaster's live page. Gift/like/follow banners only populate when the session is authenticated.
  • TikTok provides many events via DOM detection without requiring WebSocket mode – gifts, follows, likes, and opt-in joins are captured from rendered rows.
  • TikFinity widget pages at tikfinity.zerody.one/widget/activity-feed* also work. The embedded activity-feed iframe emits the same canonical TikTok payload fields for chat, follows, shares, gifts, subscriptions, opt-in joins, and treasure chests.
  • No additional API authentication required.
  • SSApp native mode still adds events beyond the page/widget capture paths: question_new, emote, and viewer_update.
Event When it Fires Payload Notes
gift Gift banner rows or DivGiftMessage entries. hasDonation converts to “N coins” (with gift lookup fallback); membership uses badge text when available.
joined Join notifications when the global Capture "joined" stream events setting is enabled. Skips share notifications; chatname might be empty for some system strings.
followed Follow messages parsed from social cards. Ensures chatname exists before emitting.
shared TikFinity share rows. chatmessage is the rendered share text.
subscribe TikFinity subscription rows. membership is set to SUBSCRIBER.
envelope TikFinity treasure chest rows. meta.coins and meta.canOpen carry the chest details.
liked Like storm summaries triggered by TikTok social cards. chatname is included when TikTok exposes it; anonymous/system like cards may still emit. The main chat/events feed setting does not block the dedicated reactions overlay.
true (boolean) Generic social/system broadcasts where TikTok provides no subtype. Use chatmessage content to decide presentation; boolean true indicates “system event – type unknown”.

membership mirrors badge tooltips (subscriber tiers). Avatar caching keeps chatimg valid between events; if the DOM suppresses color for moderators the script clears nameColor. TikFinity gift rows also set contentimg to the gift icon when available.

Whatnot

Implementation: sources/whatnot.js

  • Open the live Whatnot show page with chat visible; websocket transport now assists chat, raids, donations, and fast viewer updates, while product/giveaway snapshots still rely on DOM sections rendered in the show view.
  • Capture Stream Events controls Whatnot system events plus auction/catalog metadata updates; joined rows also require Capture "joined" stream events; viewer counts still follow the viewer/hype toggles.
Event When it Fires Payload Notes
viewer_update Viewer count changes from websocket livestream updates, with DOM polling as a fallback. meta is an integer viewer count.
donation Whatnot websocket tips and community boost contribution events. hasDonation contains the formatted amount; websocket-specific context stays under meta.
raid Whatnot websocket raid events, including backlog activity replies. meta.numRaiders is included when Whatnot supplies it.
joined Chat rows whose normalized body starts with joined, when Capture "joined" stream events is enabled. Uses string event labels for join notices (not boolean true).
auction_update When the live footer auction state changes (winner/winning text, title, bids, price, timer, sold state), often accelerated by websocket auction lifecycle packets. Metadata-only event. No chatname/chatmessage; data lives in meta (for example meta.title, meta.bids, meta.price, meta.timer, meta.status).
commerce_update When catalog sections change (products, surprise sets, upcoming giveaways), often accelerated by websocket giveaway/product lifecycle packets. Metadata-only snapshot with section counts and item arrays under meta.products, meta.surpriseSets, and meta.upcomingGiveaways.

Auction/commerce updates are still DOM-backed snapshots; websocket packets mainly provide faster triggers and cleaner event metadata. Keep downstream rendering keyed off data.event + data.meta.

eBay Live

Implementation: sources/ebay.js

  • Open an eBay Live event stream page (/ebaylive/events/<id>/stream) with event cards visible.
  • Some auction controls (winner/timer/bid buttons) are only exposed in certain layouts or authenticated states; parser falls back to live preview cards when full auction footer DOM is unavailable.
  • Capture Stream Events controls metadata snapshots (auction_update, commerce_update); viewer counters still honor viewer/hype toggles.
Event When it Fires Payload Notes
viewer_update When the active event viewer count changes (header count or live event pill fallback). meta is an integer viewer count.
follower_update When the seller follower count is returned from the seller stats endpoint. meta is an integer follower count. The source polls the seller endpoint every 60 seconds; the endpoint may still return a cached value for up to 5 minutes.
auction_update When active auction metadata changes. Metadata-only event. If player-card controls are present, includes bid/price/timer/winner/action fields. Fallback mode includes current live event fields such as meta.title, meta.viewerCount, meta.sellerName, meta.tags, and meta.scheduleText.
commerce_update When catalog/live-event snapshot sections change. Metadata-only snapshot under meta, including available sections such as meta.navigation, meta.playerCards, meta.liveEvents, meta.livePreview, meta.currentEvent, and meta.upcomingEvents.
reaction When eBay Live renders a heart/reaction animation. Sent directly to the dedicated reactions target. meta.reactionType is heart; eBay does not expose a per-user name for these DOM animations.

eBay metadata events intentionally omit chatname/chatmessage; downstream overlays should render from data.event + data.meta only.

Kick – Standard DOM Capture

Implementation: sources/kick.js

  • Needs an authenticated session to resolve profile images and subscriber badges.
  • Limited event detection via chat text matching and badges; viewer counts still work when the toggle is enabled.
Event When it Fires Payload Notes
gift Gift sub events detected via chat text matching. chatmessage contains the system line; basic gift detection only.
reward Reward redemptions ("has redeemed …"). chatmessage contains redemption text.
true (boolean) Generic system notices that don’t match gift or reward patterns. Use chatmessage content to decide presentation; boolean true indicates "system event – type unknown".
viewer_update Polls Kick’s channel API every 30 seconds (only when viewer stats are enabled). meta integer viewer count; for subs, follows, or tips use the Kick bridge below.

Kick – Websocket/Bridge

Implementation: sources/websocket/kick.js with shared helpers under providers/kick/core.js

  • OAuth via the Social Stream Kick bridge. Core scopes include user:read, channel:read, chat:write, events:subscribe, channel:rewards:read, moderation:ban, and kicks:read. Tokens are refreshed automatically.
  • Kick webhook provisioning may take several minutes; the UI lists active subscriptions per channel.
Event When it Fires Payload Notes
message Bridge chat payload. meta.plainText contains emoji-free content; badges merge platform + profile cache. Thread replies populate initial, reply, and meta.reply when reply details or a cached parent message are available.
reward channel.reward.redemption.updated, plus bridge chat/system payloads that look like redemptions. meta includes reward/redemption id, title, cost, status, user input, and redeemer.
new_subscriber channel.subscription.new. membership assigned to subscriber role; meta includes { subscriber, plan }.
resub channel.subscription.renewal. meta.duration (months) and meta.plan available; subtitle summarizes streak.
subscription_gift channel.subscription.gifts. meta.totalGifted, meta.gifter; badges fallback to 💝 icon.
donation kicks.gifted and support/tip events detected via event type heuristics. hasDonation carries the formatted amount; meta contains { amount, currency, supporter, message, giftName }.
raid Kick legacy socket host events such as App\Events\StreamHostEvent. Mapped to the canonical raid event. meta includes { fromId, fromLogin, viewers } when Kick supplies them.
new_follower channel.followed. Follower icons derive from profile cache; follower_update fires when Kick provides running totals.
follower_update Bridge supplies follower counts in webhook payloads. meta integer total; used by dashboards for follower goals.
stream_online / stream_offline livestream.status.updated. meta contains the raw status body from Kick (is_live, title, etc.).
viewer_update livestream.status.updated when Kick includes concurrent viewer totals. meta integer viewer count; emits 0 on offline status to clear stale counters.
user_banned moderation.banned from the bridge/webhook, or Kick chat socket ban events. Metadata-only event for moderation widgets. meta includes username/display name, user ID, avatar/profile URL, moderator, reason, ban/timeout duration, and permanence.

Profile lookups leverage profileCache; mapBadges merges Kick's badge assets with cached SVG when available. When Kick reports donations in KICKs, the bridge converts them into hasDonation plus meta.amount with currency fallback to "KICKs". Chat payloads include meta.messageId when the bridge exposes a native Kick message ID so delete sync can target the correct message. Reply payloads include meta.reply with the parent messageId, author, and text when known.

Kick Websocket: Event Quick Reference

data.event Scenario
new_followerUser followed channel
new_subscriberNew subscription
resubSubscription renewal
subscription_giftGifted subs
rewardChannel reward redemption or reward-style chat/system message
donationTip/support/KICKs gift event
raidIncoming Kick host/raid
follower_updateTotal follower count
stream_onlineStream went live
stream_offlineStream ended
user_bannedUser was banned or timed out

VPZone - WebSocket

Implementation: sources/websocket/vpzone.js

  • Connects to the VPZone chat websocket with ?channel=USERNAME; OAuth requests profile:read, chat:read, and chat:write for chat sending. A bearer token with chat:write can also be supplied.
  • Flat VPZone frames such as type: "msg" are normalized into standard chat payloads.
Event When it Fires Payload Notes
message VPZone msg, message, new_message, or chat_message websocket frame. chatname comes from username; chatmessage comes from body; subscriber/owner/mod/VIP flags are copied into chatbadges, top-level role flags, and meta. Native IDs populate data.id and meta.messageId.
viewer_update VPZone presence frame with count or equivalent viewer field. meta is the live viewer integer; contributes to aggregated viewer_updates.
new_subscriber VPZone subscribe / subscription frame. membership is set to Subscriber when subscription flags are present.
subscription_gift VPZone gift / gift_subscription frame. Uses the same gifted-sub event name as Twitch, Kick, Rumble, and Velora.
new_follower VPZone follow frame. Mapped into the standard follower event shape.
joined VPZone join/presence-style websocket events, when Capture "joined" stream events is enabled. Mapped into a chat-style system event with VPZone actor metadata under meta.

Joystick - Bot WebSocket

Implementation: sources/websocket/joystick.js

  • Uses Joystick bot credentials (client_id + client_secret), not direct user chat credentials.
  • Authorizes on https://joystick.tv/api/oauth/authorize, then exchanges/refreshes tokens at https://api.joystick.tv/api/oauth/token.
  • Connects to wss://api.joystick.tv/cable and subscribes to GatewayChannel.
  • Optional OAuth token exchange is used for helper endpoints like https://api.joystick.tv/api/users/stream-settings.
  • Current Joystick bot docs expose stream settings, follower count, live state, and streamer photo, but not a live viewer count; this source does not emit viewer_update.
Event When it Fires Payload Notes
message Joystick ChatMessage / new_message. chatname, chatmessage, chatimg, role badges, userid, and optional sourceName/sourceImg are normalized for overlays; Joystick-specific IDs and role booleans stay in meta.
new_follower Joystick StreamEvent with type Followed. Mapped into standard follower event shape with extra details in meta.
donation Joystick StreamEvent types Tipped / TipMenu. hasDonation is populated when token amount can be inferred from metadata/text; meta.amount, meta.currency, meta.supporter, and tip menu details carry structured data.
stream_online / stream_offline Joystick StreamEvent types like Started, StreamResuming, Ended, StreamEnding. Used for transport-aware online/offline automations.
user_enter / user_leave Joystick UserPresence types enter_stream / leave_stream. Presence notifications are emitted as event messages and can be suppressed by hide-events settings. Hide-events also suppresses non-donation stream events.

Facebook Live

Implementation: sources/facebook.js (DOM scraping) and optional Graph API bridge at sources/websocket/facebook.html

  • Relies on DOM scraping; viewer counts only refresh when Show viewer count or hype mode is enabled.
  • Stars are captured from the rendered Live Chat DOM when Facebook shows the visible N sent marker; they populate hasDonation and donoValue at 100 Stars = $1 USD without setting data.event.
  • For testing, add ssnreplay=1 to the Facebook Live URL to process chat rows already visible after refresh.
Event When it Fires Payload Notes
viewer_update Polls the live viewer badge (every ~8s when enabled). meta integer viewer count; sends 0 when parsing fails to clear stale entries.
hasDonation Facebook Stars rendered in the Live Chat DOM. Standard chat payload; hasDonation carries the visible Stars amount, such as 100 Stars, and donoValue carries the USD value. Stars do not set data.event.
highlightColor Facebook renders a visible HIGHLIGHTED label. Uses the normal chat fields and highlightColor; no data.event is set. Stars still use hasDonation.

Online Church

Implementation: sources/onlinechurch.js

  • Relies on DOM scraping of the public chat and media header.
  • Viewer counts only refresh when Show viewer count or hype mode is enabled.
Event When it Fires Payload Notes
message New entries appear under #publicchat. Standard chat payload with sender name, avatar, badges, and optional membership label when present in the DOM.
viewer_update Polls the live occupancy badge in the media header every 10s. meta integer viewer count; sends 0 when the badge is missing or unreadable to clear stale counters.

SharePlay.tv

Implementation: sources/shareplay.js

  • Relies on DOM scraping of the live chat drawer on SharePlay channel pages.
  • Only newly inserted chat rows and cards are emitted after the scraper attaches; the existing backlog is intentionally ignored.
Event When it Fires Payload Notes
message New chat rows appear inside the main chat feed. Standard chat payload with author, avatar, badge images, and HTML-preserved emotes. Thread replies also populate initial, reply, and meta.reply when the parent row is still present.
raid SharePlay inserts a Blitz card into the live chat feed. Mapped to the canonical raid event. meta.cardType is "blitz", with optional meta.fromLogin and meta.viewers when the card text exposes them.
shoutout SharePlay inserts a shoutout/follow card into the chat feed. Emitted as data.event = "shoutout". The card banner image is forwarded via contentimg, while meta.cardType and meta.action preserve the card label/button text.
viewer_update Polls the visible header viewer badge every 10s. meta integer viewer count; only emitted when Show viewer count or hype mode is enabled, and sends 0 if the badge becomes unreadable to clear stale counters.

Streamplace

Implementation: sources/streamplace.js

  • Reads Streamplace's React-rendered live page and skips the visible chat backlog when attaching.
  • Relay-style messages such as Name (Discord): message are normalized to the relayed sender name.
Event When it Fires Payload Notes
message New Streamplace chat rows appear after attach. Standard chat payload with nameColor, chatbadges, HTML-preserved links, and reply fields initial, reply, and meta.reply when visible.
viewer_update The header viewer badge changes while viewer-count capture or hype mode is enabled. meta integer viewer count.

WorldsWave

Implementation: sources/worldswave.js

  • Supports WorldsWave live pages and chat-only URLs such as https://worldswave.com/kn_livecmd.php?cmd=viewStream&streamId=STREAM_ID&chatonly=1.
  • Existing chat history is skipped when capture attaches; test with a new message.
  • Viewer counts require Show viewer count or hype mode. Gifts, tips, and send-back are not normalized by this source yet.
Event When it Fires Payload Notes
message A new rendered WorldsWave chat row appears. Standard chat payload with type: "worldswave", sender name, avatar, optional user ID and name color, plus sanitized inline message images when text-only mode is disabled.
viewer_update The visible live viewer total changes while viewer-count capture or hype mode is enabled. meta is the integer viewer count; compact values such as 1.2K are normalized.

FLEX TV

Implementation: sources/flextv.js

  • Reads the rendered chat panel on https://www.flextv.co.kr/channels/*/live pages.
  • The chat panel must be visible. Existing chat history is skipped when the source attaches, so test with a new chat row.
  • No viewer count, donation, or send-back path is documented for this source yet.
Event When it Fires Payload Notes
message New visible FLEX TV .chat-item rows appear in the live chat feed. Standard chat payload with type: "flextv", chatname, chatmessage, nameColor, badge images in chatbadges, and FLEX member details under meta when exposed by data-member.

Seal Team Sloth

Implementation: sources/sealteamsloth.js

  • Reads the rendered pop-out chat on https://sealteamsloth.com/popout-chat/* pages.
  • Viewer counts require Show viewer count or hype mode.
Event When it Fires Payload Notes
message A new rendered Seal Team Sloth chat row appears. Standard chat payload with type: "sealteamsloth", sender name, avatar, and message content.
viewer_update The visible live viewer total changes while viewer-count capture or hype mode is enabled. meta is the integer viewer count; compact values such as 1.2K are normalized.

MeetMe - DOM and WebSocket Capture

Implementation: sources/meetme.js

  • Reads MeetMe's rendered live chat DOM on app.meetme.com/live/view/... pages and inside the api.gateway.meetme-live.com/web-live/... iframe.
  • When the iframe websocket is available, wss://video-live.meetme.com/ frames are parsed before the DOM fallback to capture richer live events.
  • hideevents suppresses non-donation events; MeetMe gifts and diamond donations still populate donation fields. capturejoinedevent enables join/rejoin notices, and capturelikeevent controls whether likes appear in the main feed or only the reactions target.
  • Viewer counts prefer the visible MeetMe header count, falling back to websocket totals only when the DOM count is unavailable. Counts emit on change and repeat the latest count about every 30 seconds while showviewercount/hypemode is enabled; follower totals are changed-only and rate-limited to roughly 60 seconds.
Event When it Fires Payload Notes
message New SNSChatMessage websocket frames arrive, or new ChatMessage_* DOM rows appear under ChatHistoryContainer_*. Standard chat payload with sender name, avatar, message HTML/text, and badge images/text. DOM row details are flat meta keys, including messageId, roomId, level, levelColor, badgeLabels, badgeSrcs, badgeClasses, isBouncer, isTopStreamer, isBestOfTheWeek, rank, and rowClassName. Websocket payloads set meta.source = "websocket".
joined / rejoined / left SNSChatParticipant websocket create, update, or delete frames arrive, or MeetMe renders a DOM join-cell row. Joined/rejoined notices require Capture "joined" stream events. Emits chat-style system notices with actor name/avatar when MeetMe exposes them. meta.isNewViewer, meta.viewerLevelId, meta.isBouncer, and meta.isSubscriber preserve participant state.
new_follower MeetMe renders a DOM favorite/follow row such as Favorited. Uses the shared follower event vocabulary. chatname is the actor, chatimg is the detected profile photo when available, and flat meta.favoriteText/meta.targetName preserve the original row details.
gift SNSGiftMessage websocket frames arrive, or MeetMe renders a gift image in a chat row. hasDonation carries the visible gift label or diamond value, contentimg carries the gift image when exposed, and flat keys such as meta.giftName, meta.giftCount, meta.amount, and meta.currency preserve structured details. The gift event is reserved for actual gift frames/rows; donation rendering should still key off hasDonation.
donation SNSDiamond websocket frames expose diamond activity. Dedicated diamond frames are treated as donation events. hasDonation is formatted as diamonds, donoValue is numeric when available, and meta.amount/meta.currency stay flat for automations.
liked / reaction SNSLike websocket frames arrive. Actor-specific likes use the same liked vocabulary as TikTok. Aggregate/anonymous like totals are sent only to the reactions target as reaction, with flat meta.reactionType, meta.totalLikes, and meta.subscriberLikes.
follower_update SNSVideo websocket metadata exposes follower totals. meta is the follower integer, matching the shared counter-event convention.
guest_update SNSVideoGuestBroadcast create/update frames arrive. Metadata-only event for guest/live cohost state. Flat meta keys include status, position, totalGuests, isMuted, guestBroadcastId, videoViewerId, and broadcastId.
viewer_update The visible header viewer badge changes, or SNSVideo websocket metadata exposes viewer totals when the badge is unavailable; unchanged totals repeat about every 30 seconds while enabled. meta integer viewer count; only emitted when viewer-count capture or hype mode is enabled.

Velora

Implementation: sources/velora.js and sources/websocket/velora.js

  • Standard mode reads the visible chat DOM; WebSocket mode uses the Velora Events API with OAuth.
  • Supported Standard mode URLs include https://velora.tv/*, https://velora.tv/dashboard/stream/popout?panels=chat%2Cactivity&channel=CHANNEL&layout=vertical, and https://velora.tv/dashboard/stream/popout/CHANNEL/obs-chat.
  • Volts and channel point style cards are emitted as event payloads when exposed by the DOM or Events API.
Event When it Fires Payload Notes
message New Velora chat rows appear or Events API chat messages arrive. Standard chat payload with badges, author color, links, and emotes preserved when not in text-only mode.
volts Velora Volts cards or channel.volts Events API payloads arrive. hasDonation carries the displayed Volts amount; DOM captures include meta.source = "dom".
channel_points Velora channel point/redemption cards or channel.channel_points_redemption Events API payloads arrive. chatmessage carries the redemption message or reward title; meta.rewardTitle identifies the reward when available.
subscription Visible Velora activity row says a user became a channel member/subscriber. membership carries the visible membership label.
viewer_update Visible viewer count changes while viewer-count capture or hype mode is enabled. meta integer viewer count.

Parti - Profile / Popout Chat Capture

Implementation: sources/parti.js

  • Supports profile URLs like https://parti.com/USERNAME and popout URLs like https://parti.com/popout-chat?id=USER_ID.
  • Viewer counts use Parti's livestream heartbeat endpoint when viewer-count capture or hype mode is enabled.
Event When it Fires Payload Notes
message Visible Parti chat rows appear in the profile or popout chat stream. Standard chat payload; nameColor preserves Parti's rendered author color and chatmessage preserves inline content unless text-only mode is enabled.
donation Visible Parti tip rows say a user tipped an amount. hasDonation carries the displayed amount, meta.amount/meta.currency are populated when parsable, meta.amountText preserves the raw amount text, and donoValue is set for USD tips.
viewer_update The Parti heartbeat returns a live viewer count. meta is the integer viewer count; the page reuses one heartbeat token per source window to avoid inflating counts.

CHZZK - Popout Chat Capture

Implementation: sources/chzzk.js

  • Supports https://chzzk.naver.com/live/*/chat and https://chzzk.naver.com/iframe/live/*/chat.
  • Viewer counts use CHZZK's live-status polling endpoint when viewer-count capture or hype mode is enabled.
Event When it Fires Payload Notes
message Visible CHZZK chat rows appear in the popout chat stream. Standard chat payload with type: "chzzk", nameColor, badge image URLs in chatbadges, and rendered emotes in chatmessage unless text-only mode is enabled.
donation Visible CHZZK cheese donation rows appear in chat. hasDonation carries the displayed cheese amount. These rows do not set data.event.
viewer_update The live-status poll returns a viewer count. meta is the integer viewer count.

Rumble - Standard DOM Capture

Implementation: sources/rumble.js

  • Requires authenticated session cookies so the service.php viewer API responds.
  • No membership or donation details are exposed via public endpoints.
Event When it Fires Payload Notes
message Visible Rumble chat rows appear in the page or popup chat. Standard chat payload; chatmessage preserves Rumble emote image HTML after the page renders it unless text-only mode is enabled.
viewer_update Calls Rumble’s video.watching-now service every 30s. meta integer viewer count; uses credentials: 'include' to reuse session cookies.

Rumble - Websocket/API URL

Implementation: sources/websocket/rumble.js

  • Requires the creator-owned Live Stream API URL from https://rumble.com/account/livestream-api. Rumble documents that this URL includes the live stream key, does not require separate authentication, and should only be shared with trusted third parties.
  • Read-only transport. The public Rumble Live Stream API docs do not describe an official chat-send endpoint, so this source relays messages/events into Social Stream but does not send chat back to Rumble.
  • livestreams[].chat only populates while the selected stream is live. Use ?streamId=... to pin a specific stream when the API exposes more than one; invalid IDs now fail instead of silently falling back to another stream.
  • The page also resolves https://rumble.com/chat/popup/<livestreams[].id> so you can open the normal injected popup chat directly without first loading the broadcaster's /live page.
Event When it Fires Payload Notes
message New entries arrive from Rumble's SSE chat stream after the official API resolves livestreams[].id; falls back to livestreams[].chat.recent_messages. Standard chat payload. meta.source is rumble_sse when the SSE chat stream is available and includes avatar URLs from users[].image.1; otherwise it falls back to live_stream_api without avatars. When the popup emote catalog is available, chatmessage renders Rumble shortcode emotes as image HTML and meta.plainText preserves the original shortcode text.
donation New rant entries appear in livestreams[].chat.recent_rants. hasDonation carries the USD-formatted amount; meta includes amount_cents, amount_dollars, and expiresOn.
new_follower New entries appear in followers.recent_followers. System event with chatname set to the follower username and timestamp under meta.followedOn.
new_subscriber New entries appear in subscribers.recent_subscribers. membership is set to SUBSCRIBER; subtitle mirrors the documented USD amount when Rumble provides it.
subscription_gift New entries appear in gifted_subs.recent_gifted_subs. chatname is the gifter, hasDonation becomes N Gifted, and meta includes totalGifted, remainingGifts, giftType, and videoId.
follower_update Whenever the selected follower counter changes. meta integer follower count. Defaults to followers.num_followers; with ?followerMode=total, uses followers.num_followers_total when Rumble provides it.
subscriber_update Whenever subscribers.num_subscribers changes. meta integer subscriber count.
stream_online / stream_offline When the selected livestream switches between live and offline states. meta includes a sanitized subset of stream fields (id, title, createdOn, category labels, likes/dislikes, and viewer totals). Sensitive values such as stream_key are intentionally not forwarded.
viewer_update Whenever livestreams[].watching_now changes for the selected stream. meta integer concurrent viewer count; emits 0 when the selected stream goes offline to clear stale counters.

This transport is intended for channels you own or manage. Because the API URL contains a live stream key, do not expose it in overlays, logs, screenshots, or shared browser profiles. Chat avatars come from Rumble's SSE chat stream once the official API resolves the stream ID; this transport does not scrape Rumble pages for avatars.

Cross-Platform Event Alignment

Use this table to understand how similar concepts map across platforms. Where possible, new sources should align to the common event names in the first column.

Concept YouTube WS Twitch WS Kick WS
New member/sub sponsorship new_subscriber new_subscriber
Renewal/resub resub resub resub
Gift subs giftpurchase subscription_gift subscription_gift
Received gift giftredemption — —
Milestone membermilestone — —
Donation/tip superchat, supersticker, jeweldonation with hasDonation cheer (bits) donation
New follower new_follower (4hr delay)* new_follower new_follower
Viewer count viewer_update viewer_update viewer_update
Follower count — follower_update follower_update
Sub count subscriber_update subscriber_update —
Stream status live_chat_ended stream_online/stream_offline stream_online/stream_offline
Raid — raid —
Reward redemption — reward reward

Alignment Notes

  • YouTube uses sponsorship for new members, while Twitch and Kick use new_subscriber. Consider checking both when building cross-platform triggers.
  • resub is consistent across all three platforms for renewals.
  • Gift events differ: YouTube uses giftpurchase/giftredemption, while Twitch and Kick use subscription_gift.
  • Donations vary by platform: YouTube uses specific paid event names such as superchat, supersticker, and jeweldonation with hasDonation; Twitch has bits (cheer); Kick has tips (donation).
  • new_follower is now consistent across all three platforms, but YouTube has a 4-hour API delay and only shows subscribers with public subscription lists.

Repository Audit Snapshot (All Sources)

Static scan scope: sources/*.js and sources/websocket/*.js. The optional audit snapshot file (docs/event-audit.json) is not currently checked in; regenerate it locally when needed.

Metric Result Why It Matters
Files scanned 150 Coverage includes all root capture scripts plus all websocket capture scripts.
Files writing hasDonation 132 Most sources expose donation/cheer/tip value even when no explicit event marker is set.
Donation field but no event marker 89 Expected baseline: many adapters intentionally set hasDonation without setting data.event.
Files with delete forwarding 5 Delete parity is not universal; moderation overlays should not assume all platforms emit delete payloads.

Tracked Mismatches and Voids

Pair/Area Observed Mismatch / Void Impact
Twitch: Standard vs Websocket Shared: reward, subscription_gift, viewer_update. Standard-only: giftpurchase, knock, community_highlight. Websocket-only: new_subscriber, resub, cheer, raid, new_follower, follower_update, subscriber_update. channel_points is now a deprecated legacy alias for Twitch reward redemptions; new integrations should key off reward.
Kick: Standard vs Websocket Standard emits lightweight markers (gift, reward, boolean true, viewer_update). Websocket adds full event support: reward, new_follower, new_subscriber, resub, subscription_gift, donation, raid, stream_online/stream_offline, follower_update, including API reward redemptions and KICKs gifts. Websocket mode is richer; automation built around Standard-only event names should be reviewed when switching.
YouTube: Standard vs Websocket Shared: superchat, supersticker, jeweldonation, sponsorship, resub, giftpurchase, giftredemption, viewer_update. Standard-only: thankyou, redirect. Websocket-only: membermilestone, new_follower, subscriber_update, view_update, likes_update (opt-in). Core member/event names are aligned across both; Super Chat, Super Sticker, and Jewels use hasDonation, while membership gift purchases/redemptions do not.
All surfaces Many sources populate hasDonation without setting data.event. This is correct; donation rendering should key off hasDonation, with data.event reserved for system/event semantics.

Deprecated Event Names

The following event names were replaced during the event-naming unification. Sources no longer emit them, but downstream pages (dock, featured, events, leaderboard, multi-alerts) still accept them for backward compatibility with older extension versions. Do not use these in new code.

Deprecated Name Canonical Replacement Context
subscriptionnew_subscriberTwitch/Kick new sub
subgiftsubscription_giftTwitch gifted sub
membershipsponsorshipYouTube new member (generic)
new_membersponsorshipYouTube new member
new_membershipsponsorshipYouTube new member
newmembersponsorshipYouTube new member
new-membershipsponsorshipYouTube DOM scraper (hyphenated variant)
upgraded_membershipresubYouTube tier upgrade
upgraded-membershipresubYouTube DOM scraper (hyphenated variant)
membership_upgraderesubYouTube tier upgrade
membership_milestonemembermilestoneYouTube milestone chat
member_milestonemembermilestoneYouTube milestone chat (underscore variant)
gift_membershipgiftpurchaseYouTube gift bundle
membership_giftgiftpurchaseYouTube gift bundle
giftmembershipsgiftpurchaseYouTube gift bundle (plural variant)
gifted_membershipgiftredemptionYouTube gift received
gifted_membershipsgiftpurchaseYouTube gift bundle (plural variant)
community_giftgiftpurchaseCommunity gift bundle
channel_pointsrewardTwitch websocket reward redemption (legacy alias)
followednew_followerTikTok follow event

Using This Reference

  • When adding a new event, reuse existing vocabulary (subscription_gift, viewer_update, etc.) whenever possible. If a deviation is unavoidable, document it here along with the rationale.
  • Keep data.meta predictable: prefer flat keys, never overload strings with mixed data, and always include units (currency, bits, duration).
  • Update AGENTS.md and this page in the same pull request so future contributors know which surface produces the event.
  • When source behavior changes, regenerate/update docs/event-audit.json if your branch uses that optional audit artifact so mismatches and voids stay trackable.
  • Stream events are always captured. To hide all events in dock or featured overlays, add &hideevents (dock also accepts &hideallevents). To hide selected events, use &filterevents=subscription_gift,new_follower,gifted.
  • For YouTube, Twitch, and Kick, enable WebSocket mode in extension settings for full event support (followers, subscriptions, raids, etc.). Gift/donation capture for YouTube (including gifts and super chats) is available in both Standard and WebSocket modes; websocket adds additional event types.

Back to top