Skip to main content

​
Stream Alerts service

The Stream Alerts service provides real-time event delivery via WebSocket. When a creator receives a donation, subscription, or other event on Tuniform, the event is instantly pushed to all connected WebSocket clients for that creator. This allows:
  • OBS overlays to display live alerts during streams
  • External platforms (e.g., SparkGG) to subscribe to real-time creator activity
  • Custom tools to react to donations, subscriptions, and other events as they happen
There is also a fallback polling mechanism: overlay clients can periodically poll the Tuniform server to fetch events from the database. This ensures alerts are never permanently lost if the WebSocket connection is temporarily unavailable. However, the WebSocket path is the primary real-time delivery channel.

​
Connection endpoint

Connect to the WebSocket using the following URL format: 
wss://stream-alerts.tuniform.tn/ws?token=<stream_token>

​
Authentication

Every creator on Tuniform has a unique stream token — a 64-character hex string that acts as an API key. This token is passed as the token query parameter when connecting.
​
token
string
required
The creator’s unique 64-character hex stream token, passed as a query parameter.

​
Connection responses

ScenarioHTTP StatusResponse
Valid token101 Switching ProtocolsWebSocket connection established
Missing token401 Unauthorized"Missing 'token' query parameter"
Invalid or expired token401 Unauthorized"Invalid or expired token"

​
Handshake message

Immediately after a successful connection, the server sends a handshake confirmation message. This is always the first message received.
Handshake Response
{
  "type": "CONNECTED",
  "kick_username": "creator_kick_handle",
  "user_id": 12345
}
​
type
string
required
Always "CONNECTED" for the handshake message.
​
kick_username
string
The creator’s Kick.com username. Empty string if not set.
​
user_id
integer
required
The creator’s Tuniform user ID.
Always process the handshake message separately from event payloads. The first message after connection is always the CONNECTED handshake — never an event.

​
Message flow

1

Client connects

Open a WebSocket connection to wss://stream-alerts.tuniform.tn/ws?token=<stream_token>.
2

Server authenticates

The server validates the token query parameter. Invalid tokens receive a 401 HTTP response.
3

Handshake received

On success, the server sends a {"type":"CONNECTED",...} message.
4

Events stream in

All subsequent messages are event payloads (donations, subscriptions, etc.) scoped to the authenticated creator.

​
Key behaviors

Server → Client only

This is a one-way broadcast system. The server pushes events to connected clients. Messages sent by the client are ignored.

JSON text frames

Each event is sent as a WebSocket text frame containing a JSON-serialized object.

Creator-scoped

Events are scoped to the creator — you only receive events for the creator whose stream_token you authenticated with.

Automatic keep-alive

The server sends Ping frames automatically. Standard WebSocket clients handle Pong responses transparently — no action needed.

​
Next steps

Event payload schemas

Explore the full JSON schema for donation, subscription, and future event types.