Interactive Message Buttons¶

Button Options¶

Add message buttons as actions in your integration message attachments.

The following payload gives an example webhook that uses message buttons.

{
  "attachments": [
    {
      "pretext": "This is the attachment pretext.",
      "text": "This is the attachment text.",
      "actions": [
        {
          "name": "Ephemeral Message",
          "integration": {
            "url": "http://127.0.0.1:7357",
            "context": {
              "action": "do_something_ephemeral"
            }
          }
        }, {
          "name": "Update",
          "integration": {
            "url": "http://127.0.0.1:7357",
            "context": {
              "action": "do_something_update"
            }
          }
        }
      ]
    }
  ]
}

The integration can respond with an update to the original post, or with an ephemeral message:

{
  "update": {
    "message": "Updated!"
  },
  "ephemeral_text": "You updated the post!"
}

Below we give a brief description of each parameter to help you customize the webhook post in Mattermost. For more information on message attachments, see our documentation.

Name

Give your action a descriptive name.

URL

The actions are backed by an integration that handles HTTP POST requests when users click the message button. The URL parameter determines where this action is sent to. The request contains an application/json JSON string.

Context

The requests sent to the specified URL contain the user id and any context that was provided in the action definition. A simple example is given below:

{
"user_id": "rd49ehbqyjytddasoownkuqrxe",
"context": {
  "action": "do_something"
  }
}

In most cases, your integration will do one or both of these things:

1. Identifying which action was triggered. For example, a GitHub integration might store something like this in the context:

{
"user_id": "rd49ehbqyjytddasoownkuqrxe",
"context": {
  "repo": "mattermost/mattermost-server"
  "pr": 1234,
  "action": "merge"
  }
}

When the message button is clicked, your integration sends a request to the specified URL with the intention to merge the pull request identified by the context.

2. Authenticating the server. An important property of the context parameter is that it’s kept confidential. Hence, if your integration is not behind a firewall, you could add a token to your context without users ever being able to see it:

{
"user_id": "rd49ehbqyjytddasoownkuqrxe",
"context": {
  "repo": "mattermost/mattermost-server"
  "pr": 1234,
  "action": "merge",
  "token": "somerandomlygeneratedsecret"
  }
}

Then, when your integration receives the request, it can verify that the token matches one that you previously generated and know that the request is legitimately coming from the Mattermost server and not forged.

Depending on the application, integrations can also perform authentication statelessly with cryptographic signatures such as:

{
"user_id": "rd49ehbqyjytddasoownkuqrxe",
"context": {
  "repo": "mattermost/mattermost-server"
  "pr": 1234,
  "action": "merge",
  "signature": "mycryptographicsignature"
  }
}

It’s also possible for integrations to do both of these things with a single token and use something like this as context:

{
"user_id": "rd49ehbqyjytddasoownkuqrxe",
"context": {
  "action_id": "someunguessableactionid"
  }
}

Then, when the integration receives the request, it can act based on the action id.

Tips and Best Practices¶

1. 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.
2. Message attachments allow for rich formatting, but don’t go overboard. Use the least amount of formatting and number of action buttons required for your integration post.
3. To get started, you can use this demo integration to add polling to Mattermost channels via a /poll slash command.

Share Your Integration¶

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

The app directory lists open source integrations developed by the Mattermost community and are available for download, customization and deployment to your private cloud or on-prem infrastructure.

Slack Compatibility¶

Like Slack, actions are specified in an “actions” list within the message attachment. Moreover, your integrations can react with ephemeral messages or message updates similar to Slack.

However, the schema for these objects is different and Mattermost interactive message buttons are not intended to be Slack compatible:

• Slack requires a Slack App and action URL to be pre-configured beforehand. Mattermost instead allows any webhook or slash command to create an interactive message without pre-configuration.
• With Slack, when a user performs an action, the request made to your integration contains information such as channel and team ids. With Mattermost, the request only contains the user id and additional information you specified in your context, which might include team and channel ids if these values are needed by your integration.

Troubleshooting¶