Overview

VMSC connects to the Twitch EventSub system over WebSocket to receive real-time events from your Twitch channel. When you authorize VMSC with your Twitch account, it automatically subscribes to the event types listed below.

All events are normalized into the VMSC StreamEvent format (see Event Types) with source set to "twitch".

WebSocket Connection Details

VMSC manages the EventSub WebSocket connection automatically. The following details are provided for reference and debugging.

Setting	Value
WebSocket URL	`wss://eventsub.wss.twitch.tv/ws`
Keepalive Timeout	Configurable by Twitch (typically 10 seconds)
Reconnect	Automatic with session migration on `session_reconnect`
Auth	OAuth token with required scopes per subscription type

Session lifecycle

VMSC handles the full EventSub WebSocket lifecycle: initial connection, welcome message processing, subscription creation via the Helix API, keepalive monitoring, and transparent reconnection. You do not need to manage any of this manually.

Event Subscriptions

The table below lists all 24 EventSub subscription types that VMSC registers. The VMSC Event Type column shows the type value used in the VMSC rule engine.

EventSub Subscription	VMSC Event Type	Description
`channel.chat.message`	`chat`	A user sends a message in chat.
`channel.follow`	`follow`	A user follows the channel.
`channel.subscribe`	`subscribe`	A user subscribes to the channel (new sub or resub).
`channel.subscription.gift`	`gift_sub`	A user gifts one or more subscriptions to other viewers.
`channel.cheer`	`cheer`	A user cheers with Bits in the channel.
`channel.raid`	`raid`	Another broadcaster raids the channel.
`channel.channel_points_custom_reward_redemption.add`	`channel_points`	A viewer redeems a custom Channel Points reward.
`channel.poll.begin`	`poll_begin`	A poll starts on the channel.
`channel.poll.progress`	`poll_progress`	Vote counts update during an active poll.
`channel.poll.end`	`poll_end`	A poll ends (completed, archived, or terminated).
`channel.prediction.begin`	`prediction_begin`	A Prediction starts on the channel.
`channel.prediction.progress`	`prediction_progress`	Users place points on a Prediction outcome.
`channel.prediction.lock`	`prediction_lock`	The Prediction window locks (no more points accepted).
`channel.prediction.end`	`prediction_end`	A Prediction resolves with a winning outcome.
`channel.hype_train.begin`	`hype_train_begin`	A Hype Train starts on the channel.
`channel.hype_train.progress`	`hype_train_progress`	The Hype Train advances to the next level.
`channel.hype_train.end`	`hype_train_end`	The Hype Train ends (completed or expired).
`channel.ad_break.begin`	`ad_break`	An ad break starts on the channel.
`channel.shoutout.create`	`shoutout_create`	The broadcaster sends a Shoutout to another channel.
`channel.shoutout.receive`	`shoutout_receive`	The channel receives a Shoutout from another broadcaster.
`channel.ban`	`ban`	A user is banned or timed out in the channel.
`channel.charity_campaign.donate`	`charity_donate`	A viewer donates to the channel's active charity campaign.
`stream.online`	`stream_online`	The channel goes live.
`stream.offline`	`stream_offline`	The channel stops broadcasting.

Per-Event Data Fields

Each event type populates the data object of the VMSC StreamEvent with event-specific fields. Below are the key fields for the most commonly used events.

chat (channel.chat.message)

Field	Type	Description
`message`	`string`	Full text of the chat message.
`emotes`	`object[]`	Array of emote objects with `id`, `begin`, and `end` positions.
`badges`	`object[]`	Array of badge objects (subscriber, moderator, VIP, etc.).
`color`	`string`	User's chat name color as a hex string.

follow (channel.follow)

Field	Type	Description
`followedAt`	`string`	ISO 8601 timestamp of when the follow occurred.

Field	Type	Description
`tier`	`string`	Subscription tier: `"1000"`, `"2000"`, or `"3000"`.
`isGift`	`boolean`	Whether this subscription was gifted.
`cumulativeMonths`	`number`	Total months the user has been subscribed.
`streakMonths`	`number`	Consecutive months subscribed (0 if not sharing).
`message`	`string`	Resub message text (if any).

gift_sub (channel.subscription.gift)

