Skip to content
On this page

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 NameUsed for
effect-initialThis has all the information about an effect that was triggred.
effect-updateThis will have updated information about a previous effect.
effect-bidwarThis will have all the information about a bidwar effect.
coin-messageThis will have all the information about a coin exchange.
session-updateThis will have information about session events, such as players connecting, sessions ending and more.
session-statsThis will have information about session stats such as coins exhanged, effects sent and more.
session-clearIs sent when a session has ended or needs to be cleared for another reason.
overlay-url-params-updateThis 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
  }
]
FieldTypeDescription
targetsarrayContains the target(s) of the effect
sourceChannelstringIf in a lobby it will contain the channel of where the effect originally came from.
channelIDstringContains the channel ID for the effect (typically the TwitchID)
channelUserNamestringContains the name of the channel the effect is for.
channelNamestringContains the name of the channel the effect is for. (dupe need to clean up)
idstringThe unique ID of the effect.
timestampintUnix timestamp of when the effect was ordered.
typestringState type of the effect, look at ... for more details.
stateintCurrent state the effect is in. Same as above, but it's int.
gameobjectContains information about the game the effect is for.
effectobjectContains information about the effect, such as name, safeName, duration, cost, image and more.
viewerobjectContains information about the viewer that sent the effect.
pooledbooleanWas the effect pooled by multiple users or not.
bidwarbooleanWas the effect a bidwar effect or not.
freebooleanWas 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.
sessionIDintCurrent sessionID the effect is from.
quantityintNumber 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"
  }
]
FieldTypeDescription
channelIDstringContains the channel ID for the effect.
idstringUnique ID of the effect.
stateintCurrent state of the effect.
typestringState of the effect as human readable.
effectobjectObject containing effect details.
attemptCountintAmount of times the effect was attemped.
startedAtintTime the effect started at.
completedAtintTime the effect completed at.
dequeuedAtintTime the effect dequeued at.
durationintDuration 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"
  }
]
FieldTypeDescription
targetsobjectContains the target(s) of the effect
sourceChannelstringIf in a lobby it will contain the channel of where the effect originally came from.
channelIDstringContains the channel ID for the effect.
channelUserNamestringContains the name of the channel the effect is for.
idstringUnique ID of the effect.
timestampintUnix timestamp of when the effect was ordered.
typestringType of the effect as humand readable.
effectobject
leaderboolIs 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": ""
    }
  }
]
FieldTypeDescription
channelIDstringContains the channelID where the coin transaction happened.
playSFXboolTells the overlay to play the coins SFX or not.
anonymousboolHide the user name of the purchase.
timestampintUnix timestamp of when the transaction happened.
typestringType of coins transactions.bits, channelpoints, charity, moderartor, stripe
amountintAmount of coins granted.
typestringType of the effect as humand readable.
viewerobjectContains information about the viewer that received the coins.

Last updated: