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 only provides basic chat and viewer counts. 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.

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 & 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
Whatnot — — — Viewer count, join alerts, live auction metadata, products, and giveaway snapshots
eBay Live — — — Viewer count, live event card snapshots, auction footer metadata (when exposed), 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
Kick – DOM — — — Viewer count only; use the Kick bridge for alerts
Kick – Websocket/Bridge New subs, renewals, and gifts Follow alerts + follower total Support/tip events (amount + currency) Stream status and profile metadata
Facebook Live — — — Viewer count polls only
Rumble – DOM capture — — — Viewer count polls only
Rumble – Websocket/API URL New subs and gifted subs Follow alerts + follower total Rants/tips (amount + currency) Viewer totals, subscriber totals, live status, and read-only chat feed

*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.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.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, 5 Gifted, 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, channel point redemption details, donation currency).

Meta Conventions

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

  • viewer_update, follower_update, and subscriber_update use a plain integer meta value. The background script aggregates them into viewer_updates with an object keyed by data.type.
  • Donation-style events include a descriptive object: for example { amount, currency, supporter } for Kick, { bits } for Twitch cheers, { supporter, eventType } for YouTube memberships.
  • Raids and hosts pass { fromId, fromLogin, viewers } so overlays can display both streamer name and audience size.
  • Channel point redemptions expose { rewardId, cost, alias } alongside the prepared chat message.
  • 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.
  • Event Flow can request a highlight by setting meta.featured = true on the chat payload, which auto-features the message in dock/featured overlays.
  • 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). hasDonation set to “N Gifted”; donoValue approximates USD (5 × quantity); membership becomes “SPONSORSHIP”.
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”.
jeweldonation Gift-card style promos (eg. YouTube “Jewels”). Parses jewel count into hasDonation (“500 Jewels”) and numeric donoValue for USD estimation.
donation Super Chats, Super Stickers, donation announcement cards. hasDonation carries site-formatted amount; when no message is present the text fallback triggers thankyou.
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/

  • Requires OAuth with scopes youtube.readonly, youtube, youtube.force-ssl, and youtube.channel-memberships.creator. Tokens live in localStorage.
  • 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
donation Super Chat entries from the Data API backlog or stream polling. hasDonation preserves site amount (currency + value); badges/avatars come from API metadata.
supersticker Super Stickers (message text fallback only, no image from API). hasDonation holds the amount; chatmessage contains decoded description text.
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; meta mirrors membership mapping.
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 summarises 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.
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.
new_follower New subscriber detected via myRecentSubscribers API (polled every 5 minutes). chatname is subscriber's channel name; meta includes channelId, title, subscribedAt. 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
  • 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
donation—Super Chat
supersticker—Super Sticker
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.
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, 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, and channel point redemptions.
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 summarises the action.
channel_points channel.channel_points_custom_reward_redemption.add. meta includes reward id, cost, alias; reward object mirrors redemption body.
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.

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 honour data.id.

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
channel_pointsChannel 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

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 bit count.
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 emitted by Streamlabs. Donation fields populated similarly to donation.
sponsor Sponsor/member style alerts surfaced by Streamlabs. Standard fields; no donation unless the text includes an amount.

TikTok Live – Standard DOM Capture

Implementation: sources/tiktok.js (extension content script). SSApp has a native TikTok integration with richer event support (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, joins, and likes are captured automatically.
  • No additional API authentication required.
  • SSApp native mode connects directly via tiktok-live-connector and adds events not available through DOM scraping: subscribe, question_new, envelope, emote, shared, 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 (requires Capture Stream Events and optional join toggle). Skips share notifications; chatname might be empty for some system strings.
followed Follow messages parsed from social cards. Ensures chatname exists before emitting.
liked Like storm summaries triggered by TikTok social cards. Requires identifiable user; otherwise suppressed.
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.

Whatnot

Implementation: sources/whatnot.js

  • Open the live Whatnot show page with chat visible; product/giveaway metadata relies on DOM sections rendered in the show view.
  • Capture Stream Events controls auction/catalog metadata updates; viewer counts still follow the viewer/hype toggles.
Event When it Fires Payload Notes
viewer_update Polled viewer count from the show header. meta is an integer viewer count.
joined Chat rows whose normalized body starts with joined. 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). 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). Metadata-only snapshot with section counts and item arrays under meta.products, meta.surpriseSets, and meta.upcomingGiveaways.

Auction/commerce updates are intended for dedicated overlays and automations; 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.
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.

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 Channel point 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. Scopes: user:read, channel:read, chat:write, events:subscribe. 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.
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 summarises streak.
subscription_gift channel.subscription.gifts. meta.totalGifted, meta.gifter; badges fallback to 💝 icon.
donation Support/tip events detected via event type heuristics. meta contains { amount, currency, supporter, message }; hasDonation is intentionally left blank to avoid double rendering until a common format is agreed.
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.

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 meta.amount with currency fallback to "KICK". Chat payloads include meta.messageId when the bridge exposes a native Kick message ID so delete sync can target the correct message.

Kick Websocket: Event Quick Reference

data.event Scenario
new_followerUser followed channel
new_subscriberNew subscription
resubSubscription renewal
subscription_giftGifted subs
donationTip/support event
follower_updateTotal follower count
stream_onlineStream went live
stream_offlineStream ended

Joystick - Bot WebSocket

Implementation: sources/websocket/joystick.js

  • Uses Joystick bot credentials (client_id + client_secret), not direct user chat credentials.
  • Connects to wss://joystick.tv/cable and subscribes to GatewayChannel.
  • Optional OAuth token exchange is used only for helper endpoints like /api/users/stream-settings.
Event When it Fires Payload Notes
message Joystick ChatMessage / new_message. chatname, chatmessage, chatimg, and author flags are normalized for overlays.
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.
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.

Facebook Live

Implementation: sources/facebook.js

  • Relies on DOM scraping; viewer counts only refresh when Show viewer count or hype mode is enabled.
  • No membership or donation metadata is surfaced via the public chat DOM.
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.

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
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 appear in livestreams[].chat.recent_messages. Standard chat payload. meta.source is live_stream_api; badge labels are normalized into display-friendly badge chips.
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 followers.num_followers changes. meta integer follower count.
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.

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 donation (Super Chat) 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 —
Channel points — channel_points —

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 has Super Chats (donation), Twitch has bits (cheer), and 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. Snapshot file: docs/event-audit.json.

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: subscription_gift, viewer_update. Standard-only: reward, giftpurchase, knock, community_highlight. Websocket-only: new_subscriber, resub, cheer, channel_points, raid, new_follower, follower_update, subscriber_update. Trigger rules should handle both vocabularies; subscription_gift is aligned across both.
Kick: Standard vs Websocket Standard emits lightweight markers (gift, reward, boolean true, viewer_update). Websocket adds full event support: new_follower, new_subscriber, resub, subscription_gift, donation, stream_online/stream_offline, follower_update. Websocket mode is richer; automation built around Standard-only event names should be reviewed when switching.
YouTube: Standard vs Websocket Shared: sponsorship, resub, giftpurchase, giftredemption, donation, viewer_update. Standard-only: jeweldonation, thankyou, redirect. Websocket-only: supersticker, membermilestone, new_follower, subscriber_update, view_update. Core event names are aligned across both.
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
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 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.).