WebSocket Requests
Requests can be made to the server in stringified JSON format.
Requests and responses follow the following base schema:
{
"request": "<request>",
"id": "<id>"
}
{
"status": "ok" | "error",
"id": "<request-id>"
}
id
can be any string
value you want, and can be used to identify request/response pairs.Subscribe
Subscribe to a set of events from the connected Streamer.bot instance.
- If you are using the @streamerbot/client library, subscriptions are automatically added when using the
.on()
event handler - If you are interacting directly with the WebSocket Server, you must send a
Subscribe
request
{
"request": "Subscribe",
"id": "<id>",
"events": {
"<event category>": [
"<event name>",
"<event name>",
"...",
]
},
}
{
"request": "Subscribe",
"id": "my-subscribe-id",
"events": {
"Twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb"
]
},
}
{
"status": "ok",
"id": "my-subscribe-id",
"events": {
"Twitch": [
"Follow",
"Cheer",
"Sub",
"ReSub",
"GiftSub",
"GiftBomb"
]
},
}
// Using @streamerbot/client
client.subscribe('Twitch.ChatMessage');
UnSubscribe
Unsubscribe from any events you are currently subscribed to.
{
"request": "UnSubscribe",
"id": "<id>",
"events": {
"<event category>": [
"<event name>",
"<event name>",
"...",
]
},
}
{
"request": "UnSubscribe",
"id": "my-unsubscribe-id",
"events": {
"Twitch": [
"Follow"
]
},
}
{
"status": "ok",
"id": "my-unsubscribe-id",
"events": [
"Follow"
]
}
// Using @streamerbot/client
client.unsubscribe('Twitch.ChatMessage');
GetEvents
Fetch a list of all events that can be subscribed to on the connected Streamer.bot instance.
{
"request": "GetEvents",
"id": "<id>",
}
{
"request": "GetEvents",
"id": "my-get-events-id"
}
{
"status": "ok",
"id": "my-get-events-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"
]
}
}
// Using @streamerbot/client
const response = await client.getEvents();
console.log('Streamer.bot Events', response.events);
GetActions
Fetch a list of all actions in the connected Streamer.bot instance.
{
"request": "GetActions",
"id": "<id>"
}
{
"request": "GetActions",
"id": "my-get-actions-id"
}
{
"count": 1,
"actions": [
{
"enabled": true,
"group": "None",
"id": "a0ff6f91-a51e-4b7d-948b-5e03ff4a82f0",
"name": "Action Number One",
"subaction_count": 4,
"trigger_count": 1
},
],
"status": "ok",
"id": "my-get-actions-id"
}
// Using @streamerbot/client
const response = await client.getActions();
console.log('Streamer.bot Actions', response.actions);
DoAction
Execute an action on the connected Streamer.bot instance.
{
"request": "DoAction",
"action": {
"id": "<guid>",
"name": "<name>"
},
"args": {
"key": "value",
},
"id": "<id>"
}
{
"request": "DoAction",
"action": {
"id": "47da7c2c-1b7e-4ee7-9bbf-306bf18ff1b8"
},
"id": "sb:client:req:1753223220663-2906868922"
}
{
"status": "ok",
"id": "<id>"
}
// Using @streamerbot/client
const response = await client.doAction('47da7c2c-1b7e-4ee7-9bbf-306bf18ff1b8');
{
"request": "DoAction",
"id": "sb:client:req:1753224740175-3103164791"
"action": {
"name": "example action"
},
"args": {
"stringArg": "abcdef",
"numArg": 1234
},
}
{
"status": "ok",
"id": "<id>"
}
// Using @streamerbot/client
const response = await client.doAction(action = {name: "example action"},
args = {"stringArg" : "abcdef",
"numArg" : 1234}));
GetBroadcaster
Fetch information about the connected broadcaster account(s)
{
"request": "GetBroadcaster",
"id": "<id>"
}
{
"platforms": {
"twitch": {
"broadcastUser": "ik1497",
"broadcastUserName": "ik1497",
"broadcastUserId": 695682330,
"broadcasterIsAffiliate": false,
"broadcasterIsPartner": false,
"botUser": "MyBot",
"botUserName": "mybot",
"botUserId": "682553973"
},
"youtube": {
"broadcastUserName": "Ik1497 Tutorials",
"broadcastUserId": "UCl3oatIf9tYopHaZHvnH3xw",
"broadcastUserProfileImage": "https://yt3.ggpht.com/VpC8_9WcDEKcPSvnD6p1iGT_S2_XxdeZtL6tTL2axexj0SpG-c4Wx8i5lYNbJtvmzwCnzm9Bsg=s88-c-k-c0x00ffffff-no-rj"
},
"kick": {
"broadcasterLogin": "ik1497kicker",
"broadcasterUserName": "IK1497Kicker",
"broadcasterUserId": "5081399",
"broadcasterProfileUrl": "https://files.kick.com/images/user/5081399/profile_image/conversion/cf435acc-5bef-4ef9-938d-4f9c0582af19-fullsize.webp"
}
},
"connected": [
"twitch",
"youtube",
"kick"
],
"disconnected": [
"trovo"
],
"status": "ok",
"id": "<id>"
}
// Using @streamerbot/client
const response = await client.getBroadcaster();
console.log('Streamer.bot Broadcasters', response.platforms);
GetCredits
Fetch the current credits system data.
{
"request": "GetCredits",
"id": "<id>"
}
{
"id": "<id>",
"events": {
"follows": [],
"cheers": [],
"subs": [],
"resubs": [],
"giftsubs": [],
"giftbombs": [],
"raided": [],
"rewardredemptions": [],
"goalcontributions": [],
"gameupdates": [],
"pyramids": [],
"hypetrains": []
},
"hypeTrain": {
"conductors": [],
"contributors": []
},
"users": {
"editors": [],
"moderators": [],
"subscribers": [],
"vips": [],
"groups": [],
"users": []
},
"groups": {},
"top": {
"allBits": [],
"monthBits": [],
"weekBits": [],
"channelRewards": []
},
"status": "ok"
}
// Using @streamerbot/client
const response = await client.getCredits();
console.log('Streamer.bot Credits', response.credits);
TestCredits
Fill credits system with test data for testing.
{
"request": "TestCredits",
"id": "<id>"
}
// Using @streamerbot/client
const response = await client.testCredits();
console.log('Streamer.bot Test Credits', response.credits);
ClearCredits
Reset the current credits system data.
{
"request": "ClearCredits",
"id": "<id>"
}
// Using @streamerbot/client
const response = await client.clearCredits();
console.log('Streamer.bot Credits Cleared', response.status);
GetInfo
Fetch information about the connected Streamer.bot instance.
{
"request": "GetInfo",
"id": "<id>"
}
{
"info": {
"instanceId": "jx5gd80u-3b04-4c9b-x902-4589nn5010ax",
"name": "Streamer.bot",
"version": "0.1.15",
"os": "windows",
"osVersion": "6.2.9200.0",
"mode": "ui",
"darkMode": false,
"source": "websocketServer"
},
"status": "ok",
"id": "123"
}
// Using @streamerbot/client
const response = await client.getInfo();
console.log('Streamer.bot Instance Info', response.info);
GetActiveViewers
Fetch a list of all active viewers for connected broadcaster accounts.
{
"request": "GetActiveViewers",
"id": "<id>"
}
{
"count": 2,
"viewers": [
{
"id": "695682330",
"type": "kick",
"login": "ik1497",
"display": "ik1497",
"subscribed": true,
"role": "Broadcaster",
"groups": [],
"channelPointsUsed": 0,
"previousActive": "2022-12-20T01:03:01.4613004+01:00",
"exempt": true
},
{
"id": "750146097",
"type": "twitch",
"login": "ik1497bot",
"display": "Ik1497Bot",
"subscribed": false,
"role": "Moderator",
"groups": ["Friends"],
"channelPointsUsed": 0,
"previousActive": "2022-12-20T01:03:10.5548462+01:00",
"exempt": false
}
],
"status": "ok",
"id": "123"
}
// Using @streamerbot/client
const response = await client.getActiveViewers();
console.log('Streamer.bot Active Viewers', response.viewers);
GetCodeTriggers
Returns the list of code triggers available to be invoked by ExecuteCodeTrigger.
{
"request": "GetCodeTriggers",
"id": "<id>"
}
{
"request": "GetCodeTriggers",
"id": "my-subscribe-id"
}
{
"status": "ok",
"id": "my-subscribe-id",
"count": 1,
"triggers": [
{
"name": "Channel Created",
"eventName": "channel_created",
"category": "Custom/Discord Server/Channels"
}
]
}
// Using @streamerbot/client
const response = await client.getCodeTriggers();
ExecuteCodeTrigger
Triggers a code trigger, causing any associated actions to be executed.
{
"request": "ExecuteCodeTrigger",
"id": "<id>",
"triggerName": "<triggerName>",
"args": {
"key": "value",
}
}
{
"request": "ExecuteCodeTrigger",
"id": "my-subscribe-id",
"triggerName": "poll_vote_removed",
"args": {
"stringArg": "abcdef",
"numArg": 1234
}
}
{
"status": "ok",
"id": "my-subscribe-id"
}
// Using @streamerbot/client
client.executeCodeTrigger(triggerName = "poll_vote_removed",
args = {"stringArg" : "abcdef",
"numArg" : 1234});
GetCommands
Returns the list of defined commands.
{
"request": "GetCommands",
"id": "<id>"
}
{
"request": "GetCommands",
"id": "my-subscribe-id"
}
{
"status": "ok",
"id": "my-subscribe-id",
"commands": [
{
"id": "81bc8200-256d-4e1e-9e41-5010c3b808de",
"enabled": false,
"name": "My Game",
"group": "playing with viewers",
"commands": [
"!addplayer",
"!nextplayer",
"!randomplayer"
],
"caseSensitive": false,
"ignoreInternal": true,
"ignoreBotAccount": true,
"sources": 1
},
{
"id": "ac0dfb07-b5e2-4e97-8528-ca27dd67f47c",
"enabled": true,
"name": "CheckFiveMPlayers",
"group": null,
"commands": [
"!server"
],
"caseSensitive": false,
"ignoreInternal": true,
"ignoreBotAccount": true,
"sources": 1
}
],
"count": 2
}
// Using @streamerbot/client
const response = await client.getCommands();
TwitchGetEmotes
Fetches a list of emotes for Twitch.
{
"request": "TwitchGetEmotes",
"id": "<id>"
}
{
"request": "TwitchGetEmotes",
"id": "my-subscribe-id",
}
{
"status": "ok",
"id": "my-subscribe-id",
"emotes": {
"userEmotes": [
{
"name": "CurseLit",
"type": "twitch_globals",
"imageUrl": "https://static-cdn.jtvnw.net/emoticons/v2/116625/default/dark/3.0"
},
{
"name": "demons176Pumpkin",
"type": "twitch_subscriptions",
"imageUrl": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_6d5daa168c274d4fbf8ae46216e3730a/default/dark/3.0"
},
{
"name": "CurseLit",
"type": "twitch_globals",
"imageUrl": "https://static-cdn.jtvnw.net/emoticons/v2/116625/default/dark/3.0"
}
],
"bttvEmotes": [
{
"name": "AngelThump",
"imageUrl": "https://cdn.betterttv.net/emote/566ca1a365dbbdab32ec055b/3x",
"type": "BTTVGlobal",
"zeroWidth": false
}
],
"ffzEmotes": [
{
"name": "CatBag",
"imageUrl": "https://cdn.frankerfacez.com/emote/25927/4",
"type": "FFZGlobal",
"zeroWidth": false
}
],
"sevenTvEmotes": [
{
"name": "reckH",
"imageUrl": "https://cdn.7tv.app/emote/01F014S6KG0007E4VV006YKSM3/4x.png",
"type": "7TVGlobal",
"zeroWidth": false
}
]
}
}
// Using @streamerbot/client
const response = await client.getEmotes("twitch");
YouTubeGetEmotes
Fetches a list of emotes for YouTube.
{
"request": "YouTubeGetEmotes",
"id": "<id>"
}
{
"request": "YouTubeGetEmotes",
"id": "my-subscribe-id",
}
{
"status": "ok",
"id": "my-subscribe-id",
"emotes": {
"userEmotes": [
{
"name": ":hand-pink-waving:",
"type": "youtube",
"imageUrl": "https://yt3.ggpht.com/KOxdr_z3A5h1Gb7kqnxqOCnbZrBmxI2B_tRQ453BhTWUhYAlpg5ZP8IKEBkcvRoY8grY91Q=w24-h24-c-k-nd"
}
],
"bttvEmotes": [
{
"name": "AngelThump",
"imageUrl": "https://cdn.betterttv.net/emote/566ca1a365dbbdab32ec055b/3x",
"type": "BTTVGlobal",
"zeroWidth": false
}
],
"sevenTvEmotes": [
{
"name": "reckH",
"imageUrl": "https://cdn.7tv.app/emote/01F014S6KG0007E4VV006YKSM3/4x.png",
"type": "7TVGlobal",
"zeroWidth": false
}
]
"ffzEmotes": [
{
"name": "CatBag",
"imageUrl": "https://cdn.frankerfacez.com/emote/25927/4",
"type": "FFZGlobal",
"zeroWidth": false
}
]
}
}
// Using @streamerbot/client
const response = await client.getEmotes("youtube");
GetGlobals
Returns all the global variables, either persisted or temporary.
{
"request": "GetGlobals",
"id": "<id>",
"persisted": <bool>
}
{
"request": "GetGlobal",
"id": "my-subscribe-id",
"persisted": true
}
{
"status": "ok",
"id": "my-subscribe-id",
"variables": [
"aGlobal": {
"name": "aGlobal",
"value": "4",
"lastWrite": "2025-07-22T11:32:17.935-07:00"
},
"alertInterval": {
"name": "alertInterval",
"value": 3,
"lastWrite": "2025-06-29T22:03:21.734-07:00"
}
],
"count": 2
}
// Using @streamerbot/client
const response = await client.getGlobals();
console.log(`aGlobal is ${response.variables["aGlobal"].value}`); // ==> 4
GetGlobal
Gets a single persisted or temporary global variable. Returns an error if the variable doesn't exist.
{
"request": "GetGlobal",
"id": "<id>",
"variable": "<name>",
"persisted": <bool>,
}
{
"request": "GetGlobal",
"id": "my-subscribe-id",
"variable": "aGlobal",
"persisted": true
}
{
"status": "ok",
"id": "my-subscribe-id",
"variable": {
"name": "aGlobal",
"value": "4",
"lastWrite": "2025-07-22T11:32:17.935-07:00"
}
}
// Using @streamerbot/client
const response = await client.getGlobal(name = "aGlobal",
persisted= true);
console.log(`aGlobal is ${response.variable.value}`); // ==> 4
TwitchGetUserGlobals
Fetches the values of a given user variable across all Twitch users.
{
"request": "TwitchGetUserGlobals",
"id": "<id>",
"variable": "<name>",
"persisted": <bool>,
}
{
"request": "TwitchGetUserGlobals",
"id": "my-subscribe-id",
"variable": "tuna",
"persisted": true,
}
{
"status": "ok",
"id": "my-subscribe-id",
"variables": [
{
"name": "tuna",
"userId": "136079477",
"userLogin": "whazzittoya",
"userName": "WhazzItToYa",
"platform": "twitch",
"value": 3,
"lastWrite": "2025-07-15T19:46:40.971-07:00"
},
{
"name": "tuna",
"userId": "39547242",
"userLogin": "nervousbeard",
"userName": "NERVOUSBEARD",
"platform": "twitch",
"value": "a second fish",
"lastWrite": "2025-07-22T17:17:34.053-07:00"
}
],
"count": 2
}
// Using @streamerbot/client
const response = await client.getUserGlobals('twitch', 'tuna');
TwitchGetUserGlobal
Gets either a single user variable for a given user, or all variables for that user.
{
"request": "TwitchGetUserGlobal",
"id": "<id>",
"userId": "<userId>",
"persisted": <bool>,
}
{
"request": "TwitchGetUserGlobal",
"id": "my-subscribe-id",
"userId": "136079477",
"persisted": true
}
{
"status": "ok",
"id": "my-subscribe-id",
"variables": [
{
"name": "tuna",
"value": 3,
"lastWrite": "2025-07-15T19:46:40.971-07:00"
},
{
"name": "addedTime",
"value": 1752206450,
"lastWrite": "2025-07-10T21:00:50.553-07:00"
}
],
"count": 2,
}
// Using @streamerbot/client
const response = await client.getUserGlobal(platform = "twitch",
userId = "136079477");
{
"request": "TwitchGetUserGlobal",
"id": "my-subscribe-id",
"userId": "136079477",
"variable": "tuna",
"persisted": true
}
{
"status": "ok",
"id": "my-subscribe-id",
"variable": {
"name": "tuna",
"value": 3,
"lastWrite": "2025-07-15T19:46:40.971-07:00"
}
}
// Using @streamerbot/client
const response = await client.getUserGlobal(platform = "twitch", userId = "136079477", name = "tuna");
SendMessage
Sends a message to the broadcaster's chat.
{
"request": "SendMessage",
"id": "<id>",
"platform": "twitch | kick | trovo | youtube",
"bot": "true/false",
"internal": "true/false",
"message": "<message>"
}
{
"request": "SendMessage",
"id": "my-subscribe-id",
"bot": true,
"internal": false,
"message": "This is a test"
}
{
"status": "ok",
"id": "my-subscribe-id"
}
// Using @streamerbot/client
client.sendMessage(platform = "twitch",
message = "This is a test",
options = { bot: true,
internal: false });
GetUserPronouns
Fetches the pronouns for a given user.
{
"request": "GetUserPronouns",
"id": "<id>",
"platform": "twitch",
"userLogin": "<login>"
}
{
"request": "GetUserPronouns",
"id": "my-subscribe-id",
"platform": "twitch",
"userLogin": "justsomeguyyouknow",
}
{
"status": "ok",
"id": "my-subscribe-id",
"userLogin": "justsomeguyyouknow",
"pronoun": {
"pronounSubject": "He",
"pronounObject": "Him",
"pronounPossessive": "His",
"pronounPronoun": "His",
"pronounReflexive": "Himself",
"pronounPastTense": "Was",
"pronounSubjectLower": "he",
"pronounObjectLower": "him",
"pronounPossessiveLower": "his",
"pronounPronounLower": "his",
"pronounReflexiveLower": "himself",
"pronounPastTenseLower": "was",
"pronounCurrentTense": "Is",
"pronounCurrentTenseLower": "is",
"pronounPluralLower": "s",
"pronouns": "(He/Him)",
"pronounLastCached": "2025-07-22T15:23:02.529-07:00",
"userFound": true,
"pronounsPlain": "He/Him"
}
}
// Using @streamerbot/client
client.getUserPronouns(platform = "twitch",
userLogin = "justsomeguyyouknow"));