Field	Type	Description
`tier`	`string`	Subscription tier: `"1000"`, `"2000"`, or `"3000"`.
`total`	`number`	Number of gift subs in this event.
`cumulativeTotal`	`number`	Total gift subs the user has given in the channel.
`isAnonymous`	`boolean`	Whether the gifter chose to be anonymous.

cheer (channel.cheer)

Field	Type	Description
`bits`	`number`	Number of Bits cheered.
`message`	`string`	Chat message accompanying the cheer.
`isAnonymous`	`boolean`	Whether the cheerer is anonymous.

raid (channel.raid)

Field	Type	Description
`fromBroadcasterName`	`string`	Display name of the raiding broadcaster.
`viewers`	`number`	Number of viewers in the raid.

channel_points (channel.channel_points_custom_reward_redemption.add)

Field	Type	Description
`rewardId`	`string`	Unique ID of the redeemed reward.
`rewardTitle`	`string`	Title of the redeemed reward.
`rewardCost`	`number`	Channel Points cost of the reward.
`userInput`	`string`	Text input from the viewer (if the reward requires input).

hype_train_begin / hype_train_progress / hype_train_end

Field	Type	Description
`level`	`number`	Current Hype Train level (1–5).
`total`	`number`	Total points contributed to the Hype Train.
`progress`	`number`	Points toward the next level.
`goal`	`number`	Points needed to reach the next level.
`topContributions`	`object[]`	Top contributors with `userId`, `type`, and `total`.

poll_begin / poll_progress / poll_end

Field	Type	Description
`title`	`string`	Poll question text.
`choices`	`object[]`	Array of choices with `id`, `title`, and `votes`.
`status`	`string`	Poll status: `active`, `completed`, `archived`, or `terminated`.

prediction_begin / prediction_progress / prediction_lock / prediction_end

Field	Type	Description
`title`	`string`	Prediction question text.
`outcomes`	`object[]`	Array of outcomes with `id`, `title`, `users`, and `channelPoints`.
`winningOutcomeId`	`string`	ID of the winning outcome (only on `prediction_end`).
`status`	`string`	Prediction status: `active`, `locked`, `resolved`, or `canceled`.

ad_break (channel.ad_break.begin)

Field	Type	Description
`durationSeconds`	`number`	Length of the ad break in seconds.
`isAutomatic`	`boolean`	Whether the ad was triggered automatically by Twitch.

shoutout_create / shoutout_receive

Field	Type	Description
`toBroadcasterName`	`string`	Display name of the broadcaster receiving the shoutout (on `create`).
`fromBroadcasterName`	`string`	Display name of the broadcaster giving the shoutout (on `receive`).
`viewerCount`	`number`	Number of viewers at the time of the shoutout.

ban (channel.ban)

Field	Type	Description
`reason`	`string`	Reason given for the ban (may be empty).
`isPermanent`	`boolean`	`true` for a ban, `false` for a timeout.
`endsAt`	`string`	ISO 8601 timestamp for timeout expiry (null for permanent bans).
`moderatorName`	`string`	Display name of the moderator who issued the ban.

charity_donate (channel.charity_campaign.donate)

Field	Type	Description
`charityName`	`string`	Name of the charity.
`amount`	`number`	Donation amount in the smallest currency unit (e.g., cents).
`currency`	`string`	ISO 4217 currency code (e.g., `"USD"`).

stream_online / stream_offline

Field	Type	Description
`streamType`	`string`	Type of stream: `"live"`, `"playlist"`, or `"watch_party"` (only on `online`).
`startedAt`	`string`	ISO 8601 timestamp of when the stream started (only on `online`).

Per-Event Structured Settings

When creating rules with Twitch event triggers, the rule editor exposes structured settings specific to each event type. These let you filter events without writing manual conditions.

Event Type	Available Filters
`subscribe` / `gift_sub`	Tier filter (Tier 1, 2, 3, or Any). Minimum cumulative months. Gift vs. non-gift toggle.
`cheer`	Minimum Bits amount. Maximum Bits amount. Anonymous filter (include/exclude).
`raid`	Minimum viewer count. Maximum viewer count.
`channel_points`	Specific reward ID or title filter. Minimum cost.
`charity_donate`	Minimum amount. Currency filter.
`hype_train_*`	Minimum level filter.
`ban`	Ban type filter (permanent only, timeout only, or both).