Custom command

Requirements and availability

Use the matching SheevChat version.

Picker contexts: command.

Behavior

Match !name or configured aliases; check enabled status, platform, authority, user/global cooldown and configured response/action output. Built-in triggers take precedence over custom commands, then Marketplace commands. Send the configured response before actions. Custom action failures log and continue; a handler returning without a throw is not proof of an external side effect. Broadcaster actors bypass user/global command cooldowns; these cooldowns persist and are scoped per platform.

Configure in the app

Open: Bot → Commands → + New

Before opening a new editor, optionally choose + New Category in the relevant Bot tab, enter Category name and click Save. In the editor choose that Category, or leave Uncategorized. Categories organize items; they do not filter stream categories or events.

Initial fields

Command name

Enter the trigger name; the editor already displays !.

Category

Existing category or Uncategorized.

Enable command

On by default.

Steps

1. Open Bot, then Commands. Create an optional category before clicking + New.
2. Fill Command name, Category and Enable command.
3. Open When. Add optional Aliases with +. Choose Who can use it (default Anyone); set User cooldown (sec) and Global cooldown (sec), both default 5.
4. Open Where. Set Active on platforms deliberately; all four platform toggles default on, but connections and platform capabilities still apply.
5. Open Do. Enter Response, or leave it blank for actions only. Choose Response style (default Send normal message). The response sends before Advanced Actions.
6. Open Do (for commands also expand Advanced Actions). Choose an action category and action, then click Add action; alternatively search for its exact label. Expand its card and fill the documented fields using real resource pickers. Repeat for every action. Use Move action up / Move action down to set execution order. Actions run sequentially; adding several does not create parallel execution.
7. Click Create Command, or Save Changes when editing.
8. Save, reopen and verify the persisted fields and action order. Test only when the effects are intended: chat, audio, ads and external app actions can affect connected services. A synthetic test does not establish that a real incoming event or platform permission works. Confirm a real eligible event separately during live UAT.

Contract details

Fields

[
  "name",
  "aliases",
  "platforms",
  "requiredAuthority",
  "cooldownSec",
  "globalCooldownSec",
  "response",
  "responseReplyMode",
  "actions"
]

Defaults

{
  "requiredAuthority": "anyone",
  "cooldownSec": 5,
  "globalCooldownSec": 5,
  "responseReplyMode": "normal",
  "enabled": true,
  "platforms": {
    "twitch": true,
    "youtube": true,
    "kick": true,
    "tiktok": true
  }
}

Limits

{
  "nameCharacters": 32,
  "aliases": 20,
  "actions": 25,
  "responseCharacters": 4000,
  "cooldownSeconds": 3600
}

Identity

Incoming command sender, first-argument target and actor; synthetic automation actors differ from viewers.

Authority Levels

{
  "anyone": 0,
  "follower": 1,
  "subscriber": 2,
  "vip": 3,
  "moderator": 4,
  "super_mod": 5,
  "broadcaster": 6
}

Picker Rule

For command/pad, the action picker exposes all nonhidden actions regardless of declared contexts. Runtime requirements still apply.

Examples

Illustrative configuration; replace fixture resources in the editor. This is not an import file.

{
  "name": "hello",
  "response": "Hello {user}!"
}

Source and verification

Source-reviewed for 2.8.0. Connected-service validation remains subject to release UAT.

• server.js — handleCustomCommand / handleBotCommand
• src/features/custom-commands.js — handleCustomCommand / handleBotCommand
• src/features/command-authority.js — handleCustomCommand / handleBotCommand

Source revision: 472fb34b484eeef0b663d28cacb628a7b9f14ff1