Custom Widget Commands

Custom widget commands allow you to implement unique chat interactions defined directly within a specific widget. Because these commands are contained entirely within the widget, they operate independently of the Chatters module and will not appear in the Chatters → Commands list.

Implementation

You can create custom command behavior using the widget editor through two primary methods: AI generation or manual coding.

AI-Assisted Implementation

The AI generator can write the full logic for your custom commands based on a text description.

1. Describe the behavior: In the editor, describe the command and interaction you want (up to 400 characters). You can include style hints, such as “make the background glassy.”
2. Generate: The AI will write the complete widget, including the markup, styles, behavior, and a settings schema.
3. Refine: Use the AI assist panel to iterate on your command by providing further instructions (e.g., “add a combo counter”).

Note: AI generation is limited to 10 per hour and consumes your channel’s daily AI token allowance (Affiliate: 25,000 / Partner: 100,000 / Partner+: 250,000 tokens; unavailable on Free).

Manual Development

For precise control, you can hand-write your commands using vanilla code. All custom widgets must be self-contained; external scripts are not permitted. A standard widget is composed of three elements:

<!-- Markup -->
<div id="widget-container">
  <!-- Command interactions occur here -->
</div>

<style>
/* Styles */
#widget-container {
  /* Your CSS here */
}
</style>

<script>
/* Behavior */
// Your vanilla JavaScript command logic here
</script>

Defining Widget Fields

To define configurable fields for your widget (such as accent colors, font sizes, or specific command triggers), you must include a settings schema. While the AI generator creates this schema automatically, manual widgets use it to define the parameters available in the widget editor. These fields allow users to customize the widget’s appearance and behavior without changing the core code.

Restricting Command Access

To ensure that custom widget actions are only executed by authorized personnel, you can configure the widget to respond only to commands sent by specific roles. This allows you to gate specialized functionality to high-level users.

The following roles can be used to restrict command execution:

Role	Description
broadcaster	The channel owner. The broadcaster typically bypasses all permission checks.
lead mod	A high-level moderator authorized to manage advanced settings.
mod	Users with moderator status.

Code Example: Handling Chat Events and Roles

To implement custom commands, use the widget’s real-time WebSocket runtime to listen for chat events. You can then check the role of the user who sent the message to verify permissions.

<script>
/**
 * Example: Handling a custom chat command via the WebSocket runtime
 * and restricting access to specific roles.
 */

// Listen for chat events through the WebSocket runtime
widget.on('chat-event', (event) => {

  // Check if the incoming message is a command
  if (event.isCommand) {

    // Retrieve the role of the user who sent the command
    const userRole = event.user.role;

    // Verify if the user has the required permissions
    // Allowed roles: 'broadcaster', 'lead mod', or 'mod'
    const isAuthorized =
      userRole === 'broadcaster' ||
      userRole === 'lead mod' ||
      userRole === 'mod';

    if (isAuthorized) {
      // Execute the specific command logic
      handleCommand(event.commandName);
    } else {
      console.log("Unauthorized: User does not have permission to use this command.");
    }
  }
});

function handleCommand(command) {
  // Logic for your specific command interaction goes here
  console.log(`Executing custom command: ${command}`);
}
</script>