Events

Widget receives few types of native events during lifetime. They are:

• onWidgetLoad - Triggers when the widget is loaded or refreshed.

• onEventReceived - Triggers on every event like a chat message, new tip, new follower, subscriber, etc.

• onSessionUpdate - Similar to onEventReceived, but it handles session events, like latest subscriber, goals, etc. Does not include chat messages.

Example:

window.addEventListener('onWidgetLoad', function (obj) {
  console.log(obj); // You can check obj value in the browser console.
});

On Widget Load

Event received upon widget is loaded. Contains information about fieldData (fields values), channel information (including apiKey) and session data.

window.addEventListener('onWidgetLoad', function (obj) {
  //fancy stuff here
});

In this scope obj has every information you could need to use. For better readibility, Let’s assign it:

window.addEventListener('onWidgetLoad', function (obj) {
  let data = obj["detail"]["session"]["data"];
  let recents = obj["detail"]["recents"];
  let currency = obj["detail"]["currency"];
  let channelName = obj["detail"]["channel"]["username"];
  let apiToken = obj["detail"]["channel"]["apiToken"];
  let fieldData = obj["detail"]["fieldData"];
});

Possible keys within data:

Common

• data["merch-goal-items"]["amount"] - Merch items goal progress
• data["merch-goal-orders"]["amount"] - Merch orders goal progress
• data["merch-goal-total"]["amount"] - Merch total goal progress
• data["tip-latest"] - An array containing latest Tip event
  • data["tip-latest"]["name"] - Latest tipper username
  • data["tip-latest"]["amount"] - Latest tip amount
  • data["tip-latest"]["message"] - Latest tip message
• data["tip-session-top-donation"] - Aan array of top tip since session start
  • data["tip-session-top-donation"]["name"] - Username
  • data["tip-session-top-donation"]["amount"] - Tip amount
• data["tip-weekly-top-donation"] - An array of top tip in past week
  • data["tip-weekly-top-donation"]["name"] - Username
  • data["tip-weekly-top-donation"]["amount"] - Tip amount
• data["tip-monthly-top-donation"] - An array of top tip in past month
  • data["tip-monthly-top-donation"]["name"] - Tip amount
  • data["tip-monthly-top-donation"]["amount"] - Username
• data["tip-alltime-top-donation"] - An array of top tip all time
  • data["tip-alltime-top-donation"]["name"] - Username
  • data["tip-alltime-top-donation"]["amount"] - Tip amount
• data["tip-session-top-donator"] - An array of top tipper since session start
  • data["tip-session-top-donator"]["name"] - Username
  • data["tip-session-top-donator"]["amount"] - Sum of the tip amounts
• data["tip-weekly-top-donator"] - An array of top tip in past week
  • data["tip-weekly-top-donator"]["name"] - Username
  • data["tip-weekly-top-donator"]["amount"] - Sum of the tip amounts
• data["tip-monthly-top-donator"] - An array of top tip in past month
  • data["tip-monthly-top-donator"]["name"] - Tipper username
  • data["tip-monthly-top-donator"]["amount"] - Sum of the tip amounts
• data["tip-alltime-top-donator"] - An array of top tip all time
  • data["tip-alltime-top-donator"]["name"] - Tipper username
  • data["tip-alltime-top-donator"]["amount"] - Sum of the tip amounts
• data["tip-session"]["amount"] - Sum of all donations since session start
• data["tip-week"]["amount"] - Sum of all donations this week
• data["tip-month"]["amount"] - Sum of all donations this month
• data["tip-total"]["amount"] - Sum of all donations this all time
• data["tip-count"]["count"] - Number of tip events
• data["tip-goal"]["amount"] - Donation goal

Twitch

• data["follower-latest"]["name"] - Name of latest follower
• data["follower-session"]["count"] - Followers since session start
• data["follower-week"]["count"] - Followers this week
• data["follower-month"]["count"] - Followers this month
• data["follower-goal"]["amount"] - Followers goal
• data["follower-total"]["count"] - Total count of followers
• data["subscriber-alltime-gifter"] an array of
  • data["subscriber-alltime-gifter"]["name"] - Name of latest gifter
  • data["subscriber-alltime-gifter"]["amount"] - Number of gifted subs
