StreamElements socket.io

What is it?

StreamElements socket.io (also known as realtime) is a socket implementation that allows you to connect to StreamElements to send and receive events in real time.

As the name suggests, it is based on the socket.io protocol. While somewhat outdated on the StreamElements side (in favor of Astro WebSockets), it is still in use and works well.

Unlike Astro (StreamElements WebSockets), realtime allows you to send events to StreamElements. So, if you have a highly customized widget, you can send events to StreamElements and have it respond accordingly.

For example, I have a custom widget that displays the Pokémon in my party from the Pokémon Yellow game (yeah, I like old games). Every time a Pokémon's status changes (like HP), I can send an event to update the widget (check Pikachu's HP in the gif).

Initial information:

The StreamElements socket.io URL is https://realtime.streamelements.com.

You can authenticate using bearer token (JWT), apikey (overlay token), or oAuth2 token. It uses "websocket" transport.

It also appears possible to connect directly via Websockets (not socket.io) to wss://realtime.streamelements.com, but this document only covers the socket.io implementation (although most details apply to both).

Official StreamElements socket.io documentation is on Streamelements Developer Portal

How to connect:

It seems StreamElements still uses an old version of Socket.io, version 2. I was able to connect using newer client version, like 4.5.4, though. However, if you are having connection issues, try using an older client version to see if that works.

You need to use a socket.io library to connect to the StreamElements socket. It is originally a JavaScript library, but you can find other client implementations on the Socket.io website

            <script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>
          

            // This snippet is just an example of how to connect to the StreamElements socket.
            // For more information on handling events, check the next section

            const url = "https://realtime.streamelements.com";
            const options = { transports: ["websocket"]};
            const token = ""; // Your JWT, overlay token (aka apikey) or oAuth2 token
            const method = ""; // "jwt", "apikey" or "oauth2", based on the token used
            const socket = io(url, options); // Start the connection

            // Listen for connection and authentication events
            socket.on("connect", onConnect);
            socket.on("authenticated", onAuthenticated);
            socket.on("disconnect", onDisconnect);
            socket.on("unauthorized", console.error);

            function onConnect() {
              console.log("Connected to StreamElements socket.");
              // After connecting, authenticate:
              socket.emit("authenticate", { method: method, token: token });
            }

            function onAuthenticated(data) {
              const { channelId, clientId, message, project } = data; // available fields in the response
              console.log(`Successfully authenticated to channel ${channelId} with ID ${clientId}`);
              console.log(message);
            }

            function onDisconnect(data) {
              // The client will try to reconnect automatically unless the reason is 
              // "io server disconnect" and "io client disconnect" (manual disconnections)
              // If you want to reconnect even when there is a manual disconnects, use:
              // if (reason === "io server disconnect" || reason === "io client disconnect") {
              //  socket.connect();
              // }
              console.log(`Disconnected from StreamElements. Reason: ${data}`);        
            }
          

Events

Every time a new event occurs, the socket emits a message (except for a chat messages). Some events are listed below:

            "event"                       // Standard events like follower, subscribers, channel points redemptions
            "event:test"                  // Test events and When the "Next Alert" button is clicked (useful for custom events)
            "event:update"                // Same as "event", but updates data
            "event:skip"                  // When alert is skipped
            "session:reset"               // When session data is reset
            "overlay:mute"                // When overlays are muted or unmuted
            "overlay:refresh"             // When overlays are refreshed
            "overlay:update"              // When an overlay is updated
            "overlay:action"              // When the "Reload overlays" is clicked on Activity feed
            "overlay:togglequeue"         // When overlays are paused or resumed
            "kvstore:update"              // When a kvstore data is updated (like overlay paused)
            "session:update"              // When an session update occurs (new bits, new follower, tips, etc)
            "bot:counter"                 // When a counter is updated
            "giveaway:state"              // When a giveaway is created or closed
            "contest:state"               // When a contest is created or closed
            "contest:winner"              // When a contest winner is picked
            "songrequest::mediashare"     // Information on media share
            "songrequest:play"            // When song request starts playing
            "songrequest:pause"           // When song request is paused
            "songrequest:song:next"       // When next song is chosen to be played
            "songrequest:song:previous"   // When previous song is chosen to be played
            "songrequest:queue:remove"    // When song is removed from queue (or declined from pending requests)
            "songrequest:queue:add"       // When song is added to the queue (or approved from pending requests)
            "songrequest:history:add"     // When song is added to the history
            "songrequest:volume"          // When volume is set for song
            "songrequest:settings:update" // When song request settings is changed
          

Receiving events

In order to receive events, add a socket.on function with the event name you want to receive:

If you want, you can listen to all the events listed above, just register each one in its own code block.

            socket.on("event", (data) => {
              console.log("event received:", data);
              // Your logic here
            });

            socket.on("event:test", (data) => {
              console.log("event:test received:", data);
              // Your logic here
            });

            socket.on("overlay:action", (data) => {
              console.log("overlay:action received:", data);
              // Your logic here
            });
          

Alternatively, you can use socket.onAny() function to listen to all events:

            socket.onAny((eventName, ...args) => {
              console.log("New event:", eventName);
              console.log("Data:", args[0]);
              // Your logic here
            });            
          

Rooms

Some rooms are available to subscribe to via the StreamElements socket. Here are the ones I have found so far (replace ACCOUNT_ID with your actual StreamElements account id):

            "songrequest::ACCOUNT_ID"
            "contests::ACCOUNT_ID"
            "giveaways::ACCOUNT_ID"
            "store::ACCOUNT_ID"
            "obs::ACCOUNT_ID"
            "kvstore::ACCOUNT_ID"
            "plarium::ACCOUNT_ID"
            "appsflyer::ACCOUNT_ID"
            "partner-integrations::ACCOUNT_ID"
            "audience-queue::ACCOUNT_ID"
          

Before you ask, I also don't know exactly what the "plarium" and "appsflyer" rooms are used for. Plarium is the company behind the game “Raid - Shadow Legends” (a well-known StreamElements sponsorship) and AppsFlyer is a company that does analytics and campaigns management. The "partner-integrations" room is probably related to sponsorships, but I could not test it.

As for "obs", well... I believe it has something to do with OBS Studio, but I couldn't test it. If you know more about it, please let me know.

Subscribe to a room

To join a room, emit a subscribe event with the room name. In JavaScript, you also need to provide a third parameter: a callback function. So, it should look like this:

            const id = "5a2ed5cc9a474a2c2bc4f0aa"; // your account id
            socket.emit("subscribe" , {"room": `giveaways::${id}`} , (error, data) => console.log(error, data));
          

Alternatively, you can subscribe to multiple rooms at once:

            const id = "5a2ed5cc9a474a2c2bc4f0aa"; // your account id
            const rooms = [ 
              "songrequest", "contests", "giveaways", "kvstore", "store", 
              "obs", "audience-queue", "partner-integrations", "plarium", "appsflyer" 
            ];
            
            rooms.forEach( (room) => {
              socket.emit("subscribe" , {"room": `${room}::${id}`} , (error, data) => {
                if(error){
                  console.error(`Error subscribing to ${room}::${id}:\n ${error.message}`);
                  return;
                }
                console.log(data);
              });
            });            
          

Other info

If you have questions or want to share feedback, feel free to contact me here.

I believe there is much more data to document, but I can't recall what else to add right now. In the meantime, enjoy this randomly generated image below: