Functions & Data

Implement only the functions you need. Each is called automatically when the corresponding WebSocket data is received.

Function	data.type	Description
handleSubathonUpdate(data)	subathon_timer	Timer, points, lock/pause status, multiplier - fires frequently
handleSubathonEvent(data)	event	Fired whenever an event is successfully processed
handlePromptUpdate(data)	prompt_update	Fired whenever a prompt starts, ends, is completed, or progresses
handleGoalsUpdate(data)	goals_list	Goals list changes
handleGoalCompleted(data)	goal_completed	A new goal is completed
handleSubathonDisconnect()	-	Socket disconnected from SubathonManager
handleValueConfig(data)	value_config	Seconds/points config updated
handleTotalsUpdate(data)	subathon_totals	Subathon totals updated

See the Overlay Websocket Data diagram for field-level detail.

---

handleSubathonUpdate

Fires very frequently - use for the timer display, points, lock/pause state, and multiplier values.

Note

When multiplier_points or multiplier_time is 1, no multiplier is active for that field.

Example payload

{
  "type": "subathon_timer",
  "total_seconds": int,
  "days": int,
  "hours": int,
  "minutes": int,
  "seconds": int,
  "total_points": int,
  "is_paused": bool,
  "is_locked": bool,
  "is_reversed": bool,
  "multiplier_points": float,
  "multiplier_time": float,
  "multiplier_start_time": "timestamp | null",
  "multiplier_seconds_total": int,
  "multiplier_seconds_remaining": int,
  "total_seconds_elapsed": int,
  "total_seconds_added": int,
  "currency": "string",
  "rounded_money": double,
  "fractional_money": double
}

---

handleSubathonEvent

Fires whenever an event is successfully processed and has added to the subathon timer.

Example payload

{
  "type": "event",
  "event_type": "string",
  "source": "string",
  "seconds_added": int,
  "points_added": int,
  "user": "string",
  "value": "string",
  "amount": int,
  "currency": "string",
  "command": "string",
  "event_timestamp": "datetime",
  "reversed": bool,
  "sub_type": "string",
  "secondary_value": "string",
  "tertiary_value": "string",
  "type_true_source": "string"
}

Field	Notes
event_type	SubathonEventType - alt view
source	SubathonEventSource - alt view
command	SubathonCommandType - only populated if event_type is a Command
sub_type	SubathonEventSubType - alt view
value	For certain events: $ amount for tips, number of bits, tier of sub, etc.
amount	Number of gift subs for gift events; otherwise usually 1
reversed	true if seconds were removed during a reverse subathon
secondary_value	Mostly used for Order events (commission value + currency) or other rare data
tertiary_value	Mostly used for Order events, will sometimes include an item name if available, but not always
type_true_source	For simulated events, the original source type rather than "Simulated". For GoAffPro orders, the GoAffProSource.

GenericEventTypes event behaviour

For event_type: TwitchHypeTrain or ThroneCrowdGiftComplete, the event is structured differently from other types - it is intended as a status signal, not a points/time event:

• seconds_added and points_added will be 0
• for HypeTrain
  • value will be start, progress, or end (or start ... with multiplier details if one was started)
  • amount will be the current hype train level. progress is only sent when the level increases.
  • user will be your Twitch username
  • Events are sent regardless of the auto-multiplier setting - only the start value is modified when auto-multiplier is enabled.
• for Throne Gift Complete
  • value fields (value, secondary, tertiary) will include information on the price ofthe item, and item name.

---

handlePromptUpdate

Fires whenever a prompt run is started, progressed, completed, expired/cancelled.

Example payload

{
  "type": "prompt_update",
  "status": string,
  "progress": int,
  "target": int,
  "seconds_remaining": double,
  "start_time": datetime,
  "end_time": datetime,
  "duration_seconds": double,
  "text": string,
  "prompt_type": string,
  "prompt_subtype": string, 
  "prompt_eventtype": string,
  "prompt_eventtype_metafilter": string

}

Field	Notes
status	Current prompt status. None, Active, Completed, Expired, Cancelled
progress	Current progress towards the goal
target	Current target for the goal for completion
seconds_remaining	How many seconds left until the prompt expires
start_time	When the prompt goal started to run
end_time	The expected time when the prompt goal expires
duration_seconds	How long the prompt's duration was setup to last
text	The prompt text to display
prompt_type	The type of the prompt. Points, Money, Orders, Follows, Subs, Tokens, Event
prompt_subtype	The subtype for filtering. Default, Items, NormalSubs, GiftSubs, ByTier
prompt_eventtype	SubathonEventType - alt view
prompt_eventtype_metafilter	Filter for specific event types. Such as tier name for subscriptions / memberships.

---

handleGoalsUpdate

Fires when the goals list updates - new goals, changed goals, or point changes. Including when goal list is swapped.

Example payload

{
  "type": "goals_list",
  "points": long,
  "goals_type": "string",
  "goals": [
    {
      "text": "string",
      "points": long,
      "completed": bool
    }
  ]
}

Field	Notes
points	Current subathon points, or rounded (floor) sum of real money donations if goals_type is Money
goals_type	GoalsType - Points or Money

---

handleGoalCompleted

Fires whenever a new goal is completed (and unchanged from the current list).

Example payload

{
  "type": "goal_completed",
  "goal_text": "string",
  "goal_points": long,
  "points": long
}

points is the current subathon points at time of completion, or rounded (floor) sum of real money donations if goals_type is Money.

---

handleSubathonDisconnect

Fires whenever the socket disconnects from SubathonManager.

On reconnection, initial messages for all other handlers are always re-sent, so you can simply wait for new data to arrive.

---

handleValueConfig

Fires whenever the subathon seconds/points configuration is updated - either from the UI or via a remote config patch.

Example payload

{
  "type": "value_config",
  "data": [
    {
      "eventType": "TwitchSub",
      "source": "Twitch",
      "meta": "1000",
      "seconds": 60,
      "points": 1
    }
  ]
}

meta is an empty string for most event types; it is used for sub/membership tier names.

---

handleTotalsUpdate

Fires whenever subathon totals change - from events being processed, money recalculated, etc.

Keys in *_by_type objects are valid SubathonEventTypes.

Example payload

{
  "type": "subathon_totals",
  "currency": "USD",
  "money_sum": 1234.50,
  "sub_like_total": 10,
  "sub_like_by_type": {
    "TwitchSub": 6,
    "YouTubeGiftMembership": 4
  },
  "token_like_total": 400,
  "token_like_by_type": {
    "TwitchCheer": 400
  },
  "order_count_by_type": {
    "OrchidEightOrder": 4,
    "GamerSuppsOrder": 10
  },
  "order_items_count_by_type": {
    "OrchidEightOrder": 5,
    "GamerSuppsOrder": 18
  },
  "follow_count": 130,
  "follow_count_by_type": {
    "TwitchFollow": 130
  },
  "simulated": {
    // same structure as above, for test/simulated events
    "sub_like_total": 10,
    "sub_like_by_type": {
      "TwitchSub": 6,
      "YouTubeGiftMembership": 4
    },
    "token_like_total": 400,
    "token_like_by_type": {
      "TwitchCheer": 400
    },
    "order_count_by_type": {
      "OrchidEightOrder": 4,
      "GamerSuppsOrder": 10
    },
    "order_items_count_by_type": {
      "OrchidEightOrder": 5,
      "GamerSuppsOrder": 18
    },
    "follow_count": 130,
    "follow_count_by_type": {
      "TwitchFollow": 130
    }
  }
}

---