> ## Documentation Index
> Fetch the complete documentation index at: https://sparkggdocs.internal.tuniform.tn/llms.txt
> Use this file to discover all available pages before exploring further.
# Event payloads
> Complete JSON schemas for every event type delivered through the Tuniform Stream Alerts WebSocket.
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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
See a complete JavaScript integration example and best practices for production use.