# Event Reference
This document describes the public `Event` enum and payload shapes.
`Event` is serialized with:
```rust
#[serde(tag = "type", content = "payload")]
```
Example JSON shape:
```json
{
"type": "Chat",
"payload": {
"received_time": "2026-07-12T00:00:00Z",
"comment": "hello"
}
}
```
Most payload structs flatten `EventMeta`, so `received_time` appears at the top level of the payload.
## Shared Types
### `EventMeta`
Fields:
- `received_time: DateTime<Utc>`: time when the SDK created the event.
### `User`
Fields:
- `id: String`
- `label: String`
- `status: UserStatus`
- `subscribe: Option<UserSubscribe>`
### `UserStatus`
Fields:
- `follow: u8`
- `is_bj: bool`
- `is_manager: bool`
- `is_top_fan: bool`
- `is_fan: bool`
- `is_supporter: bool`
### `UserSubscribe`
Fields:
- `acc: u32`: accumulated subscription months/count according to the upstream payload.
- `current: u32`: current subscription months/count according to the upstream payload.
## Lifecycle Events
### `Connected`
Emitted after the WebSocket connection succeeds.
Payload: none.
### `Disconnected`
Emitted when the connection loop ends.
Fields:
- `received_time: DateTime<Utc>`
- `reason: DisconnectReason`
`DisconnectReason` values:
- `Shutdown`
- `WebSocketClosed`
- `ConnectionFailed`
- `ProtocolError`
- `ChannelClosed`
## Chat Events
### `Chat(ChatEvent)`
Emitted for normal chat, manager chat, and emoticon chat.
Fields:
- `received_time: DateTime<Utc>`
- `comment: String`
- `chat_type: ChatType`
- `user: User`
- `is_admin: bool`
- `emoticon: Option<Emoticon>`
`ChatType` values:
- `Common`
- `Manager`
- `Emoticon`
`Emoticon` fields:
- `id: String`
- `number: String`
- `ext: String`
- `version: String`
Notes:
- `is_admin` is currently meaningful for manager chat.
- `emoticon` is populated for emoticon chat.
### `Notification(NotificationEvent)`
Emitted for streamer or manager notices.
Fields:
- `received_time: DateTime<Utc>`
- `message: String`
- `show: bool`
## User Presence and Moderation Events
### `Enter(UserEvent)`
Represents a viewer entering the chat room when the relevant upstream message is parsed as an enter event.
Fields:
- `received_time: DateTime<Utc>`
- flattened `User` fields.
Current note:
- `Enter` exists in the public enum but may not be emitted by the current live dispatch path.
### `Exit(UserEvent)`
Emitted when a viewer exits and the parser determines it is not a kick.
Fields:
- `received_time: DateTime<Utc>`
- flattened `User` fields.
### `Kick(UserEvent)`
Emitted when an exit-like message is parsed as a forced exit.
Fields:
- `received_time: DateTime<Utc>`
- flattened `User` fields.
### `KickCancel(SimplifiedUserEvent)`
Emitted when a forced exit is canceled.
Fields:
- `received_time: DateTime<Utc>`
- `user_id: String`
### `ParticipantList(ParticipantListEvent)`
Emitted once when a participant-list response is complete after `Command::RequestParticipantList`.
The SDK internally normalizes duplicate upstream user ids and aggregates participant/follow-state
chunks before dispatching this final event.
Fields:
- `received_time: DateTime<Utc>`
- `result_code: String`
- `count: usize`: number of unique normalized participants.
- `entries: Vec<User>`
Each entry uses the same `User` payload shape used by chat/user events:
- `id: String`: normalized user id.
- `label: String`
- `status: UserStatus`
- `subscribe: Option<UserSubscribe>`
### `Mute(MuteEvent)`
Emitted when a viewer is muted.
Fields:
- `received_time: DateTime<Utc>`
- `user: User`
- `seconds: u32`
- `message: String`
- `by: String`
- `counts: u32`
- `superuser_type: String`
Current note:
- `message` is currently emitted as an empty string.
### `Black(SimplifiedUserEvent)`
Represents a blacklist-related user event.
Fields:
- `received_time: DateTime<Utc>`
- `user_id: String`
Current note:
- `Black` exists in the public enum but may not be emitted by the current live dispatch path.
### `Freeze(FreezeEvent)`
Emitted when chat freeze settings change.
Fields:
- `received_time: DateTime<Utc>`
- `freezed: bool`
- `limit_subscription_month: u32`
- `limit_balloons: u32`
- `targets: Vec<String>`
Known target strings:
- `BJ`
- `FAN`
- `SUPPORTER`
- `TOP_FAN`
- `FOLLOWER`
- `MANGER`
Note:
- `MANGER` reflects the current emitted string and appears to be a typo preserved from implementation behavior.
### `Slow(SlowEvent)`
Emitted when slow chat mode changes.
Fields:
- `received_time: DateTime<Utc>`
- `duration: u32`
## Donation and Paid Interaction Events
### `Donation(DonationEvent)`
Emitted for balloon, ad balloon, VOD balloon, and video donation message codes.
Fields:
- `received_time: DateTime<Utc>`
- `from: String`
- `from_label: String`
- `amount: u32`
- `fan_club_ordinal: u32`
- `become_top_fan: bool`
- `donation_type: DonationType`
`DonationType` values:
- `Balloon`
- `ADBalloon`
- `VODBalloon`
### `Sticker(StickerEvent)`
Emitted for sticker messages.
Fields:
- `received_time: DateTime<Utc>`
- `from: String`
- `from_label: String`
- `amount: u32`
- `supporter_ordinal: u32`
### `Subscribe(SubscribeEvent)`
Emitted when a user subscribes or renews a subscription.
Fields:
- `received_time: DateTime<Utc>`
- `user_id: String`
- `label: String`
- `tier: u32`
- `renew: u32`
Notes:
- `renew` is `0` for non-renewal subscription events.
### `Gift(GiftEvent)`
Emitted for subscription, OGQ, and QuickView gifts.
Fields:
- `received_time: DateTime<Utc>`
- `gift_type: GiftType`
- `sender_id: String`
- `sender_label: String`
- `receiver_id: String`
- `receiver_label: String`
- `gift_code: String`
`GiftType` values:
- `Subscription`
- `OGQ`
- `QuickView`
## Mission Events
### `MissionDonation(MissionEvent)`
Emitted when a battle or challenge mission receives a gift/donation event.
Fields:
- `received_time: DateTime<Utc>`
- `from: String`
- `from_label: String`
- `amount: u32`
- `mission_type: MissionType`
`MissionType` values:
- `Battle`
- `Challenge`
### `MissionTotal(MissionTotalEvent)`
Emitted when mission total/settlement information is received.
Fields:
- `received_time: DateTime<Utc>`
- `mission_type: MissionType`
- `amount: u32`
### `BattleMissionResult(BattleMissionResultEvent)`
Emitted for battle mission result notices.
Fields:
- `received_time: DateTime<Utc>`
- `is_draw: bool`
- `winner: String`
- `title: String`
### `ChallengeMissionResult(ChallengeMissionResultEvent)`
Emitted for challenge mission result notices.
Fields:
- `received_time: DateTime<Utc>`
- `is_success: bool`
- `title: String`
## State and Diagnostic Events
### `BJStateChange`
Emitted when a BJ state change message is received.
Payload: none.
### `Unknown(MessageCode)`
Emitted when the SDK decodes a raw message but does not have a typed handler for the message code.
Payload:
- `MessageCode`, currently a `u32`.
Use this event to detect new or unsupported SOOP protocol messages.
### `Diagnostic(DiagnosticEvent)`
Emitted for protocol analysis, decoded frame inspection, unknown codes, and parse failures when `SoopChatOptions::diagnostics` is `true`.
Variants:
- `RawFrame`: original frame bytes and byte length.
- `DecodedFrame`: message code, return code, body field count, decoded body fields, and raw bytes.
- `UnknownCode`: decoded unsupported code plus body fields and raw bytes.
- `ParseFailed`: parse failure reason, optional code, body field count, field index, expected type, and raw bytes.
### `Raw(Arc<[u8]>)`
Legacy raw-byte event variant retained in the enum. v0.3 live message handling emits `Diagnostic(RawFrame)` for raw frame analysis when diagnostics is enabled.
Payload:
- raw frame bytes.
Use this event for:
- protocol analysis,
- fixture capture,
- debugging malformed or unknown events,
- validating parser changes.
Serialization note:
- The raw bytes use Serde byte serialization. JSON output depends on the serializer being used.