Models

`AuthOp`

Field	Type	Description
`op`required	object
`token`required	string	A session token, guest token, or API key.

`SubscribeOp`

Subscribe to a topic. Subscribing is idempotent: subscribing again to a topic you already hold succeeds and is acknowledged. The server replies with a subscribed frame on success or an error frame on failure.

Field	Type	Description
`op`required	object
`topic`required	string	The topic to subscribe to. `chat`: one channel's live chat; requires `channel`. `user`: your own direct messages and friend activity. `events`: your own channel's event feed.
`channel`	string	The channel id to subscribe to. Required for `chat` and ignored for other topics.

`UnsubscribeOp`

Remove a subscription. Idempotent: unsubscribing from a topic you do not hold still succeeds. Acknowledged with an unsubscribed frame.

Field	Type	Description
`op`required	object
`topic`required	string
`channel`	string	The channel to leave. Required for `chat`.

`ChatSendOp`

Send a chat message to a channel you are subscribed to. Only signed-in users may send; guests receive an auth_required error. Sending to a channel you have not subscribed to returns not_subscribed. A rejected message (for example from a ban, timeout, rate limit, or empty body) returns send_refused. An accepted message is delivered back to you on the chat topic like any other.

Field	Type	Description
`op`required	object
`channel`required	string
`text`required	string	The message text. Escape it when rendering as HTML.
`reply_parent_msg_id`	string <uuid>	The message being replied to. Optional. Must belong to the same channel, otherwise the send is rejected.

`ControlFrame`

oneOf

`AuthedFrame`

Confirms authentication succeeded. Sent only when you authenticate with an auth frame; header authentication produces no authed frame.

Field	Type	Description
`op`required	object

`SubscribedFrame`

Confirms a subscription is active.

Field	Type	Description
`op`required	object
`topic`required	string
`channel`	string	Present for `chat`; absent for `user` and `events`.

`UnsubscribedFrame`

Confirms a subscription was removed.

Field	Type	Description
`op`required	object
`topic`required	string
`channel`	string

`ErrorFrame`

Reports a problem. code is stable and safe to branch on; message is human-readable and may change.

Field	Type	Description
`op`required	object
`code`required	oneOf	The error identifier. Each value also states whether it closes the connection.
`message`required	string
`topic`	string	The topic the error relates to, when applicable.
`channel`	string

`ChatEnvelope`

A chat-topic frame for one channel.

Field	Type	Description
`topic`required	object
`channel`required	string	The channel this frame belongs to.
`event`required	ServerMessage	A chat event, identified by its `type`.

`ServerMessage`

A chat event, identified by its type.

oneOf

`SM_Message`

A chat message posted in the channel.

Field	Type	Description
`type`required	object
`msg_id`required	string <uuid>
`broadcast_id`	string \| null	The broadcast the message was posted during, or null if the channel was offline.
`user_id`required	string
`username`required	string
`display_name`required	string	The sender's display name as it was when the message was sent.
`text`required	string	The message text. Escape it when rendering as HTML.
`timestamp`required	string <date-time>
`emote_refs`	EmoteRefsV2	Resolved emotes found in the message text. Absent when the message contains no usable emote tokens.
`reply`	ReplyRef	A snapshot of the message being replied to. Absent for non-replies.
`is_owner`	boolean	True if the sender owns the channel. Absent when false.
`is_moderator`	boolean	True if the sender is a moderator of the channel. Absent when false.

`SM_ViewerCount`

The channel's current viewer count, including anonymous guests. Sent once when you subscribe and again whenever it changes.

Field	Type	Description
`type`required	object
`count`required	integer

`SM_NowPlaying`

A listen-along playback update. Sent on every playback change, periodically as a keepalive, and once when you subscribe if a session is already in progress so you can sync to the current position. The playback fields are flattened onto this object rather than nested under a sub-key.

Field	Type	Description
`type`required	object
`video_id`required	string
`position_ms`required	integer	The current playback position within the item
`play_state`required	string	The current playback state, normally `playing` or `paused`. Treat any other value as not actively playing.
`captured_at`required	integer	When this update was captured, in milliseconds since the Unix epoch. To compensate for delivery delay, advance `position_ms` by the time elapsed since `captured_at` before seeking.
`mode`required	oneOf	How playback repeats.
`playlist_id`	string \| null	The playlist being played through, or null for a standalone item.
`playlist_index`	integer \| null	The zero-based position of the current item within the playlist, or null for a standalone item.

