Event payloads

All events share a common JSON structure. The type field identifies what kind of event occurred.

Donation event

Triggered when a user sends a Dannous (tip) to a creator.

Example payload
Field reference

{
  "sender_username": "ahmed_ben",
  "sender_avatar": "https://media.tuniform.tn/upload/photos/d-avatar.jpg",
  "amount": 50.00,
  "currency": "TND",
  "type": "donation",
  "tier": "",
  "duration": "",
  "period": "",
  "streak": 0,
  "receiver_username": "streamer123",
  "receiver_display_name": "Mohamed Ali",
  "receiver_avatar": "https://media.tuniform.tn/upload/photos/avatar.jpg",
  "message": "Great stream! Keep it up!",
  "kick_username": "ahmed_kick",
  "tts_url": "https://media.tuniform.tn/upload/sounds/tts_abc123.mp3",
  "have_tts": true,
  "voice_message": "https://media.tuniform.tn/upload/sounds/2026/04/voice_xyz.webm",
  "have_voice_message": true,
  "timestamp": "2026-04-11T17:00:00+01:00"
}

Field	Type	Description
`type`	`string`	Always `"donation"` for this event type
`sender_username`	`string`	Display name of the person who sent the Dannous
`sender_avatar`	`string`	Absolute URL to the sender’s profile avatar image
`amount`	`float`	Donation amount in platform currency
`currency`	`string`	Currency code (e.g., `"TND"`)
`message`	`string`	Optional text message from the donor (max 250 chars, or 50 if TTS enabled). Empty string if none.
`kick_username`	`string`	Donor’s Kick.com username (used by overlays for external avatar display). Empty string if not set.
`tts_url`	`string`	Absolute URL to the TTS MP3 audio file. Empty string if no TTS.
`have_tts`	`boolean`	`true` if `tts_url` is present and valid
`voice_message`	`string`	Absolute URL to the uploaded voice recording. Empty string if none.
`have_voice_message`	`boolean`	`true` if `voice_message` is present and valid
`receiver_username`	`string`	Creator’s username
`receiver_display_name`	`string`	Creator’s full display name
`receiver_avatar`	`string`	Creator’s avatar URL
`tier`	`string`	Always empty for donations (used only for subscriptions)
`duration`	`string`	Always empty for donations
`period`	`string`	Always empty for donations
`streak`	`integer`	Always `0` for donations
`timestamp`	`string`	ISO 8601 timestamp of when the event was created

Always check have_tts before using tts_url, and have_voice_message before using voice_message. The URL fields may be empty strings even when the boolean flags are false.

Subscription event

Triggered when a user subscribes or resubscribes to a creator’s monetization tier.

Example payload
Subscription-specific fields

{
  "sender_username": "subscriber_name",
  "sender_avatar": "https://media.tuniform.tn/upload/photos/avatar.jpg",
  "amount": 15.00,
  "currency": "TND",
  "type": "subscription",
  "tier": "Gold Tier",
  "duration": 30,
  "period": "monthly",
  "streak": 3,
  "receiver_username": "streamer123",
  "receiver_display_name": "Mohamed Ali",
  "receiver_avatar": "https://media.tuniform.tn/upload/photos/avatar.jpg",
  "message": "",
  "kick_username": "sub_kick_handle",
  "tts_url": "",
  "have_tts": false,
  "voice_message": "",
  "have_voice_message": false,
  "timestamp": "2026-04-11T17:00:00+01:00"
}

These fields are specific to subscription events. All other fields follow the same schema as the donation event.

Field	Type	Description
`type`	`string`	Always `"subscription"` for this event type
`tier`	`string`	Name of the subscription tier (e.g., “Gold”, “Premium”)
`duration`	`integer`	Billing cycle length in days (e.g., `30`)
`period`	`string`	Human-readable period label (e.g., `"monthly"`)
`streak`	`integer`	Consecutive subscription count. Starts at `1`, increments on each renewal, resets if the user lapses for more than 48 hours.

Subscription events typically have empty message, tts_url, and voice_message fields.

Test event

Triggered when a creator uses the Test Lab in their Stream Alerts dashboard.

Test events are structurally identical to donation or subscription events — there is no special type value or flag in the WebSocket payload to distinguish them. They are delivered normally through the WebSocket.

Overlay clients can choose whether to display or filter test events based on their own logic.

Future event types

The platform may add these additional event types in the future:

Type	Description
`follow`	A new user follows the creator
`raid`	Another streamer raids the creator’s stream
`host`	Another streamer hosts the creator’s stream

These will follow the same payload structure with the type field set accordingly. Your integration must handle unknown type values gracefully — log or ignore events with a type you don’t recognize rather than crashing.

Next steps

Integration guide

See a complete JavaScript integration example and best practices for production use.

Getting started

Overview

WebSocket API

Implementation

Donation event

Subscription event

Test event

Future event types

Next steps

Integration guide

Getting started

Overview

WebSocket API

Implementation

​Donation event

​Subscription event

​Test event

​Future event types

​Next steps

Integration guide

Donation event

Subscription event

Test event

Future event types

Next steps