API

Requests

Reference of all requests that made to a Streamer.bot instance

`getInfo`

Fetch information about the connected Streamer.bot instance.

Signature

getInfo(): Promise<GetInfoResponse>

Response Type

GetInfoResponse.ts

type GetInfoResponse = {
  status: 'ok' | 'error';
  id: string;
  info: {
    instanceId: string;
    name: string;
    os: 'windows' | 'linux' | 'macosx' | string;
    osVersion: string;
    version: string;
    source?: 'websocketServer' | 'streamDeckServer' | 'httpServer' | string;
  };
};

Examples

const infoResponse = await client.getInfo();

{
  "status": "ok",
  "id": "[request-id]",
  "info": {
    "instanceId": "c1a51f77-ec2e-4051-8378-94e4e8b6044b",
    "name": "Streamer.bot",
    "os": "windows",
    "osVersion": "10.0.22631.0",
    "version": "0.2.5",
    "source": "websocketServer"
  }
}

`getEvents`

Fetch a list of all events that can be subscribed to on the connected Streamer.bot instance.

Signature

getEvents(): Promise<GetEventsResponse>

Response Type

GetEventsResponse.ts

type GetEventsResponse = {
  status: 'ok' | 'error';
  id: string;
  events: StreamerbotEventsType;
};

Examples

const response: GetEventsResponse = await client.getEvents();

  {
    "status": "ok",
    "id": "[request-id]",
    "events": { ... }
  }

The events key will contain the Streamer.bot Events structure, with all events supported by the connected instance.

`on`

Quickly define an event handler for a specific event or set of events.

Event subscriptions will be automatically added as needed

Signature

on(events: StreamerbotEventName | StramerbotEventName[], listener: (data: unknown) => void): Promise<void>

Parameters

events

StreamerbotEventName | StreamerbotEventName[] required

Define the event(s) to subscribe to, formatted as '[source].[eventType]'

eventType supports wildcards, e.g. Twitch.* ::
listener
(data: unknown) => void required
Define a callback function to handle data anytime the requested events are triggered
::

Examples

// Subscribe to Twitch ChatMessage events
await client.on('Twitch.ChatMessage', (data) => {
  console.log('Twitch Chat Message Received:', data);
});

// Subscribe to all Twitch events
await client.on('Twitch.*', (data) => {
  console.log('Twitch Event Received:', data);
});

Subscribe to a set of events on the connected Streamer.bot instance.

Signature

subscribe(events: StreamerbotEventsSubscription | '*'): Promise<SubscribeResponse>

Parameters

events

StreamerbotEventsSubscription | '\*' required

Define the events to subscribe to, formatted as an Events Subscription

You can use wildcard '*' to subscribe to all events :: ::

Response Type

SubscribeResponse.ts

type SubscribeResponse = {
  status: 'ok' | 'error';
  id: string;
  events: StreamerbotEventsSubscription;
};

Examples

// Subscribe to Twitch ChatMessage events
const response = await client.subscribe({
  Twitch: ['ChatMessage'],
});

{
  "status": "ok",
  "id": "[request-id]",
  "events": {
    "Twitch": ["ChatMessage"]
  }
}

`unsubscribe`

Unsubscribe from a set of events on the connected Streamer.bot instance.

Signature

unsubscribe(events: StreamerbotEventsSubscription | '*'): Promise<UnsubscribeResponse>

Parameters

events

StreamerbotEventsSubscription | '\*' required

Define the events to unsubscribe from, formatted as an Events Subscription

You can use wildcard '*' to unsubscribe from all events :: ::

Response Type

UnsubscribeResponse.ts

type UnsubscribeResponse = {
  status: 'ok' | 'error';
  id: string;
  events: StreamerbotEventsSubscription;
};

Examples

// Unsubscribe from Twitch ChatMessage events
const response = await client.unsubscribe({
  Twitch: ['ChatMessage'],
});

{
  "status": "ok",
  "id": "[request-id]",
  "events": {
    "Twitch": ["ChatMessage"]
  }
}

`getActions`

Fetch a list of all actions in the connected Streamer.bot instance.

Signature

getActions(): Promise<GetActionsResponse>

Response Type

GetActionsResponse.ts

type GetActionsResponse = {
  status: 'ok' | 'error';
  id: string;
  actions: Array<{
    enabled: boolean;
    group: string;
    id: string;
    name: string;
    subaction_count: number;
  }>;
  count: number;
};

Examples

const response = await client.getActions();