`SM_NowPlayingCleared`

The listen-along session ended. Remove any playback display.

Field	Type	Description
`type`required	object
`reason`required	oneOf	Why the session ended.

`SM_StreamStatus`

The channel went live or offline. On receiving this, refetch the channel's stream state and mount or unmount the player accordingly.

Field	Type	Description
`type`required	object
`is_live`required	boolean	True if the channel is now live, false if it is now offline.

`SM_RequestsUpdated`

The channel's viewer-request queue changed. This frame carries no detail; refetch the queue to get the current state.

Field	Type	Description
`type`required	object

`SM_EmoteTableChanged`

An emote available in this channel changed.

Field	Type	Description
`type`required	object
`owner_channel_id`	string	The channel that owns the changed emote. Absent when the change applies to a global emote available everywhere.
`change`required	oneOf	What changed.

`SM_MessageDeleted`

A moderator deleted a message. Replace it in place with a removed-message placeholder rather than removing it, so the message list does not shift.

Field	Type	Description
`type`required	object
`msg_id`required	string <uuid>

`SM_ChatRestricted`

A user was banned or timed out in this channel. The affected user should have their composer disabled; other clients may mark or hide that user's recent messages.

Field	Type	Description
`type`required	object
`user_id`required	string
`kind`required	oneOf	The kind of restriction.
`expires_at`	string <date-time>	When a timeout ends. Absent for bans.

`SM_ChatRestrictionLifted`

A ban or timeout was lifted. The affected user may post again.

Field	Type	Description
`type`required	object
`user_id`required	string

`EmoteRefsV2`

Resolved emotes found in the message text. Absent when the message contains no usable emote tokens.

Field	Type	Description
`v`required	integer	The schema version of these references. Always 2.
`refs`required	object[]

`ReplyRef`

A snapshot of the message being replied to. Absent for non-replies.

Field	Type	Description
`parent_msg_id`required	string <uuid>
`parent_user_id`required	string
`parent_display_name`required	string
`parent_text_snippet`required	string	The start of the parent message text, up to 100 characters.
`thread_root_msg_id`required	string <uuid>	The first message in the reply thread. Equal to `parent_msg_id` when replying directly to a top-level message.

`UserEnvelope`

A user-topic frame carrying a direct message or friend event.

Field	Type	Description
`topic`required	object
`event`required	UserTopicEvent	A direct message or friend event, identified by its `type`.

`UserTopicEvent`

A direct message or friend event, identified by its type.

oneOf

`UTE_DmMessage`

A direct message was sent to you. The full message is included so you can display it without a separate fetch.

Field	Type	Description
`type`required	object
`message`required	DmMessage

`UTE_FriendRequest`

Another user sent you a friend request.

Field	Type	Description
`type`required	object
`from`required	UserSummary

`UTE_FriendAccept`

Another user accepted your friend request.

Field	Type	Description
`type`required	object
`from`required	UserSummary

`DmMessage`

Field	Type	Description
`id`required	string
`conversation_id`required	string
`sender_id`required	string
`body`required	string	The message text
`created_at`required	string <date-time>

`UserSummary`

Field	Type	Description
`user_id`required	string
`username`required	string
`display_name`required	string

`EventsEnvelope`

An events-topic frame carrying one channel event.

Field	Type	Description
`topic`required	object
`event`required	PlatformEvent	One channel event. The same shape is returned by `GET /users/me/events`, so live pushes and the REST feed can be merged and deduplicated on `id`.

`PlatformEvent`

One channel event. The same shape is returned by GET /users/me/events, so live pushes and the REST feed can be merged and deduplicated on id.

Field	Type	Description
`id`required	string	A stable, unique identifier for the event. Use it both to deduplicate across live pushes and the REST feed, and as the pagination cursor for `GET /users/me/events`.
`type`required	oneOf	What happened.
`version`required	integer	The schema version of `data` for this event type, currently 1. A higher number signals a payload shape your client may not recognize.
`channel_user_id`required	string	The channel the event belongs to.
`occurred_at`required	string <date-time>
`data`required	object	A compact, type-specific payload with the identifiers and essentials needed to display the event. Fetch full detail from the REST API when you need more. Properties may be added over time, so ignore any you do not recognize.