spreed/docs/commands.md

# Chat commands


## Admin defined commands

For security reasons commands can only be added via the command line. `./occ  talk:command:add --help` gives you a short overview of the required arguments, but they are explained here in more depth:

### "Add command" arguments

Argument | Allowed chars | Description
---|---|---
`cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters)
`name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters)
`script` | * | Actual command that is being ran. The script must be executable by the user of your webserver. See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly.
`response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone
`enabled` | 0-3 |  Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone

### Script parameter

Parameter | Description
---|---
`{ROOM}` | The token of the room the command was used in
`{USER}` | ID of the user that called the command
`{ARGUMENTS}` | Everything the user write after the actual command
`{ARGUMENTS_DOUBLEQUOTE_ESCAPED}` | … but with double quotes `"` escaped.

### Example

* `/path/to/calc.sh`:

    ```
    while test $# -gt 0; do
      case "$1" in
        --help)
          echo "/calc - A Nextcloud Talk chat wrapper for gnome-calculator"
          echo " "
          echo "Simple equations: /calc 3 + 4 * 5"
          echo "Complex equations: /calc sin(3) + 3^3 * sqrt(5)"
          exit 0
          ;;
        *)
          break
          ;;
     esac
    done
    
    set -f
    echo "$@ ="
    echo $(gnome-calculator --solve="$@")
    ```
    
    Please note, that your command should also understand the argument `--help`.
It should return a useful description, the first line is also displayed in a list of all commands when the user just types `/help`.

* `./occ` command used to add the command:

    ```
    ./occ talk:command:add calculator calculator "/path/to/calc.sh \"{ARGUMENTS_DOUBLEQUOTE_ESCAPED}\" {ROOM} {USER}" 1 3
    ```
    
* User input by user `my user id` in the chat of room `index.php/call/4tf349j`:
    
    ```
    /calculator 1 + 2 + 3 + "hello"
    ```

    
* Executed shell command:

    ```
    /path/to/calc.sh "1 + 2 + 3 + \"hello\"" '4tf349j' 'my user id'
    ```

## Aliases

It is also possible to define an alias for a command. This allows e.g. to get the `/help` command also with the german word `/hilfe`.

An alias for the `/calculator` command from above could be created using the following command:

```
./occ talk:command:add calc calculator "alias:calculator" 1 3
```

Now `/calculator 1 + 2 + 3` and `/calc 1 + 2 + 3` result in the same message.

**Note:** The enabled and response flag of the alias are ignored and the flags of the original command will be used and respected.