{
  "status": "ok",
  "id": "[request-id]",
  "actions": [
    {
      "enabled": true,
      "group": "None",
      "id": "a0ff6f91-a51e-4b7d-948b-5e03ff4a82f0",
      "name": "Action Number One",
      "subaction_count": 4
    },
    {
      "enabled": false,
      "group": "None",
      "id": "84a0dfe7-5033-4e14-964b-ce2dfe9f5e09",
      "name": "Action Number Two",
      "subaction_count": 18
    }
  ],
  "count": 2
}

`doAction`

Execute an action on the connected Streamer.bot instance.

Signature

doAction(action: string | { id?: string, name?: string }, args?: Record<string, any>, options?: Partial<{ customEventResponse: boolean; }>): Promise<DoActionResponse>

Parameters

action

string | { id?: string, name?: string } required

The id of the action to execute, or an object containting the action id and/or name

args

Record<string, any>

Optionally define any arguments to pass to the executed action as JSON

options.customEventResponse

boolean

If true, wait for a Custom Event Trigger with event name matching the %sbClientResponse% argument from the outgoing request

Response Type

Response

type DoActionResponse<T = Record<string, any>> = StreamerbotResponse<{
  status: 'ok' | 'error';
  id: string;
  args?: Record<string, any>;
  customEventResponseArgs?: T;
}>;

Examples

// Execute an action by id
const response = await client.doAction('[action-id]');

// Execute an action by name
const response = await client.doAction({ name: 'My Action' });

{
  "status": "ok",
  "id": "[request-id]"
}

`getBroadcaster`

Fetch information about the connected broadcaster account(s)

Signature

getBroadcaster(): Promise<GetBroadcasterResponse>

Response Type

GetBroadcasterResponse.ts

type GetBroadcasterResponse = {
  status: 'ok' | 'error';
  id: string;
  platforms: {
    twitch?: {
      broadcastUser: string;
      broadcastUserName: string;
      broadcastUserId: string;
      broadcastIsAffiliate: boolean;
      broadcastIsPartner: boolean;
    };
    youtube?: {
      broadcastUserName: string;
      broadcastUserId: string;
      broadcastUserProfileImage: string;
    };
  };
  connected: Array<'twitch' | 'youtube'>;
  disconnected: Array<'twitch' | 'youtube'>;
};

Examples

const response = await client.getBroadcaster();

{
  "status": "ok",
  "id": "[request-id]",
  "platforms": {
    "twitch": {
      "broadcastUser": "SomeUsername",
      "broadcastUserName": "someusername",
      "broadcastUserId": "12345678",
      "broadcastIsAfilliate": true,
      "broadcastIsPartner": false
    }
  },
  "connected": ["twitch"],
  "disconnected": ["youtube"]
}

`getActiveViewers`

Fetch a list of all active viewers for connected Twitch or YouTube accounts.

Signature

getActiveViewers(): Promise<GetActiveViewersResponse>

Response Type

GetActiveViewersResponse.ts

type GetActiveViewersResponse = {
  status: 'ok' | 'error';
  id: string;
  viewers: Array<{
    channelPointsUsed: number;
    display: string;
    exempt: boolean;
    groups: Array<string>;
    id: string;
    login: string;
    previousActive: string;
    role: string;
    subscribed: boolean;
  }>;
};

Examples

const response = await client.getActiveViewers();

{
  "status": "ok",
  "id": "[request-id]",
  "viewers": [
    {
      "id": "12345678",
      "login": "someusername",
      "display": "SomeUsername",
      "subscribed": true,
      "role": "Broadcaster",
      "groups": [],
      "channelPointsUsed": 5661,
      "previousActive": "2023-01-28T12:36:45.3764724-05:00",
      "exempt": false
    }
  ]
}

`getCodeTriggers`

Fetch a list of all Custom Triggers that have been defined on the connected Streamer.bot instance

Signature

getCodeTriggers(): Promise<GetCodeTriggersResponse>

Response Type

GetCodeTriggersResponse.ts

type GetCodeTriggersResponse = {
  status: 'ok' | 'error';
  id: string;
  triggers: Array<{
    name: string;
    eventName: string;
    category: string;
  }>;
  count: number;
};

Examples

const response = await client.getCodeTriggers();

`executeCodeTrigger`

Execute a Custom Trigger that has been defined on the connected Streamer.bot instance

Signature

executeCodeTrigger(triggerName: string, args?: Record<string, any>, options?: Partial<{ customEventResponse: boolean; }>): Promise<ExecuteCodeTriggerResponse>

Parameters

triggerName

String required

