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 events in the dock overlay, add &hideevents to your dock.html URL. Donation-style items always pass through 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.

Quick Feature Availability

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

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
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 — — — Viewer count polls only

*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.
  • If a platform exposes multiple counters together, prefer a structured object with explicit keys (meta.viewer_count, meta.follower_count) instead of overloading strings.

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 …”.
new-membership Structured welcome cards or localized “Welcome to …” text. membership “MEMBERSHIP”; subtitle carries tier/title; nameColor uses membership green when allowed.
upgraded-membership 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.
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.

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, showviewcount).
  • 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.
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 showviewcount or hype mode 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.

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.
sponsorship 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.

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

Implementation: sources/tiktok.js

  • 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.
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.

Kick – Standard DOM Capture

Implementation: sources/kick.js

  • Needs an authenticated session to resolve profile images and subscriber badges.
  • No dedicated event detection; relies on chat text and badges only (viewer counts still work when the toggle is enabled).
Event When it Fires Payload Notes
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.
— Only standard chat messages are forwarded; Kick’s public DOM does not expose membership, follower, or donation alerts.

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.).

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".

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

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

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.

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 (DOM only)
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.

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.
  • Stream events are always captured. To hide events in the dock overlay, add &hideevents to your dock.html URL.
  • For YouTube, Twitch, and Kick, enable WebSocket mode in extension settings for full event support (followers, subscriptions, raids, etc.).