Configuration

After adding the extension to your channel, you have to configure it to use it.

When opening the configuration screen, you should see a few components after the loading is finished.

Preview & Editor

Here you can set the different categories and events the extension should handle for you. Switching the “edit” mode allows you to disable or enable adding new categories and events. As long as you are connected to the internet and the server, changes are saved automatically. Keep in mind that updating the configuration resets all event limits and locks to their default.

Categories

You need at least one Category before adding any events. You can use categories to sort events by type, for example, one for sounds, one for visual effects, etc.

Each category ID must be unique.

Controls for adding events, editing, moving and deleting the category are shown below the category name.

Events

Adding an event to a category gives a bunch of options.

  • Event ID: The event ID is used later in the WebSocket client (for example, your streaming broadcasting software), to identify the events. It should be unique, and it should only contain the characters a-z, A-Z, 0-9, _ and -.
  • Display Name (Optional): This is showed to the users in the extension. You can use any character here, including emojis. Without it, the display name is the same as the event id.
  • Description (Optional): A short description shown when opening the event.
  • Duration: How long the event takes to execute in seconds. While executing, no other event can be sent (besides limitations). For example, if you want to play a sound when executing the event, you can set the duration to the duration of the sound.
  • Bits Amount (Optional): How many bits for sending the event. This requires activated bits capabilities.
  • Write in Chat: Whether a message should be written in chat by the extension when someone redeems an event, including the user name and bits amount (if any).
  • Locked: Whether the event is locked by default. This can be used, for example, to lock events from the start. You can then unlock them via your WebSocket client, if you wish so (for example, automatically as a result of executing other events.)

Further advanced options are available:

  • Limit (Optional): How often the event can be sent before it is automatically locked (besides limitations). -1 means the event can be sent unlimited times.
  • Hide when locked: Hides the event from viewers when locked.
  • Use custom redeem response: Enable this if you want to send a custom response to the viewer. Requires setup in your WebSocket client to work properly.

After adding an event, you can hover over it in the list to adjust it. Editing the event also allows you to change it to another category.

You can also send a test event to your streaming software, as long as it’s properly connected to the server. Sending test events work regardless of whether the event is locked, limited or sending is currently blocked by the streamer.

Colors

Here you can individualize the colors of the extension, to make it fit your channel. Remember to save after you are done. You can always reset the colors to their default.

Secret, Exports and Setups

The secret is required for sending commands from the WebSocket client to the server. You should keep it hidden at all times. Should you accidentally leak it, you can request a new one. Keep in mind this requires updating the secret you use for your WebSocket client.

Backup

When done with the configuration, it is recommended to make a local backup of all the settings. For exporting, you can copy the “Data” string and save it to a file. To import an existing backup, paste the backup string into the text input.

Streamer.bot

This is for setting up with Streamer.bot. Streamer.bot acts as a middleman between the extension and whatever other software you use (like OBS). Thus it offers more flexibility than connecting to OBS or any other streaming software directly. Sadly, it doesn’t support imports from generated code yet, so it requires more manual setup time.

Setup

  1. First, make sure Streamer.bot is setup correctly. Refer to their docs for more information, for example, to setup with OBS.

After importing, you still need to create the necessary event actions for each event defined in the config. For example, if you got an event with ID “test”, you need to create an action named “Event_test”, that is going to be executed when the event “test” is redeemed.

  1. Create two persisted global variables:

    • StreamerSocketActive with value False (check “Auto Type”).
    • StreamerSocketSecret with the value being your secret.

  2. Import the following Streamer.bot code:

Streamer.bot code for StreamSocket Events

  1. Connect Streamer.bot with the server. Go to the tab Server/Clients -> WebSocket Clients, right click and add a new Websocket client with the info given in the setup form of the configuration. You should enable auto connect and reconnect.

  2. Manually setup the actions for each event. If you have an event with id “example_id”, create an action “Event_example_id” (Assuming you didn’t change or disable the prefix).

  3. Activate the extension by triggering the “Extension Enable” action.

After adding all the required actions, make sure to test them thoroughly. You can use the “test event” buttons in the config to check whether they execute successfully when you are connected to the server with your streaming software.

Custom

If any of the options provided aren’t sufficient, you can always implement your own WebSocket client that connects to the API.

  1. Use a package like ws to create the client. Connect to the address provided in the API documentation with “custom” as the app_source.
  2. Every message you send requires the secret given to you in the configuration as a parameter of the data object.
  3. After connection, you will receive a request_connection_check. Reply with a JSON object that follows the response_connection_check schema. If you don’t reply in time, you will be disconnected.
  4. To activate the extension for viewers, send a notification_status_change with the corresponding values. Notifications do not receive a response. Remember to also update a state variable with the current status for the response_connection_check.
  5. Events are received with the notification_event message. The message might also include additional information, like about the user who sent the event.
  6. Any other message types found in the API are optional and can be used to further enhance event behavior, like unlocking or locking events under certain conditions.