Introduction
The Crowd Control Overlay/Dashboard Socket Server is how the overlay and dashboard get updates about effects, coin exchanges, overlay changes, session data and more. We will explain the process of listening to a channel and understanding the messages.
The server is actually a Socket.IO server but you are still able to use normal websockets if you do not wish to use Socket.IO.
Connecting
Clients are able to establish a connection to Socket.IO with:
wss://overlay-socket.crowdcontrol.live
For those that would rather use websockets you can use:
wss://overlay-socket.crowdcontrol.live/socket.io/?EIO=4&transport=websocket
If using websockets instead of a Socket.IO client you will need to prepend the correct packet ID to your messasges. You can find protocol details here. https://github.com/socketio/socket.io-protocol
Socket.IO will automatically handle the heartbeat and keep the connection alive, but if you are using websockets you will need to send the message of 3
everytime you see a message of 2
from the server to keep the connection alive.
Once connected you are able to send a message to connect to a channel or multiple channels.
Sending ["events", "jaku"]
will subscribe you to all events on the channel for jaku
You can subscribe to multiple channels by sending an array of channel names. ["events", ["jaku", "s4turn", "dtothefourth"]
We also support sending Twitch IDs instead of the channel name ["events", "138803"]
, this method might is prefered if you already have the Twitch ID of the user.
Once you are connected and are connected to a channel you will receive all messages for that user, there are no topics to listen to.
Messages
We have multiple types of messages that are sent over the socket server.
Message Name | Used for |
---|---|
effect-initial | This has all the information about an effect that was triggred. |
effect-update | This will have updated information about a previous effect. |
effect-bidwar | This will have all the information about a bidwar effect. |
coin-message | This will have all the information about a coin exchange. |
session-update | This will have information about session events, such as players connecting, sessions ending and more. |
session-stats | This will have information about session stats such as coins exhanged, effects sent and more. |
session-clear | Is sent when a session has ended or needs to be cleared for another reason. |
overlay-url-params-update | This will have information about the current overlay settings. |
Receiving Messages
effect-initial
Example Message:
[
"effect-initial",
{
"targets": [{ "id": 22, "name": "jaku", "twitchID": "138803", "enabled": true }],
"sourceChannel": false,
"channelID": "138803",
"channelUserName": "jaku",
"channelName": "jaku",
"id": "9d328201-b076-d90c-7edf-12d636e4c033",
"timestamp": 1658706556,
"type": "initial",
"game": { "id": 2, "name": "Super Mario World", "safeName": "SuperMarioWorld" },
"effect": {
"id": "6464",
"name": "1up",
"nameParam": "",
"safeName": "1up",
"image": "IMAGE_URL",
"cost": 10,
"attemptCount": 0,
"durational": false,
"duration": 0,
"parameters": [],
"paramTypes": []
},
"viewer": {
"name": "jaku",
"twitchID": "138803",
"twitchAvatarURL": "IMAGE_URL",
"staff": true,
"elite": true,
"anonymous": false
},
"pooled": false,
"bidwar": false,
"free": true,
"sessionID": 131509,
"quantity": 1,
"state": 3
}
]
Field | Type | Description |
---|---|---|
targets | array | Contains the target(s) of the effect |
sourceChannel | string | If in a lobby it will contain the channel of where the effect originally came from. |
channelID | string | Contains the channel ID for the effect (typically the TwitchID) |
channelUserName | string | Contains the name of the channel the effect is for. |
channelName | string | Contains the name of the channel the effect is for. (dupe need to clean up) |
id | string | The unique ID of the effect. |
timestamp | int | Unix timestamp of when the effect was ordered. |
type | string | State type of the effect, look at ... for more details. |
state | int | Current state the effect is in. Same as above, but it's int. |
game | object | Contains information about the game the effect is for. |
effect | object | Contains information about the effect, such as name, safeName, duration, cost, image and more. |
viewer | object | Contains information about the viewer that sent the effect. |
pooled | boolean | Was the effect pooled by multiple users or not. |
bidwar | boolean | Was the effect a bidwar effect or not. |
free | boolean | Was the effect free. Typically this will be true if the effect was sent by the streamer, retried by the streamer, sent from a lobby or channel point reward. |
sessionID | int | Current sessionID the effect is from. |
quantity | int | Number of "items" that were purchased in the effect. Such as arrows, bombs, etc. |
effect-update
Example Message:
[
"effect-update",
{
"channelID": "138803",
"id": "9d328201-b076-d90c-7edf-12d636e4c033",
"state": 16,
"effect": {},
"completedAt": 1658706557,
"type": "completed"
}
]
Field | Type | Description |
---|---|---|
channelID | string | Contains the channel ID for the effect. |
id | string | Unique ID of the effect. |
state | int | Current state of the effect. |
type | string | State of the effect as human readable. |
effect | object | Object containing effect details. |
attemptCount | int | Amount of times the effect was attemped. |
startedAt | int | Time the effect started at. |
completedAt | int | Time the effect completed at. |
dequeuedAt | int | Time the effect dequeued at. |
duration | int | Duration or time remaining on a timed effect in milliseconds. |
effect-bidwar
Example Message:
[
"effect-bidwar",
{
"targets": [{ "id": 22, "name": "jaku", "twitchID": "138803", "enabled": true }],
"sourceChannel": false,
"channelID": "138803",
"channelUserName": "jaku",
"channelName": "jaku",
"id": 12060,
"timestamp": 1658702928,
"type": "bidwar",
"game": { "id": 26, "name": "Super Mario 64", "safeName": "SuperMario64" },
"effect": {
"id": "138803-12060",
"name": "Big Fish",
"safeName": "sprite_bigfish",
"type": { "id": 0, "name": "General", "safeName": "empty", "type": 0, "meta": null },
"image": "IMAGE_URL",
"cost": 2,
"attemptCount": 0
},
"viewer": {
"name": "The Crowd",
"twitchID": "-1",
"twitchAvatarURL": "",
"elite": false,
"staff": false,
"anonymous": false
},
"pooled": false,
"bidwar": true,
"free": false,
"sessionID": 131472,
"leader": true,
"bidwarParent": "Sprite"
}
]
Field | Type | Description |
---|---|---|
targets | object | Contains the target(s) of the effect |
sourceChannel | string | If in a lobby it will contain the channel of where the effect originally came from. |
channelID | string | Contains the channel ID for the effect. |
channelUserName | string | Contains the name of the channel the effect is for. |
id | string | Unique ID of the effect. |
timestamp | int | Unix timestamp of when the effect was ordered. |
type | string | Type of the effect as humand readable. |
effect | object | |
leader | bool | Is true if the current bidwar is currently highest/winning. |
coin-message
Example Message:
[
"coin-message",
{
"channelID": "138803",
"playSFX": true,
"anonymous": false,
"timestamp": 1661020325,
"type": "bits",
"amount": 120,
"viewer": {
"name": "Test Purchase",
"twitchID": "-3",
"twitchAvatarURL": ""
}
}
]
Field | Type | Description |
---|---|---|
channelID | string | Contains the channelID where the coin transaction happened. |
playSFX | bool | Tells the overlay to play the coins SFX or not. |
anonymous | bool | Hide the user name of the purchase. |
timestamp | int | Unix timestamp of when the transaction happened. |
type | string | Type of coins transactions.bits, channelpoints, charity, moderartor, stripe |
amount | int | Amount of coins granted. |
type | string | Type of the effect as humand readable. |
viewer | object | Contains information about the viewer that received the coins. |