The name of your custom code trigger

args

Record<string, any>

Any arguments you want to pass to your trigger execution as JSON

options.customEventResponse

boolean

If true, wait for a Custom Event Trigger with event name matching the %sbClientResponse% argument from the outgoing request

Response Type

ExecuteCodeTriggerResponse.ts

type ExecuteCodeTriggerResponse = {
  status: 'ok' | 'error';
  id: string;
  customEventResponseArgs?: T;
};

Examples

// Execute a trigger named 'myCustomTrigger', with some custom arguments
const response = await client.executeCodeTrigger('myCustomTrigger', {
  value: 23,
  someArg: 'testing!',
});

type GetCreditsResponse = {
  status: 'ok' | 'error';
  id: string;
  credits: {
    events: {
      cheers?: Array<string>;
      follows?: Array<string>;
      gameupdates?: Array<string>;
      giftbombs?: Array<string>;
      giftsubs?: Array<string>;
      goalcontributions?: Array<string>;
      hypetrains?: Array<string>;
      pyramids?: Array<string>;
      raided?: Array<string>;
      resubs?: Array<string>;
      rewardredemptions?: Array<string>;
      subs?: Array<string>;
    };
    users: {
      editors?: Array<string>;
      groups?: Array<string>;
      moderators?: Array<string>;
      subscribers?: Array<string>;
      vips?: Array<string>;
      users?: Array<string>;
    };
    hypeTrain: {
      conductors: Array<string>;
      contributors: Array<string>;
    };
    top: {
      allBits: Array<string>;
      monthBits: Array<string>;
      weekBits: Array<string>;
      channelRewards: Array<string>;
    };
    groups: {};
    custom: {};
  };
};

Examples

const response = await client.getCredits();

type TestCreditsResponse = {
  status: 'ok' | 'error';
  id: string;
  credits: {
    events: {
      cheers?: Array<string>;
      follows?: Array<string>;
      gameupdates?: Array<string>;
      giftbombs?: Array<string>;
      giftsubs?: Array<string>;
      goalcontributions?: Array<string>;
      hypetrains?: Array<string>;
      pyramids?: Array<string>;
      raided?: Array<string>;
      resubs?: Array<string>;
      rewardredemptions?: Array<string>;
      subs?: Array<string>;
    };
    users: {
      editors?: Array<string>;
      groups?: Array<string>;
      moderators?: Array<string>;
      subscribers?: Array<string>;
      vips?: Array<string>;
      users?: Array<string>;
    };
    hypeTrain: {
      conductors: Array<string>;
      contributors: Array<string>;
    };
    top: {
      allBits: Array<string>;
      monthBits: Array<string>;
      weekBits: Array<string>;
      channelRewards: Array<string>;
    };
    groups: {};
    custom: {};
  };
};

Examples

const response = await client.testCredits();

type ClearCreditsResponse = {
  status: 'ok' | 'error';
  id: string;
};

Examples

const response = await client.clearCredits();

type GetCommandsResponse = {
  status: 'ok' | 'error';
  commands: Array<{
    id: string;
    enabled: boolean;
    name: string;
    group: string;
    commands: Array<string>;
    caseSensitive: boolean;
    ignoreInternal: boolean;
    ignoreBotAccount: boolean;
    sources: Array<string>;
  }>;
  count: number;
};

Examples

const response = await client.getCommands();

type GetMonitoredYouTubeBroadcastsResponse = {
  status: 'ok' | 'error';
  broadcasts: Array<{
    actualEndTime: string;
    actualStartTime: string;
    categoryId: string;
    channelId: string;
    description: string;
    id: string;
    liveChatId: string;
    privacy: 'public' | 'private' | 'unlisted' | string;
    publishedAt: string;
    scheduledEndTime: string;
    scheduledStartTime: string;
    status: 'ready' | 'complete' | string;
    title: string;
    tags: Array<string>;
    defaultLanguage: string;
    defaultAudioLanguage: string;
  }>;
  count: number;
};

Examples

const response = await client.getMonitoredYouTubeBroadcasts();

Select the platform to fetch emotes for

Response Type

type TwitchGetEmotesResponse = {
  status: 'ok' | 'error';
  emotes: {
    userEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
    bttvEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
    ffzEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
    sevenTvEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
  };
};

type YouTubeGetEmotesResponse = {
  status: 'ok' | 'error';
  emotes: {
    userEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
    bttvEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
    sevenTvEmotes: Array<{
      type: string;
      name: string;
      imageUrl: string;
    }>;
  };
};

Examples

