slash_register

Register slash commands that your connection will answer. Bots use this to add commands such as /weather. When someone runs one, the server forwards the call to your connection and you reply with slash_response.

Request

{
  "cmd": "slash_register",
  "commands": [
    {
      "name": "weather",
      "description": "Show the weather for a city",
      "options": [
        {
          "name": "city",
          "description": "City name",
          "type": "str"
        },
        {
          "name": "units",
          "description": "Temperature units",
          "type": "enum",
          "choices": ["metric", "imperial"],
          "required": false
        }
      ],
      "ephemeral": false
    }
  ]
}

Field	Type	Required	Description
`commands`	array of objects	Yes	The full set of commands for this connection. At least one. Names must be unique within the array.

Each command:

Field	Type	Required	Description
`name`	string	Yes	Command name, without the `/`. Can’t be blank.
`description`	string	Yes	Shown in the command picker. Can’t be blank.
`options`	array	No	Arguments the command takes. Defaults to `[]`. Option names must be unique.
`ephemeral`	boolean	No	If `true`, replies are shown only to the person who ran the command and aren’t saved. Defaults to `false`.
`whitelistRoles`	array of strings	No	Only users with at least one of these roles can see and run the command.
`blacklistRoles`	array of strings	No	Users with any of these roles can’t see or run the command.
`permission`	string	No	Only users with this permission, such as `manage_messages`, can see and run the command. It isn’t shown in `slash_list` or `slash_add`.

Each option:

Field	Type	Required	Description
`name`	string	Yes	Argument name. Can’t be blank.
`description`	string	Yes	Shown in the command picker. Can’t be blank.
`type`	string	Yes	One of the types below.
`required`	boolean	No	Defaults to `true`.
`choices`	array of strings	For `enum`	Allowed values. Required and non-empty for `enum`.

`type`	Value in `slash_call` `args`
`str`	Any string.
`int`	A whole number.
`float`	Any number.
`bool`	`true` or `false`.
`enum`	One of the `choices` strings.
`user`	A username string. The server doesn’t check that the user exists.

Registration rules

Each request replaces everything this connection registered before. To add a command, send the whole list again.
Commands belong to the connection, not the account. They’re removed when the connection closes, and other connections on the same account don’t share them.
Two connections can register the same name. Callers then have to choose one by passing username to slash_call. The server’s built-in commands count too, so avoid their names.

Response

{
  "cmd": "slash_register",
  "val": "1 commands registered successfully"
}

Every authenticated connection, including yours, then receives broadcasts:

slash_remove, only if this request dropped commands you had registered before. It lists the dropped definitions.
slash_add, listing every command in this request.

{
  "cmd": "slash_add",
  "commands": [
    {
      "name": "weather",
      "description": "Show the weather for a city",
      "options": [
        { "name": "city", "description": "City name", "type": "str", "required": true, "choices": null },
        {
          "name": "units",
          "description": "Temperature units",
          "type": "enum",
          "choices": ["metric", "imperial"],
          "required": false
        }
      ],
      "whitelistRoles": null,
      "blacklistRoles": null,
      "ephemeral": false,
      "registeredBy": "weatherbot"
    }
  ]
}

Definitions come back with defaults filled in. registeredBy is the username of the registering account. When your connection closes, everyone receives slash_remove for its commands.

Permissions

Any authenticated member can register commands. It is blocked while you are timed out.

Errors

All schema errors start with Invalid command schema: .

`val`	When
`Invalid command schema: name and description must be non-empty strings`	A command’s `name` or `description` is missing or blank.
`Invalid command schema: /<name> options must be a list`	`options` isn’t an array.
`Invalid command schema: /<name> has invalid options`	An option isn’t an object, has a blank `name` or `description`, has an unknown `type`, a non-boolean `required`, non-string `choices`, or is an `enum` without `choices`.
`Invalid command schema: /<name> has duplicate option '<option>'`	Two options share a name.
`Invalid command schema: /<name> whitelistRoles must be a list of strings`	`whitelistRoles` isn’t an array of strings. The same message is used for `blacklistRoles`.
`Invalid command schema: /<name> ephemeral must be a boolean`	`ephemeral` isn’t a boolean.
`Invalid command schema: duplicate command '<name>'`	Two commands in the request share a name.
Validation message	`commands` is missing, empty, or holds a non-object, for example `commands: Expected length at least 1`.

If any command is invalid, nothing changes.