Getting started with Mattermost integrations

Mattermost is well-known as a flexible, open source messaging platform. But what makes it even more useful is its ability to automate connections with bots and webhooks and to link up to external applications. These automations and connections are known as integrations. 

Many integrations are available off-the-shelf through the Integrations Directory. But there are lots of ways to create your own.

For example, webhooks provide lightweight communication between apps in real time and are typically used to send notifications of events. 

Incoming webhooks allow Mattermost to receive data from external apps and share it in channels. To illustrate, let’s say you have support requests coming from a variety of sources. These could all be routed into a channel where your team can discuss them and take the required action.

On the other hand, outgoing webhooks are used to send data out to other apps and to post responses back in a channel. You typically use these in conjunction with slash commands. 

Slash commands begin with a forward slash (i.e., / ) and can be used both for internal automated responses and to send HTTP requests to a web service. For example, you might want to improve the support system so your team can type commands in the channel to record actions or assign or close issues and have those commands fired out to an external app.

In addition, the Mattermost Server exposes a REST API that you can call from more advanced applications. For more information, see our Getting Started guide to integrations.

Now, let’s look at a couple of examples. 

The first shows how to send messages from your Jenkins server to your Mattermost server. The second illustrates how you can have Mattermost send messages to Jenkins.

Jenkins sending messages to Mattermost

Setting up an integration between a Jenkins CI server and Mattermost simply involves installing a plugin on your Jenkins server and opening up a webhook endpoint on your Mattermost server.

To add an incoming webhook on your Mattermost server, go to Main Menu > Integrations > Incoming Webhook > Add Incoming Webhook.

If the menu option for integrations is missing, direct your admin to this guide to enable it. 

You’ll end up with a URL generated for you, ready to send data to and from Jenkins:

Next, install the Mattermost Notification Plugin on your Jenkins server through the Plugin Manager UI:

Now configure the Mattermost webhook endpoint on your Jenkins server.

From the Jenkins dashboard, go to Manage Jenkins > Configure System > Global Mattermost Notifier Settings and paste in the endpoint URL generated by the Mattermost server for the incoming webhook you added.

You’ll need to include the Jenkins build server address for any links back.

Configure Jenkins to send data to Mattermost. The simplest example is to send a test message in a color given as a hex value:

mattermostSend(color: "#2A42EE", message: "Simple test message")

The screenshot below shows an example of a Jenkins Pipeline to build a Simple Java Maven App. The example uses the declarative pipeline approach, but there’s a script embedded to provide more control over when to fire events related to build failure. 

Here’s what’s happening:

1. We send a message, in blue, to Mattermost, informing the channel that the build has started and providing the build name, number, and a link back to it.
2. We start the maven build. This is in the try block so we can catch a failure.
3. On any failure, we catch the exception and set the build result to FAILURE.
4. In the finally block, we use danger (red) and good (green) to send the appropriate failure or success message to Mattermost.

pipeline {
    agent {
        docker {
            image 'maven:3-alpine'
            args '-v /root/.m2:/root/.m2'
        }
    }
    stages {
        stage('Build') {
           steps {  
                script {
                    try {
                        mattermostSend (
                            color: "#2A42EE", 
                            message: "Build STARTED: ${env.JOB_NAME} #${env.BUILD_NUMBER} (<${env.BUILD_URL}|Link to build>)"
                        )                   
                        sh 'mvn -B -DskipTests clean package'
                    } catch(e) {
                        currentBuild.result = "FAILURE"
                    } finally {
                        if(currentBuild.result != "FAILURE") {
                            mattermostSend (
                                color: "danger", 
                                message: "Build FAILED: ${env.JOB_NAME} #${env.BUILD_NUMBER} (<${env.BUILD_URL}|Link to build>)"
                            )
                        } else {
                            mattermostSend (
                                color: "good", 
                                message: "Build SUCCESS: ${env.JOB_NAME} #${env.BUILD_NUMBER} (<${env.BUILD_URL}|Link to build>)"
                            )
                        }                            
                    }           
                }
            }      
        }
    }
}

In the configured channel on your Mattermost server (assuming a successful first run of the build was followed by a failed run), this is what you see:

Note that all senders from external apps are labeled as bots by default to help protect users from phishing attacks.

Mattermost sending messages to Jenkins (and receiving responses)

To send and receive messages between Mattermost and Jenkins, you simply install a plugin on your Mattermost server and set up an API token on your Jenkins server.

The installation instructions for the Mattermost Jenkins plugin are pretty straightforward. But the process has become even simpler with the new plugins feature (currently in beta). Simply go to System Console > Plugins > Jenkins plugin, enable the plugin, and enter your Jenkins URL.

You need to generate an API key to allow Mattermost to work with your Jenkins builds. In Jenkins, click on your username in the top-right corner of the screen, then go to Configure > API Token and add a new token. Keep a copy of the token to use in Mattermost.

Now, connect to Jenkins from a Mattermost channel. The Jenkins plugin provides a range of slash commands that enable interaction with Jenkins jobs. 

A full list of commands can be seen here or by typing the slash command:

/jenkins help

The first command you need to execute to get connected is:

/jenkins connect username API_Token

Then you can start a build with:

/jenkins build mattermost-demo

At this point, you’ll see this:

Wrapping Up

Integrations enable Mattermost to be much more than a chat platform. Here are just a few examples of what you can automate:

• Alerts that are sent when services are down on AWS
• Monitoring a Kubernetes cluster
• Notifications about pull requests from Bitbucket
• Real-time notifications of Cisco config changes 
• Meeting reminders from Google Calendar
• Jira notifications and managing Jira issues from a channel
• Forwarding Microsoft Outlook emails to a channel

As you’ve seen, integrations are a cinch to set up!

Don’t be alarmed if a plugin you’d like is not available in the Integration Directory. Most of the time, what you want can be achieved via a simple webhook or by adding custom slash commands. If you do need to create something more powerful, like a bot, then look at writing your own code that calls the Mattermost REST API. 

The Getting Started guide mentioned earlier is very useful. If you need more help, there’s also a plugin demo on GitHub, which is a great way to learn about creating more advanced integrations.

Have fun!

(Editor’s note: This post was written by Ben Hall, Expert .NET Software Engineer at the United Kingdom Hydrographic Office. If you have any feedback or questions about Getting started with Mattermost integrations, please let us know.)