How To Trigger Marketplace Widgets from Commands

A Custom Command can send an action event to an interactive Marketplace Item inside a saved Overlay Builder layout.

Prepare the Widget

  1. Install the widget package from Marketplace.
  2. Open Settings → Overlays → Overlay Builder.
  3. Add a Marketplace Item widget.
  4. Select the installed package and configure its fields.
  5. Save the overlay.
  6. Make sure the saved overlay—or the Master Overlay currently displaying it—is active in your browser source.

The widget must exist in a saved overlay before it appears in Action Builder's target picker.

Create the Command

  1. Open Bot Commands → Commands.
  2. Create a Custom Command such as spin or decide.
  3. Set permissions and cooldowns appropriate for the effect.
  4. Leave the normal response blank if the widget is the complete response.
  5. Under Actions, choose Overlay Widgets → Trigger Marketplace Widget.
  6. Select the saved Marketplace widget.
  7. Enter the widget action documented by its publisher, such as spinWheel.
  8. Add optional payload JSON if the widget supports it.
  9. Save and test the command.

Add Variables to the Payload

Supported command variables can be inserted into payload JSON:

{
  "viewer": "{user}",
  "message": "{message}",
  "source": "chat-command"
}

The exact action name and payload fields belong to the widget package. Use its Marketplace description or publisher documentation rather than guessing.

Control Who Can Trigger It

Use VIP, Moderator, or Broadcaster permission while testing. Add a global cooldown for animations or games that should finish before another viewer starts them.

Common Problems

  • Widget is missing from the picker: Add it to an overlay, save, then reopen the command editor.
  • Nothing happens: Confirm the active overlay contains that exact widget instance.
  • Wrong action runs: Check the publisher's widget-action key, including capitalization.
  • Payload is ignored: Validate the JSON and confirm the widget supports those fields.
  • Viewers spam the effect: Increase the command's global cooldown.
  • Package reports an error: Open Marketplace Package Details and inspect its dependencies and runtime status.