Use Slack to broadcast event activity from Matrix

This tutorial shows you how to integrate Slack with Matrix, which lets you notify members of your Slack channel about events triggered in Matrix, such as when a page is published live or when the page’s workflow status is changed.

Before you start

For this tutorial, you will require:

A Slack service with a Slack account - using your Slack account, you will create a Slack channel and add an app to this channel.
For more information about Slack’s pricing plans, consult their pricing page. Note also Slack’s Terms of Service and Privacy Policy, as well as their help documentation.
A Matrix system on which to configure a trigger for your Slack notification - your Matrix account type must be system administrator and your user account located within the System management System Administrators user group.

Configuring Slack for integration with Matrix

These procedures document how to prepare Slack for integration with Matrix.

Create a Slack channel

If you have an existing Slack channel through which you want Matrix notifications to be sent, then skip to the next procedure below.

Otherwise, follow Slack’s own instructions on how to signed in to Slack and create a channel.

Add the "Incoming webhooks" app to your Slack channel

Ensure you have signed in to Slack and have accessed the relevant channel.
In your Slack channel, select the cog icon and then Add an app.
In Add apps to #your-slack-channel, select View App Directory.
on the resulting web page, search for the app "Incoming webhooks".
On the resulting web page, select Add configuration.
In the Request to install Incoming webhooks for … message box, enter a reason to request the installation of this app in your Slack channel and select Submit request.
Wait for Slackbot to notify you about when Incoming webhooks has been approved for installation.
Once you receive this notification, return to the Incoming webhooks web page and select Add configuration again.
On the resulting web page, choose your channel from the Choose a channel dropdown, and select btn:Add Incoming webhooks integration]. Keep the resulting page open.

Configure your Matrix trigger for Slack

Ensure you are logged in to your Matrix site in admin mode as a user with the system administrator account type (according to the Before you start section above).
Add a trigger through System management Trigger manager. Read the Adding triggers documentation for more details about adding triggers.
On the Create a new trigger page, specify a Name value of "When a page goes live, send a notification to Slack".
In the Events section, select the Before Status Changed checkbox.
In the Conditions section, add the following conditions and select Save at the lower right:
- Asset Status Being Changed To
- Asset is of type
- Tree Location
Choose the following values for these conditions:
- Asset Status Being Changed To - select Live.
- Asset is of type > Match any one of these types: choose Page and select the Inherit checkbox.
- Tree Location - select the site or part of the site where you want pages going live to trigger the notification.
In the Actions section, choose Call REST Resource and select Save.

In the Call REST Resource section, set the following field values:

METHOD - choose POST.
URL(S) - copy the Webhook URL value from your Incoming webhooks web page in Slack and paste it in the first of these fields in Matrix. Your URL should begin with https://hooks.slack.com/services/….

REQUEST BODY - copy and paste one of the following JSON code snippets into this text field, ensuring that you replace the appropriate values with those to match your scenario:

Simple message:

{
    "username":"Matrix site notification",
    "channel":"#your-slack-channel",
    "icon_emoji":":incoming_envelope:",
    "text":"A new page has been published on your Matrix site:\n%globals_asset_name%\n%globals_asset_url%"
}

Change the username, channel and text values to suit your Matrix site, Slack channel and the message you want to convey in this Slack channel.

Complex (attachment) message:

{
    "username":"Matrix site notification",
    "channel":"#your-slack-channel",
    "icon_emoji":":incoming_envelope:",
    "attachments": [
        {
            "fallback": "A new page has been published on your Matrix site:\n%globals_asset_name%\n%globals_asset_url%",
            "color": "#6D11BA",
            "title": "A new page has been published on your Matrix site:\n%globals_asset_name%\n%globals_asset_url%",
            "actions": [
                {
                    "type": "button",
                    "text": "Read Now :point_right:",
                    "url": "%globals_asset_url%"
                }
            ]
        }
    ]
}

Change the username, channel, fallback and title values to suit your Matrix site, Slack channel and the message you want to convey in this Slack channel.

At the top of the page, change the Status of the trigger to Enabled, which makes the trigger live.

Read more about how to configure additional elements of the request body on the Slack page itself.
( Optional ) Test that the trigger functions correctly by selecting the RUN TEST checkbox.

Select Save to save changes to the trigger.

If you selected the RUN TEST checkbox, you should see a notification appear within the specified channel (i.e. #your-slack-channel above) in Slack. Be aware though that most of the notification’s content will contain empty values, because a real asset (which populates some of the keyword replacement values in the JSON snippet) is not undergoing a status change.

Confirm that the Slack notifications from Matrix are correctly configured

Although you may have selected the RUN TEST checkbox when you saved your trigger (above), you should confirm that the notifications appearing within your Slack channel contain the correct keyword replacement values from Matrix.

Ensure you are logged in to your Matrix site in admin mode as a user with admin access to your site’s asset tree specified in Tree Location (above).
Create a test page or standard age asset within this asset tree.

Access the new page asset’s Details screen (if not already visible), and if necessary, select Edit.
Select Approve and make live from the Change Status field and select the Cascade status change check box.
Select Save at the lower right to save the status change update to the page and observe the notification in your Slack channel. Confirm that this notification contains the correct %globals_asset_name% and %globals_asset_url% keyword replacement values.

Help Center

Menu