• data["subscriber-gifted-latest"] an array of
  • data["subscriber-gifted-latest"]["name"] - Name of latest gifter
  • data["subscriber-gifted-latest"]["amount"] - Number of gifted subs
• data["subscriber-gifted-session"]["count"] - Number of gifted subs during session
• data["subscriber-latest"] - an array of
  • data["subscriber-latest"]["name"] - Name of latest sub
  • data["subscriber-latest"]["amount"] - Duration in months
  • data["subscriber-latest"]["tier"] - Tier of sub (1-3)
  • data["subscriber-latest"]["message"] - Message attached to sub action
  • data["subscriber-latest"]["sender"] - If it was a gift, here’s a gifter
  • data["subscriber-latest"]["gifted"] - If it was a gift, here’s a gifted
• data["subscriber-new-latest"] an array of
  • data["subscriber-new-latest"]["name"] - Name of latest new sub
  • data["subscriber-new-latest"]["amount"] - Number of months (1)
  • data["subscriber-new-latest"]["message"] - user message
• data["subscriber-new-session"]["count"] - Number of new subs during session
• data["subscriber-resub-latest"] an array of
  • data["subscriber-resub-latest"]["name"] - Name of latest resub
  • data["subscriber-resub-latest"]["amount"] - Number of months
  • data["subscriber-resub-latest"]["message"] - user message
• data["subscriber-resub-session"]["count"] - Number of resubs during session
• data["subscriber-session"]["count"] - Subscribers since session start
• data["subscriber-week"]["count"] - Subscribers this week
• data["subscriber-month"]["count"] - Subscribers this month
• data["subscriber-goal"]["amount"] - Subscribers goal
• data["subscriber-total"]["count"] - Total count of subscribers
• data["subscriber-points"]["amount"] - Subscriber points (used for unlocking additional channel emotes - more info on Twitch Partner Emoticon Guide)
• data["host-latest"]["name"] - Latest host
• data["host-latest"]["amount"] - Number of viewers in latest host (can be 0)
• data["raid-latest"]["name"] - Name of latest raider
• data["raid-latest"]["amount"] - Number of viewers in latest raid
• data["cheer-session"]["amount"] - Cheers since session start
• data["cheer-month"]["amount"] - Cheers this month
• data["cheer-total"]["amount"] - Total amount of cheers
• data["cheer-count"]["count"] - Number of cheer events
• data["cheer-goal"]["amount"] - Cheer goal
• data["cheer-latest"] - An array containing latest Cheer event
  • data["cheer-latest"]["name"] - Latest cheerer
  • data["cheer-latest"]["amount"] - Latest cheer amount
  • data["cheer-latest"]["message"] - Latest cheer message
• data["cheer-session-top-donation"] - Aan array of top cheerer since session start
  • data["cheer-session-top-donation"]["name"] - Username
  • data["cheer-session-top-donation"]["amount"] - Cheer amount
• data["cheer-weekly-top-donation"] - An array of top cheer in past week
  • data["cheer-weekly-top-donation"]["name"] - Username
  • data["cheer-weekly-top-donation"]["amount"] - Cheer amount
• data["cheer-monthly-top-donation"] - An array of top cheer in past month
  • data["cheer-monthly-top-donation"]["name"] - Username
  • data["cheer-monthly-top-donation"]["amount"] - Cheer amount
• data["cheer-alltime-top-donation"] - An array of top cheer all time
  • data["cheer-alltime-top-donation"]["name"] - Username
  • data["cheer-alltime-top-donation"]["amount"] - Cheer amount
• data["cheer-session-top-donator"] - An array of top cheerer since session start
  • data["cheer-session-top-donator"]["name"] - Username
  • data["cheer-session-top-donator"]["amount"] - Sum of the cheer amounts
• data["cheer-weekly-top-donator"] - An array of top cheerer in past week
  • data["cheer-weekly-top-donator"]["name"] - Username
  • data["cheer-weekly-top-donator"]["amount"] - Sum of the cheer amounts
• data["cheer-monthly-top-donator"] - An array of top cheerer in past month
  • data["cheer-monthly-top-donator"]["name"] - Username
  • data["cheer-monthly-top-donator"]["amount"] - Sum of the cheer amounts
• data["cheer-alltime-top-donator"] - An array of top cheer all time
  • data["cheer-alltime-top-donator"]["name"] - Username
  • data["cheer-alltime-top-donator"]["amount"] - Sum of the cheer amounts

YouTube

OBS: Youtube member is used to be called sponsor, that's the reason the key is called "sponsor"

• data["sponsor-goal"]["amount"] - Amount of members goal
• data["sponsor-session"]["count"] - Members since session start
• data["sponsor-week"]["count"] - Members this week
• data["sponsor-month"]["count"] - Members this month
• data["sponsor-total"]["count"] - Total count of members
• data["sponsor-latest"] - An array containing latest member event
  • data["sponsor-latest"]["name"] - Username
  • data["sponsor-latest"]["amount"] - amount
• data["sponsor-recent"] - An array of latest member events with each element structure as in sponsor-latest
• data["sponsor-gifted-latest"]- An Array of a gifted members
  • data["sponsor-gifted-latest"]["name"]- Username getting the gift
  • data["sponsor-gifted-latest"]["amount"] - Amount of member gifts
  • data["sponsor-gifted-latest"]["tier"] - Tier of member gifts
  • data["sponsor-gifted-latest"]["message"] - Message from gifter
  • data["sponsor-gifted-latest"]["sender"] - username giving the gift
• data["subscriber-latest"]["name"] - Name of latest subscriber
• data["subscriber-session"]["count"] - Subscribers since session start
• data["subscriber-week"]["count"] - Subscribers this week
• data["subscriber-month"]["count"] - Subscribers this month
• data["subscriber-goal"]["amount"] - Subscribers goal
• data["subscriber-total"]["count"] - Total count of subscribers
• data["superchat-goal"]["amount"] - Amount of superchat goal
• data["superchat-session"]["count"] - Superchats since session start
• data["superchat-week"]["count"] - Superchats this week
• data["superchat-month"]["count"] - Superchats this month
• data["superchat-total"]["count"] - Total count of superchats
• data["superchat-latest"] - An array containing latest superchat event
  • data["superchat-latest"]["name"] - Username
  • data["superchat-latest"]["amount"] - amount
• data["superchat-recent"] - An array of latest superchat events with each element structure as in superchat-latest

There is a difference between:

• cheer-*-donation and cheer-*-donator
• tip-*-donation and tip-*-donator

donation stands for single event (biggest one-time donation/cheer in period)

donator stands for cumulative amount of all events by this user.

Example for better understanding:

User	Amount
UserA	10
UserB	15
UserA	10

Then calling each scope will result:

tip-alltime-	amount	name
-donator	20	UserA
-donation	15	UserB

Recent events: You can access recent events of each type by calling:

data["follower-recent"];
data["subscriber-recent"];
data["host-recent"];
data["raid-recent"];
data["cheer-recent"];
data["tip-recent"];

Each of them is an array (number indexes 0-24), and every subarray contains:

let recentFollows=data["follower-recent"][0]; 
recentFollows["name"]; // Username,
recentFollows["createdAt"];// Timestamp like "2018-06-11T08:08:33.180Z",
recentFollows["$hashKey"]; // unique ID for example"object:5024",
recentFollows["type"]; // Event type "follower", "subscriber", "host", "raid", "cheer", "tip"

Depending on type there can be also:

• subscriber-recent

["tier"]; //Subscriber tier (1000,2000,3000)
["amount"]; // amount of months

• host-recent

["amount"]; // amount of viewers

• raid-recent

["amount"]; // amount of months

• cheer-recent

["amount"]; // amount of bits

• tip-recent

["amount"]; // amount of tip

There is also a list in chronological order of last 25 events (so if you want to make list of all events - use this one) - variable recents initialized one line after variable data.

It is an array of elements (each of them is array) with the same elements as in data["*-recent"] The last element of obj is currency, which contains:

