Skip to content

[Draft] MBCS - Specification Version 1.0

This is the unofficial standard on how to define and process commands of bots for the Matrix Protocol.

Responsible for evaluating compliance with this specification are project maintainers themselves.
If they think of their project to be compliant, they can add this badge to their documentation and/or README(s):

Matrix Bot Command Standard Compliance
(CODE)
(Feel free to modify the badge as needed)

To better explain the details, we use the following example statement from Draupnir as reference:

Definition: 

!dp list create <shortcode> <alias localpart>

Usage: 

!dp list create mylist local-alias

Components

In the following, the different components of a statement are listed and explained.
All components should be separated from each other by a single whitespace.

Prefix

The prefix is the first part of the statement, which identifies the recipient.
This prefix helps a bot identify which statements he has to respond to and which to ignore.

It shall always have a leading exclamation mark, followed by a minimum of two and a maximum of ten letters and digits.
A prefix shall be considered case-insensitive.

RegEx: ^![a-z0-9]{2,10}$
Example:

  • !dp (see example)
  • !botv3
  • !longprefix

Command

The command is the part of the statement that indicates what action to execute.
Statements may contain one or more commands, located right after the prefix.
For the exception of a statement without a command, see

It shall consist of a minimum of one and a maximum of twenty letters and digits.
A command shall be considered case-insensitive.

(In the case of a statement without any command, so only the prefix itself, the command help shall be implicitly assumed.)

RegEx: ^[a-z0-9]{1,20}$
Examples:

Command Chain

A command chain is the combination of multiple commands in a single statement.
They should be separated by a single whitespace.

Example:

  • list create (see example)
  • config add
  • status update

Arguments

A command or command chain may have one or more parameters, here called arguments.
They shall be considered case-sensitive.
This standard does not define valid characters for arguments, as you may pass anything that can be processed by the Matrix protocol, the homeserver and the bot logic.

Multiple arguments shall be separated by a single whitespace. If an argument contains one or more whitespaces, surround the argument with single quotation marks.

Examples:

  • mylist local-alias (see example)
  • !GKPWoymMiVrWlSLhud:matrix.org
  • 'example argument'

Processing

Whitespace Handling

Before every processing step of a statement, leading and trailing whitespace shall be removed (trimmed).
(Whitespace visualized as _)

  1. __!dp__list___create_mylist__local-alias_ shall be processed as
    !dp__list___create_mylist__local-alias
  2. __list___create_mylist__local-alias shall be processed as
    list___create_mylist__local-alias
  3. ___create_mylist__local-alias shall be processed as
    create_mylist__local-alias
  4. _mylist__local-alias shall be processed as
    mylist__local-alias

Case Handling

Before every processing step and after the Whitespace Handling, the input shall be converted to lowercase, unless processing arguments (the only case-sensitive statement component).

That way the processor does not have to distinguish between e.g. the prefixes !dp, !Dp, !dP and !DP.

Statement Recognition

A statement received by the bot shall only be processed if the trimmed statement...

In all other cases, the message shall not be further processed.

Argument Handling

All arguments of a command shall be trimmed (see Whitespace Handling) and converted into a list of strings.
The logic for a command shall receive a list of strings from the processor, filled with the trimmed arguments or empty if no arguments passed.

Help pages

Unexpected input from the user shall never be ignored, instead the most relevant help page shall be returned to the user.
The prefix without a command and every command in the command chain shall provide a help page.
The help page to a command shall be requestable with the input <command> help or by omitting following commands and arguments like <command>.

The following list shows a recommended help page fall-back logic based on the example statement:

  • !dp !dp help
  • !dp <unknown_command> !dp help
  • !dp list !dp list help
  • !dp list <unknown_subcommand> !dp list help
  • !dp list create !dp list create help
  • !dp list create <unexpected_argument(s)> !dp list create help

Bot Self-Disclosure

To allow the end user to see active bots in a room and which bots he can interact with, there's the general bot self-disclosure trigger statement:

!bots

This command may be answered by any bot listening with the following information:

  • Name: the name of the bot
  • Author: the author of the bot
  • Version: the currently running version of the bot
  • 'About' Link: a URL to a web page with more information about the bot, preferably Git repos (GitHub, GitLab, etc.)
  • Interaction Notice: an indicator wether a standard user (moderators/admins excluded) is allowed to interact with the bot (for example: 'Yes' / 'No')

Comments