Requests can be made to the server in JSON format.
The basic format for a request is as follows:
{
"request": "<request>",
"id": "<id>"
}
⚠️ This request is required to enable you to listen to events
{
"request": "Subscribe",
"id": "<id>",
"events": {
"<event category>": [
"<event name>",
"<event name>",
"...",
]
},
}
{
"request": "Subscribe",
"id": "<id>",
"events": {
"Twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb"
]
},
}
This request allows you to unsubscribe from any message events you are currently subscribed to
{
"request": "UnSubscribe",
"id": "<id>",
"events": {
"<event category>": [
"<event name>",
"<event name>",
"...",
]
},
}
{
"request": "UnSubscribe",
"id": "<id>",
"events": {
"Twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb"
]
},
}
This request will get you a list of all events that may be emitted
{
"request": "GetEvents",
"id": "<id>",
}
{
"events": {
"general": [
"Custom"
],
"twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb",
"Raid",
"HypeTrainStart",
"HypeTrainUpdate",
"HypeTrainLevelUp",
"HypeTrainEnd",
"RewardRedemption",
"RewardCreated",
"RewardUpdated",
"RewardDeleted",
"CommunityGoalContribution",
"CommunityGoalEnded",
"StreamUpdate",
"Whisper",
"FirstWord",
"SubCounterRollover",
"BroadcastUpdate",
"StreamUpdateGameOnConnect",
"PresentViewers",
"PollCreated",
"PollUpdated",
"PollCompleted",
"PredictionCreated",
"PredictionUpdated",
"PredictionCompleted",
"PredictionCanceled",
"PredictionLocked",
"ChatMessage",
"ChatMessageDeleted",
"UserTimedOut",
"UserBanned",
"Announcement",
"AdRun",
"BotWhisper",
"CharityDonation",
"CharityCompleted",
"CoinCheer",
"ShoutoutCreated",
"UserUntimedOut",
"CharityStarted",
"CharityProgress",
"GoalBegin",
"GoalProgress",
"GoalEnd",
"ShieldModeBegin",
"ShieldModeEnd",
"AdMidRoll"
],
"streamlabs": [
"Donation",
"Merchandise"
],
"speechToText": [
"Dictation",
"Command"
],
"command": [
"Message",
"Whisper",
"MessageCooldown",
"BotWhisper"
],
"fileWatcher": [
"Changed",
"Created",
"Deleted",
"Renamed"
],
"quote": [
"Added",
"Show"
],
"misc": [
"TimedAction",
"PyramidSuccess",
"PyramidBroken"
],
"raw": [
"Action",
"SubAction",
"ActionCompleted"
],
"websocketClient": [
"Open",
"Close",
"Message"
],
"streamElements": [
"Tip",
"Merch"
],
"websocketCustomServer": [
"Open",
"Close",
"Message"
],
"donorDrive": [
"Donation",
"ProfileUpdated"
],
"youTube": [
"BroadcastStarted",
"BroadcastEnded",
"Message",
"MessageDeleted",
"UserBanned",
"SuperChat",
"SuperSticker",
"NewSponsor",
"MemberMileStone",
"NewSponsorOnlyStarted",
"NewSponsorOnlyEnded",
"StatisticsUpdated",
"BroadcastUpdated",
"MembershipGift",
"GiftMembershipReceived",
"FirstWords",
"PresentViewers"
],
"pulsoid": [
"HeartRatePulse"
],
"hypeRate": [
"HeartRatePulse"
],
"kofi": [
"Donation",
"Subscription",
"Resubscription",
"ShopOrder",
"Commission"
],
"patreon": [
"FollowCreated",
"FollowDeleted",
"PledgeCreated",
"PledgeUpdated",
"PledgeDeleted"
],
"application": [
"ActionAdded",
"ActionUpdated",
"ActionDeleted"
],
"tipeeeStream": [
"Donation"
],
"treatStream": [
"Treat"
],
"shopify": [
"OrderCreated",
"OrderPaid"
],
"obs": [
"Connected",
"Disconnected"
],
"midi": [
"Message"
]
},
"status": "ok"
"id": "<id>",
}
This request will get you a list of all the actions you have configured in your Streamer.bot instance
{
"request": "GetActions",
"id": "<id>"
}
{
"count": 00,
"actions": [
{
"id": "<action guid>",
"name": "<action name>",
"group": "<group name>",
"subaction_count": 0,
"enabled": true|false
},
],
"status": "ok",
"id": "<id>"
}
This request will trigger an action that you provide
{
"request": "DoAction",
"action": {
"id": "<guid>",
"name": "<name>"
},
"args": {
"key": "value",
},
"id": "<id>"
}
If the action is not found, an error will be returned, if the action was dispatched it will return success.
{
"status": "ok",
"id": "<id>"
}
This request will give the broadcaster information for Twitch/Youtube
{
"request": "GetBroadcaster",
"id": "<id>"
}
{
"platforms": {
"twitch": {
"broadcastUser": "ik1497",
"broadcastUserName": "ik1497",
"broadcastUserId": 695682330,
"broadcasterIsAffiliate": false,
"broadcasterIsPartner": false
},
"youtube": {
"broadcastUserName": "Ik1497 Tutorials",
"broadcastUserId": "UCl3oatIf9tYopHaZHvnH3xw",
"broadcastUserProfileImage": "https://yt3.ggpht.com/VpC8_9WcDEKcPSvnD6p1iGT_S2_XxdeZtL6tTL2axexj0SpG-c4Wx8i5lYNbJtvmzwCnzm9Bsg=s88-c-k-c0x00ffffff-no-rj"
}
},
"connected": [
"twitch",
"youtube"
],
"disconnected": [],
"status": "ok",
"id": "<id>"
}
{
"request": "GetCredits",
"id": "<id>"
}
{
"Events": {
"Follows": [],
"Cheers": [],
"Subs": [],
"ReSubs": [],
"GiftSubs": [],
"GiftBombs": [],
"Raided": [],
"RewardRedemptions": [],
"GoalContributions": [],
"GameUpdates": [],
"Pyramids": []
},
"HypeTrainConductor": [],
"HypeTrainContributors": [],
"User": {
"Editors": [],
"Moderator": [],
"Subscriber": [],
"VIPs": [],
"Users": [],
"regulars": []
},
"Custom": {},
"TopBits": {
"All": [],
"Month": [],
"Week": []
},
"TopChannelRewards": [],
"status": "ok",
"id": "<id>"
}
{
"request": "TestCredits",
"id": "<id>"
}
{
"request": "ClearCredits",
"id": "<id>"
}
{
"request": "GetInfo",
"id": "<id>"
}
{
"info": {
"instanceId": "jx5gd80u-3b04-4c9b-x902-4589nn5010ax",
"name": "Streamer.bot",
"version": "0.1.15",
"os": "windows"
},
"status": "ok",
"id": "123"
}
{
"request": "GetActiveViewers",
"id": "<id>"
}
{
"count": 2,
"viewers": [
{
"id": "695682330",
"login": "ik1497",
"display": "ik1497",
"subscribed": true,
"role": "Broadcaster",
"groups": [],
"channelPointsUsed": 0,
"lastActive": "2022-12-20T01:03:01.4613004+01:00",
"exempt": true
},
{
"id": "750146097",
"login": "ik1497bot",
"display": "Ik1497Bot",
"subscribed": false,
"role": "Moderator",
"groups": [],
"channelPointsUsed": 0,
"lastActive": "2022-12-20T01:03:10.5548462+01:00",
"exempt": false
}
],
"status": "ok",
"id": "123"
}
{
"request": "ExecuteCodeTrigger",
"triggerName": "<registered name of event>",
"args": {
},
"id": "<id>"
}
{
"request": "GetCodeTriggers",
"id": "<id>"
}
{
"count": 3,
"triggers": [
{
"name": "Song Start",
"eventName": "progressbar_spotify_songstart",
"category": "Custom/Spotify"
},
{
"name": "Song Pause",
"eventName": "progressbar_spotify_songpause",
"category": "Custom/Spotify"
},
{
"name": "Song End",
"eventName": "progressbar_spotify_songend",
"category": "Custom/Spotify"
},
],
"status": "ok"
"id": "123",
}
Example Javascript code for interacting with the WebSocket Server
Code to connect - this function is ideally called directly / indirectly from onload
function connectws() {
if ("WebSocket" in window) {
const ws = new WebSocket("ws://localhost:8080/");
}
}
Code to attempt to reconnect (after 10 seconds) when disconnected:
ws.onclose = function() {
// "connectws" is the function we defined previously
setTimeout(connectws, 10000);
};
Code to subscribe to events - In this example: Follows, Cheers, Subs, Resubs, Gift Subs and Gift Bombs.
ws.onopen = function() {
ws.send(JSON.stringify(
{
"request": "Subscribe",
"events": {
"Twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb"
]
},
"id": "123"
}
));
}
Code to Handle the above messages when received from the server:
ws.onmessage = function (event) {
// grab message and parse JSON
const msg = event.data;
const wsdata = JSON.parse(msg);
// check for events to trigger
if (wsdata.event.source === 'Twitch') {
if (wsdata.event.type === 'Sub' || wsdata.event.type === 'ReSub') {
alert(`trigger sub event for ${wsdata.data.displayName}`);
} else if (wsdata.event.type === 'GiftSub') {
alert(`trigger Gift sub event for ${wsdata.data.recipientDisplayName}`);
} else if (wsdata.event.type === 'GiftBomb') {
if (wsdata.data.isAnonymous === false) {
alert(`trigger gift bomb event for ${wsdata.data.displayName} ${wsdata.data.gifts} subs`);
} else {
alert(`trigger gift bomb event for Anonymous ${wsdata.data.gifts} subs`);
}
} else if (wsdata.event.type === 'Follow') {
alert(`trigger follow event for ${wsdata.data.displayName}`);
} else if (wsdata.event.type === 'Cheer') {
alert(`trigger cheer event for ${wsdata.data.message.displayName} ${wsdata.data.message.bits}`);
}
}
};