• code - currency code (for example “USD”)
• name - currency name (for example "U.S. Dollar)
• symbol - currency symbol (for example “$”)

On Event Received:

Live event for alerts, chat messages, SE_API store updates, etc.

window.addEventListener('onEventReceived', function (obj) {
    // fancy stuff here
});

In the example above you have obj forwarded to that function, which has two interesting scopes within obj.detail:

• obj.detail.listener: Will provide you information about event type. This value is a string. Possible values:

  • follower-latest - New Follower
  • subscriber-latest - New Subscriber
  • host-latest - New host
  • cheer-latest - New cheer
  • tip-latest - New tip
  • raid-latest - New raid
  • message - New chat message received
  • delete-message - Chat message removed
  • delete-messages - Chat messages by userId removed
  • event:skip - User clicked "skip alert" button in activity feed
  • alertService:toggleSound - User clicked "mute/unmute alerts" button in activity feed
  • bot:counter - Update of bot counter
  • kvstore:update - Update of SE_API store value.
  • widget-button - User clicked custom field button in widget properties

• obj.detail.event: Will provide you information about event details. It contains few keys. For -latest events it is:

  • .name - user who triggered action
  • .amount - amount of action
  • .message - message attached to sub
  • .gifted - if this is a gift event for viewer
  • .sender - if it was a gift, a gifter (for community and single gifts)
  • .bulkGifted - if it is INITIAL event of community gift (${event.sender} gifted ${event.amount} subs to community)
  • .isCommunityGift - if it is one of community gifts train (${event.sender} gifted ${event.name} a sub as part of random giveaway!)
  • .playedAsCommunityGift - if the event was played as part of "cumulative sub bomb alert"

• there is also userCurrency for donations, you can use it (if initialized by let userCurrency;). For example: usercurrency.symbol

So expanding our sample code above you can have

window.addEventListener('onEventReceived', function (obj) {
  const listener = obj.detail.listener;
  const data = obj["detail"]["event"];
  // Assigned new const value, for easier handling. You can do it with .property or ["property"]. 
  // I personally recommend using [""] as some of keys can have "-" within,
  // so you won't be able to call them (JS will try to do math operation on it).

  // jQuery is included by default, so you can use following
  $("#usernameContainer").html(data["name"]);
  $("#actionContainer").html(listener);

  // You can use vanilla JS as well
  document.getElementById("amount").innerHTML = data["amount"]
});

Chat Message

For message events, there is an additional object that's accessible at obj.detail.event.data, which looks like this:

Twitch:

{
  "time": 1552400352142,
  "tags": {
    "badges": "broadcaster/1",
    "color": "#641FEF",
    "display-name": "SenderName",
    "emotes": "25:5-9",
    "flags": "",
    "id": "885d1f33-8387-4206-a668-e9b1409a998b",
    "mod": "0",
    "room-id": "85827806",
    "subscriber": "0",
    "tmi-sent-ts": "1552400351927",
    "turbo": "0",
    "user-id": "85827806",
    "user-type": ""
  },
  "nick": "sendername",
  "userId": "123123",
  "displayName": "senderName",
  "displayColor": "#641FEF",
  "badges": [
    {
      "type": "broadcaster",
      "version": "1",
      "url": "https://static-cdn.jtvnw.net/badges/v1/5527c58c-fb7d-422d-b71b-f309dcb85cc1/3",
      "description": "Broadcaster"
    }
  ],
  "channel": "channelname",
  "text": "Test Kappa test",
  "isAction": false,
  "emotes": [
    {
      "type": "twitch",
      "name": "Kappa",
      "id": "25",
      "gif": false,
      "urls": {
        "1": "https://static-cdn.jtvnw.net/emoticons/v1/25/1.0",
        "2": "https://static-cdn.jtvnw.net/emoticons/v1/25/2.0",
        "4": "https://static-cdn.jtvnw.net/emoticons/v1/25/4.0"
      },
      "start": 5,
      "end": 9
    }
  ],
  "msgId": "885d1f33-8387-4206-a668-e9b1409a99Xb"
}

Every emote displayed on chat is within array of objects emotes with start/end index of text you can replace with image NOTE: if you are creating chat widget, remember to store msgId and userId of each message (for example <div class="message" data-msgId="${msgId}" data-userId="${userId}"></div>) for message deletion events handling.

Youtube:

{
  "kind": "youtube#liveChatMessage",
  "etag": "joNqfOov4YhUTK1ly5QnEw2O_04",
  "id": "LCC.EhwKGkNQakd1YS0tZ293REZWa1AxZ0FkMFU0VzNn",
  "snippet": {
    "type": "textMessageEvent",
    "liveChatId": "KicKGFVDT2p0eVFPaTNNUjhYT3lzMFdOZmtKZxILMXFObko0UHU5bTA",
    "authorChannelId": "noRfodywm2MXfIUCp9nm2MX",
    "publishedAt": "2025-03-11T16:51:20.385245+00:00",
    "hasDisplayContent": true,
    "displayMessage": ":face-blue-smiling: Testing message",
    "textMessageDetails": {
      "messageText": ":face-blue-smiling: Testing message"
    }
  },
  "authorDetails": {
    "channelId": "noRfodywm2MXfIUCp9nm2MX",
    "channelUrl": "http://www.youtube.com/channel/noRfodywm2MXfIUCp9nm2MX",
    "displayName": "userName",
    "profileImageUrl": "https://yt3.ggpht.com/MkVId1UPvXogOyUqSyaFRZD2eFHqNaThFYO4-YNWAA4sQGvCPdoZKDkN5qgPUQ9BRiajmtcU=s88-c-k-c0x00ffffff-no-rj",
    "isVerified": false,
    "isChatOwner": false,
    "isChatSponsor": false,
    "isChatModerator": true
  },
  "msgId": "LCC.EhwKGkNQakd1YS0tZ293REZWa1AxZ0FkMFU0VzNn",
  "userId": "noRfodywm2MXfIUCp9nm2MX",
  "nick": "username",
  "badges": [
  ],
  "displayName": "userName",
  "isAction": false,
  "time": 1741711893915,
  "tags": [
  ],
  "displayColor": null,
  "channel": "noRfodywm2MXfIUCp9nm2MX",
  "text": ":face-blue-smiling: Testing message",
  "emotes": [
  ],
  "avatar": "https://yt3.ggpht.com/MkVId1UPvXogOyUqSyaFRZD2eFHqNaThFYO4-YNWAA4sQGvCPdoZKDkN5qgPUQ9BRiajmtcU=s88-c-k-c0x00ffffff-no-rj"
}

Message deletion

When user message is removed by channel moderator there is an event emited either:

• delete-message - with msgId of message to be removed
• delete-messages - with userId of user whose messages have to be removed This functionality is to prevent abusive content displayed in chat widget.

Bot counter

Contains two elements counter name (counter) and current value (value)

window.addEventListener('onEventReceived', function (obj) {
    const listener = obj.detail.listener;
    const data = obj.detail.event;

    if (listener === 'bot:counter' && data.counter === counter) {
        document.getElementById("mycounter").innerHTML = data.value;
    }
});

Button click

Contains two elements - field name (field) and value (value). Example below will send simplified event to test your chat widget

window.addEventListener('onEventReceived', function (obj) {
  const data = obj.detail.event;
  if (data.listener === 'widget-button') {
    if (data.field === 'chat' && data.value === 'First Message') {
      const emulated = new CustomEvent("onEventReceived", {
        detail: {
          "listener": "message",
          event: {
            data: {
              text: "Example message!",
              displayName: "StreamElements"
            }
          }
        }
      });
      window.dispatchEvent(emulated);
    }
  }
});

On Session Update

window.addEventListener('onSessionUpdate', function (obj) {
    const data = obj.detail.session;
    //fancy stuff here
});

This event is triggered every time a session data is updated (new tip/cheer/follower), basically most of the scenarios can be covered by onEventReceived, but onSessionUpdate provides a lot of more data you can use. The biggest advantage of using this is that you can check if top donator (not donation) changed. Also it is the recommended option for goal widgets.

Note: Due to complexity of object in onSessionUpdate, a onEventReceived event listener will be the best way to use for most of scenarios (easier to implement and better performance).

Example:

window.addEventListener('onSessionUpdate', function (obj) {
  const data = obj.detail.session;
  const tipTopDonator = data["tip-session-top-donator"];
  const cheerTopDonator = data["cheer-session-top-donator"];

  document.getElementById("top-donator").innerHTML = `${tipTopDonator["name"]} - ${tipTopDonator["amount"]}`;
  document.getElementById("top-cheerer").innerHTML = `${cheerTopDonator["name"]} - ${cheerTopDonator["amount"]}`;
});

data is the same as in onWidgetLoad so every property is listed in section above.