const response = await client.getEmotes('twitch');

Fetch persisted or non-persisted variables

Default: true :: ::

Response Type

GetGlobalsResponse.ts

type GetGlobalsResponse = StreamerbotResponse<{
  variables: {
    [key: string]: {
      name: string;
      value: string | number | boolean | null;
      lastWrite: string;
    };
  };
  count: number;
  status: 'ok' | 'error';
}>;

Examples

const response = await client.getGlobals();

type GetGlobalResponse<T, K = string> = StreamerbotResponse<{
  variable: {
    name: K;
    value: T;
    lastWrite: string;
  };
  status: 'ok' | 'error';
}>;

Examples

const response = await client.getGlobals();

Select the platform to fetch globals for

persisted

boolean

Default: true :: ::

Response Type

GetGlobalsResponse.ts

type GetUserGlobalsResponse = StreamerbotResponse<{
  variables: {
    [key: string]: {
      name: string;
      value: string | number | boolean | null;
      lastWrite: string;
      platform: 'twitch' | 'youtube' | 'trovo' | 'kick';
      userId: string;
      userLogin: string;
      userName: string;
    };
  };
  count: number;
  status: 'ok' | 'error';
}>;

Examples

const response = await client.getUserGlobals('twitch');

Select the platform to fetch globals for

userId

string required

Provide the specific user ID to fetch globals for

name

string

Optionally provide a variable name

persisted

boolean

Default: true :: ::

Response Type

type GetUserGlobalResponse = StreamerbotResponse<{
  variables: {
    [key: string]: {
      name: string;
      value: string | number | boolean | null;
      lastWrite: string;
    };
  };
  count: number;
  status: 'ok';
}>;

type GetUserGlobalByNameResponse = StreamerbotResponse<{
  variable: {
    name: string;
    value: string | number | boolean | null;
    lastWrite: string;
  };
  status: 'ok';
}>;

Examples

// Fetch all user global variables for a given user ID
const response = await client.getUserGlobal('twitch', '12345678');

// Fetch a specific user global variable by user ID and variable name
const response = await client.getUserGlobal('twitch', '12345678', 'test');

`sendMessage`

Requires Streamer.bot v0.2.5

Send a chat message to the selected platform

Signature

sendMessage(
  platform: 'twitch' | 'youtube' | 'trovo' | 'kick',
  message: string,
  options?: {
    bot?: boolean;
    internal?: boolean;
    replyId?: string;
    broadcastId?: string;
  }
): Promise<SendMessageResponse>

Parameters

platform

'twitch' | 'youtube' | 'trovo' | 'kick' required

Select the platform to send the message to

message

string required

Enter the content of the message to send

options.bot

boolean

Default: false Send with the bot account? ::
options.internal
boolean
Default: true Send as an Internal message

Useful in combination with the Ignore Internal option on Commands

options.replyId

string

Optional message id to send a reply toCurrently only supported by Twitch

options.broadcastId

string

Optioanl broadcast id to send the message toCurrently only supported by YouTube

Response Type

type SendMessageResponse = StreamerbotResponse<{
  id: string;
  status: 'ok' | 'error';
  error?: string;
}>;

Examples

// Send a message with the Twitch broadcaster account
const response = await client.sendMessage('twitch', 'Hello, world!');

// Send a message with the Twitch bot account
const response = await client.getUserGlobal('twitch', 'Hello, from bot account!', { bot: true });

Select the platform to fetch pronouns forCurrently only supported by Twitch

userLogin

string required

Provide the specific user login to fetch pronouns for

Response Type

export type GetUserPronounsResponse = StreamerbotResponse<{
  status: 'ok';
  userLogin: string;
  pronoun: {
    pronouns: string;
    pronounSubject: string;
    pronounObject: string;
    pronounPossessive: string;
    pronounPronoun: string;
    pronounReflexive: string;
    pronounPastTense: string;
    pronounSubjectLower: string;
    pronounObjectLower: string;
    pronounPossessiveLower: string;
    pronounPronounLower: string;
    pronounReflexiveLower: string;
    pronounPastTenseLower: string;
    pronounCurrentTense: string;
    pronounCurrentTenseLower: string;
    pronounPluralLower: string;
    pronounLastCached: string;
    userFound: boolean;
  };
}>;

Examples

const response = await client.getUserPronouns('twitch', 'whipstickgostop');

Edit this pageorReport an issue

Configuration

Reference of all configuration options available when initializing a Streamer.bot client

Events

All events that can be subscribed to from the Streamer.bot WebSocket Server