Edit on GitHub

Slash commands at Mattermost

Slash commands are messages that begin with / and trigger an HTTP request to a web service that can in turn post one or more messages in response.

Slash commands have an additional feature, autocomplete, that displays a list of possible commands based on what has been typed in the message box. Typing / in an empty message box will display a list of all slash commands. As the slash command is typed in the message box, autocomplete will also display possible arguments and flags for the command.

Unlike outgoing webhooks, slash commands work in private channels and direct messages in addition to public channels, and can be configured to auto-complete when typing. Mattermost includes a number of built-in slash commands. You can also create custom slash commands.

Tips and best practices

Slash commands are designed to easily allow you to post messages. For other actions such as channel creation, you must also use the Mattermost APIs.
Posts size is limited to 16383 characters for servers running Mattermost Server v5.0 or later. Use the extra_responses field to reply to a triggered slash command with more than one post.
You can restrict who can create slash commands in System Console > Integrations > Integration Management.
Mattermost outgoing webhooks are Slack-compatible. You can copy-and-paste code used for a Slack outgoing webhook to create Mattermost integrations. Mattermost automatically translates Slack’s proprietary JSON payload format.
The external application may be written in any programming language. It needs to provide a URL which receives the request sent by your Mattermost Server and responds with in the required JSON format.

FAQ

How do I debug slash commands?

To debug slash commands in System Console > Logs, set System Console > Logging > Enable Webhook Debugging to true and set System Console > Logging > Console Log Level to DEBUG.

How do I send multiple responses from a slash command?

You can send multiple responses with an extra_responses parameter as follows.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 696

{
    "response_type": "in_channel",
    "text": "\n#### Test results for July 27th, 2017\n@channel here are the requested test results.\n\n| Component  | Tests Run   | Tests Failed                                   |\n| ---------- | ----------- | ---------------------------------------------- |\n| Server     | 948         | ✅ 0                           |\n| Web Client | 123         | ⚠️ 2 [(see details)](http://linktologs) |\n| iOS Client | 78          | ⚠️ 3 [(see details)](http://linktologs) |\n\t\t      ",
    "username": "test-automation",
    "icon_url": "https://www.mattermost.org/wp-content/uploads/2016/04/icon.png",
    "props": {
        "test_data": {
            "ios": 78,
            "server": 948,
            "web": 123
        }
    },
    "extra_responses": [
       {
         "text": "message 2",
         "username": "test-automation"
       },
       {
         "text": "message 3",
         "username": "test-automation"
       }
     ]
}

What if my slash command takes time to build a response?

Reply immediately with an ephemeral message to confirm response of the command, and then use the response_url to send up to five additional messages within a 30-minute time period from the original command invocation.

Why does my slash command fail to connect to `localhost`?

By default, Mattermost prohibits outgoing connections that resolve to certain common IP ranges, including the loopback (127.0.0.0/8) and various private-use subnets.

During development, you may override this behaviour by setting ServiceSettings.AllowedUntrustedInternalConnections to "127.0.0.0/8" in your config.json or via System Console > Advanced > Developer. See the configuration settings documentation for more details.

Should I configure my slash command to use `POST` or `GET`?

Best practice suggests using GET only if a request is considered idempotent. This means that the request can be repeated safely and can be expected to return the same response for a given input. Some servers hosting your slash command may also impose a limit to the amount of data passed through the query string of a GET request.

Ultimately, however, the choice is yours. If in doubt, configure your slash command to use a POST request.

Why does my slash command always fail with `returned an empty response`?

If you are emitting the Content-Type: application/json header, your body must be valid JSON. Any JSON decoding failure will result in this error message.

Also, you must provide a response_type. Mattermost does not assume a default if this field is missing.

Why does my slash command print the JSON data instead of formatting it?

Ensure you are emitting the Content-Type: application/json header, otherwise your body will be treated as plain text and posted as such.

Are slash commands Slack-compatible?

See the Slack compatibility page.

How do I use Bot Accounts to reply to slash commands?

If you are developing an integration

Set up a Personal Access Token for the Bot Account you want to reply with.
Use the REST API to create a post with the Access Token.

If you are developing a plugin

Use CreatePost plugin API. Make sure to set the UserId of the post to the UserId of the Bot Account. If you want to create an ephemeral post, use SendEphemeralPost plugin API instead.

Troubleshoot slash commands

Join the Mattermost user community for help troubleshooting your slash command.

If you’ve built an integration for Mattermost, please consider sharing your work in our Marketplace.

The Marketplace lists open source integrations developed by the Mattermost community and are available for download, customization, and deployment to your private cloud or self-hosted infrastructure.