Skip to main content

Bot Commands

The Bot Commands view lets operators define global chat commands (available to every Lumio account out of the box) and inspect per-account overrides that accounts have customised on top of those globals. It also supports creating bot commands scoped to a single account.

Where to find it​

Admin sidebar → Bot Commands (/bot-commands). Two tabs: Global Commands and Account Commands.

Quick start​

  1. Open Admin → Bot Commands on the Global tab.
  2. Click Create Global Command.
  3. Fill in the command name (no ! prefix), description, platforms, minimum role, cooldowns, and pick a Response Type: Text, Template, or Automation.
  4. For Text / Template, enter the response text (template placeholders like \{user.name\} are allowed in Template mode). For Automation, paste the target automation UUID.
  5. Click Save. The command is live across all accounts immediately.

Detailed walkthrough​

Global tab​

Lists every command fetched with scope=global. Commands render as rows in a card list, not a table. Each row shows:

  • !name, plus a Global badge and an Enabled: OFF badge when the command is disabled.
  • The description, underneath the name.
  • One outline badge per platform.
  • The minimum role.

Response type and cooldowns are stored on the command but are not surfaced in the row - open the editor to see them.

Row actions (icon buttons):

  • Edit Command (pencil) - opens the command editor pre-filled. Gated on bot-commands:edit.
  • Delete Command (trash) - native confirm ("Are you sure you want to delete the command !{name}?"). Gated on bot-commands:delete.

A Create Global Command button sits above the list, gated on bot-commands:create.

Account tab​

Switches the fetch to scope=account. A search bar filters by account - the typed value is sent as the account_id query parameter. Rows use the same layout as the Global tab, with the owning account name shown alongside each command.

Command editor​

Fields:

  • Command Name - string without leading !.
  • Description - free text.
  • Response Type - one of text, template, automation.
  • Response Text - for text / template.
  • Automation ID - UUID when Response Type is automation. Inline UUID validation ("Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
  • Platforms - multi-select: twitch, youtube, kick, discord.
  • Minimum Role - viewer / moderator / vip / broadcaster (platform-dependent).
  • Global Cooldown (s) and Per-User Cooldown (s) - integer seconds.
  • Enabled - boolean toggle.

Create vs update​

  • Create - POST /api/bot-commands with the full body.
  • Update - PUT /api/bot-commands/\{id\} with the mutated body.
  • Delete - DELETE /api/bot-commands/\{id\} (confirm dialog first).

Account-scoped commands and overrides​

Accounts can override global commands (for example, changing the response text) without forking the command. The override lives in a separate table and is fetched alongside the global when the bot dispatches.

The admin Account Commands tab lists account-scoped commands - it does not render per-command override lists. Overrides are set account-side and inspected through the API:

  • POST /v1/bot-commands/\{id\}/override (GraphQL overrideGlobalCommand) - set or update an override.
  • DELETE /v1/bot-commands/\{id\}/override (GraphQL removeGlobalCommandOverride) - clear the override.
  • adminBotCommandOverrides(commandId) - read every account's override of one global command.

Common scenarios​

  • Ship a new !lurk command to everyone - Create Global Command, Response Type Text, response "\{user.name\} is now lurking", enabled.
  • Quickly disable a misbehaving global - open it in the editor, toggle Enabled off, Save. Accounts won't see it.
  • Spot which accounts customised a command - query adminBotCommandOverrides(commandId) directly; there is no admin UI for it.
  • Wire a command to a complex automation - set Response Type to Automation and paste the UUID from the account's Automation Builder.

Permissions​

ActionPermission
View global / account commandsbot-commands:read
Create a commandbot-commands:create
Edit a commandbot-commands:edit
Delete a commandbot-commands:delete

Dashboard entry requires admin:access. System admins implicitly hold every permission above.

API​

UI actionGraphQLREST
List global commandsadminBotCommands(scope: "global")GET /v1/admin/bot-commands?scope=global
List per-account commandsadminBotCommands(scope: "account", accountId)GET /v1/admin/bot-commands?scope=account&account_id=X
List account overrides for a globaladminBotCommandOverrides(commandId)-
Create global commandadminCreateGlobalCommandPOST /v1/admin/bot-commands
Update commandadminUpdateBotCommandPUT /v1/admin/bot-commands/\{id\}
Delete commandadminDeleteBotCommandDELETE /v1/admin/bot-commands/\{id\}
Account override setoverrideGlobalCommand(commandId, input)POST /v1/bot-commands/\{id\}/override
Account override clearremoveGlobalCommandOverride(commandId)DELETE /v1/bot-commands/\{id\}/override

Tips & gotchas​

  • Automation UUIDs are account-specific. A global command that calls an automation only fires for accounts that own that automation - typically you want Response Type Text or Template for globals.
  • Platforms without the required chat scopes silently skip dispatch; the command stays listed but never runs.
  • Template placeholders follow the bot's template engine.
  • Editing a global with active account overrides leaves the overrides intact - they still apply on top of the new base.