Slash Commands¶

Built-in Commands¶

Each Mattermost installation comes with some built-in slash commands that are ready to use. These commands are listed below:

Enabling Custom Commands¶

Custom slash commands are off by default. The feature can be enabled by the system administrator only. If you are the system administrator you can enable them by doing the following:

1. Login to your Mattermost team account that has the system administrator role.
2. Navigate to System Console > Integrations > Custom Integrations.
3. Enable slash commands by setting the Enable Custom Slash Commands option to true.
4. (Optional) Configure the Enable integrations to override usernames option to allow custom slash commands to post under any name. If not enabled, the username of the user who activated the command will be used.
5. (Optional) Configure the Enable integrations to override profile picture icons option to allow custom slash commands to post using any icon. If not enabled, the icon of the user who activated the command will be used.
6. (Optional) Configure the Restrict managing integrations to Admins option to allow only system and team admins to create slash commands.
7. Save your changes.

Set Up a Custom Command¶

Once slash commands are enabled, you will be able to set some up through the Mattermost UI. You can do so by following these steps:

1. Login to your Mattermost team site and go to Main Menu > Integrations > Slash Commands.
2. Click Add a new command, and select your options.

1. Fill in Command Trigger Word, this will be the word that is your command. (Note: The trigger word must be unique, and cannot contain any spaces).
2. Enter a Request URL that will be the endpoint Mattermost hits to reach your external application.
3. Select an HTTP Request Method from the dropdown.
4. (Optional) Type in a Response Username that will be used with any messages your command responds with.
5. (Optional) Enter the URL to a Reponse Icon that will be used with any messages your command responds with.
6. (Optional) Check the Show this command in the autocomplete list. to let users autocomplete your command.
7. (Optional) Fill in an Autocomplete Hint to let users know about possible arguments to your command.
8. (Optional) Add an Autocomplete Description to help users understand your command.
9. (Optional) Type in a Descriptive Label to provide a bit more information about your command.

3. Click Add to add your command to the system.
4. Your new slash command will be displayed with a Token that your external application should use to verify the request came from Mattermost.

Creating Integrations with Commands¶

If you’d like to build your own integration that uses slash commands, you can follow these general guidelines:

1. In the programming language of your choice, write your integration to perform what you had in mind.

1. Your integration should have a function for receiving HTTP POSTs or GETs from Mattermost that look like this example:

Content-Length: 244
User-Agent: Go 1.1 package http
Host: localhost:5000
Accept: application/json
Content-Type: application/x-www-form-urlencoded

channel_id=cniah6qa73bjjjan6mzn11f4ie&
channel_name=town-square&
command=/somecommand&
response_url=not+supported+yet&
team_domain=someteam&
team_id=rdc9bgriktyx9p4kowh3dmgqyc&
text=hello+world&
token=xr3j5x3p4pfk7kk6ck7b4e6ghh&
user_id=c3a4cqe3dfy6dgopqt8ai3hydh&
user_name=somename

2. Your integration must have a configurable MATTERMOST_TOKEN variable that is the Token given to you when you set up the custom command in Mattermost as described in the previous section. This configurable MATTERMOST_TOKEN must match the token in the request body so your application can be sure the request came from Mattermost
3. If you want your integration to post a message back to the same channel, it can respond to the HTTP POST request from Mattermost with a JSON response body similar to this example:

{
  "response_type": "in_channel",
  "text": "This is some response text.",
  "username": "robot",
  "icon_url": "https://www.mattermost.org/wp-content/uploads/2016/04/icon.png"
}

• Change response_type to “ephemeral” to have the message appear temporarily and only display to the user who activated the command.
• Use the field goto_location with a URL as the value to redirect the user of the command to a webpage.
• Use the fields username and icon_url to set the username and icon for the message.

2. Set up your integration running on Heroku, an AWS server, or a server of your own to start using your application from within Mattermost

Additional Notes:

1. As mentioned previously, markdown can be used to create richly formatted responses, for example: {"text": "# A Header\nThe _text_ below **the** header."} creates a messages with a header, a carriage return, italicized text for “text” and bold text for “the”.
2. Including @username will trigger a mention notification for the person with the specified username, and channels can be mentioned by including @channel or <!channel>. For example: {"text": "<!channel> this is a notification"} would create a message that mentions @channel
3. If the text in a response is longer than 4000 characters, the message is split into multiple consecutive posts, each within the 4000 character limit.

Slack Compatibility¶

As mentioned above, Mattermost makes it easy to take integrations written for Slack’s proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported:

1. The HTTP POST and GET request body is formatted the same as Slack’s, which means your Slack integration’s receiving function should not need to change at all to be compatible with Mattermost
2. JSON responses designed for Slack using <> to note the need to hyperlink a URL, such as {"text": "<http://www.mattermost.com/>"}, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack
3. Similarly, responses designed for Slack using | within a <> to define linked text, such as {"text": "Click <http://www.mattermost.com/|here> for a link."}, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack