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.) only forward when users enable Capture Stream Events in popup.html. Donation-style items still pass through even if the toggle is off.

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 Subscriber total updates only* 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 does not expose instant subscriber alerts. Watch for subscriber_update entries (and their deltas) inside events.html to spot milestones.

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.
  • Capture Stream Events must stay enabled for membership, gift, and milestone notices. Super Chats/Super Stickers arrive regardless.
  • Viewer counts require Show viewer count or Hype Mode to be enabled in 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.
  • Non-donation events respect Capture Stream Events; channel statistics respect the per-setting toggles (showsubscount, showviewcount).
  • The API cannot deliver custom badge imagery; badge fallbacks use emoji icons noted below.
  • The Data API does not expose real-time subscriber/follower notifications. Social Stream polls statistics.subscriberCount every 30 minutes and emits a subscriber_update; individual “new subscriber” alerts are unavailable, but the events.html dashboard highlights the count changes so you can still react live.
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 membershipEventType of new sponsor. membership becomes new_sponsor; meta includes originalEventType, durations, and level info.
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.

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. Watch subscriber_update entries inside events.html to keep an eye on count bumps even though instant alerts are unavailable.

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.
  • Non-donation user notice handling (gift subs, channel point rewards) respects Capture Stream Events.
  • Viewer count requests hit https://api.socialstream.ninja/twitch/viewers every 30 seconds.
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 the Kick-style EventSub bridge, plus Helix polling for viewer/follower/subscriber totals. Capture Stream Events must remain on.
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.

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.
  • Capture Stream Events gate social/system cards; gift donations still pass.
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”.

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.

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.
  • Downstream overlays rely on the opt-in behaviour described above; do not bypass the Capture Stream Events toggle unless an event is intrinsically a donation or payment proof.