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

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

{
  "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",
  "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
`type_true_source`	For simulated events, the original source type rather than `"Simulated"`. For GoAffPro orders, the GoAffProSource.

TwitchHypeTrain event behaviour

For event_type: TwitchHypeTrain, 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
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.

handleGoalsUpdate¶

Fires when the goals list updates - new goals, changed goals, or point changes.

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

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

{
  "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
    }
  }
}