Use Slack and Confluence together

On this page:

How do I install the Confluence Server for Slack app in Confluence?

Head to the Atlassian Marketplace to download the Confluence Server for Slack app.

How do I connect the Confluence Server for Slack app to my Confluence site?

Slack requires that the Confluence instance is accessible through the internet via a secure connection (HTTPS). Therefore, you need to open up your secure port and make sure that the server has a valid certificate.

If that's not an option for you, you are still able to setup a limited connection with Slack by creating a custom Slack app that will give you notifications from Confluence to Slack. See how to create an app below in this page.

As an administrator, you'll now have a "Slack Integration" navigation item under "Confluence administration"

From here, select "Connect Slack Team"

You'll then be taken to Slack's App Directory to install the Confluence Server Slack app. Click the green "Install" button for the Slack app and complete Slack's OAuth process.

Once you complete the OAuth process in Slack, you'll then see a new configuration page for your integration. Scroll to the bottom to see the two fields you need to complete. First, add your Confluence Server web address. Please do not include a trailing / after your web address. Second, you'll want to copy the contents of box #2 back into your Confluence setup.

Paste the credentials into the Confluence configuration on the Confluence Server side. Click save here, and be sure to click "Submit" in your Slack window (screenshot above).

Once the connection has been setup, you'll receive a success notification from Confluence Server in your direct message with Slackbot.

How do I set up a space to post notifications into Slack?

In order to connect to any Slack channels, you must first confirm access to your Slack account. On the Slack integration screen in Confluence (in both Project and Global Admin), you'll see a link to do this under "Connection status" if you haven't done it yet. Clicking this link will take you to a Slack auth link, which will give the app the ability to view your channels.

Once you've completed this step, you should now see "You're accessing Slack as [Your Name]", and should now be able to select private channels from the drop down. Each user who wants to connect their private channels to the Slack integration will need to do this step.

As a Confluence Administrator

In the Applications section of Administration, you'll see "Slack Integration" listed under Integrations. From here, you can connect Confluence spaces to to different slack channels.

Once you've selected a channel, you'll now see the connection to Slack listed below. You will also receive a notification in Slack that Confluence notifications have been set up to appear in the channel.

From the configuration menu in Confluence, you can filter exactly what notifications you want sent to that channel, by subscribing or unsubscribing to Blog post created, Page created, and page updated events.

As a Space Administrator

Space Administrators are able to set up and configure their Slack notifications. In a Confluence space, under Space Tools, you should see a link for the Slack integration. From this page, space administrators can see current Slack channel connections for that space, as well as set up new ones.

How do I set up personal notifications?

The integration allows you to receive some specific personal notifications in Slack via a direct message from the bot.

Go to your Confluence user profile page.
Click the Settings > Slack notifications.
In the next page, choose the options for when you want to be notified and the Slack workspace of your preference.

How do I connect Confluence Server to a direct message or multi party direct message?

Unfortunately, it's not possible to set up Confluence Server notifications into Slack's direct messages or multi party direct messages.
Alternatively we suggest setting up a private channel and configuring notifications to route there.

How do I connect to a different Slack Workspace?

The Confluence Server for Slack app supports the ability to connect to multiple Slack Workspaces, such as in a Slack Enterprise Grid. To do so, on any of the Slack integration pages in Confluence, you should see a dropdown of workspaces at the top. To connect to a new workspace, click this and click "Connect to a new team." Please follow the steps from above to connect your new workspace to this Confluence Server instance.

I use multiple Confluence Server instances or my instances are behind a firewall. How do I connect them to Slack?

The process for setting up additional Confluence Server instances with Slack takes some manual configuration to setup. Please ensure that you follow the below steps perfectly to ensure proper connectivity between your Confluence Server instance and Slack. You can repeat this process multiple times for each additional Confluence Server instance you have.

To get started, first visit https://api.slack.com/apps?new_classic_app=1. Make sure you create the App with classic scopes as Slack has released a new permission model that's not compatible with this App at this moment.

Slash Commands

You can skip this section if your Confluence instance is behind a firewall so that Slack can't reach it.

Slash commands lets users trigger an interaction with your app directly from the message box in Slack.

In your app settings, go to Slash Commands.
Click Create New Command.
Copy the details of this command over, replacing {{url}} with your Confluence Server's URL:
Command name: /confluence_server
Request URL: https://{{url}}/rest/slack/latest/command
Usage hint: account, help

Make sure the Command name is not taken by another Slack app in your workspace.

Once saved, your new slash command should show up in the list.

Now continue to "OAuth & Permissions" under Features.

OAuth & Permissions

First, we'll click "Add New Redirect URL". Set this to http://{{url}}/rest/slack/latest/oauth. Again, replace {{url}} with your Confluence Server's URL. Make sure to click "Save URLs".

Next, scroll down to the Scopes section. Please add the following scopes:

`channels:read`	`channels:write`	`links:read`
`groups:read`	`groups:write`	`links:write`
`im:read`	`mpim:read`	`chat:write:bot`

Double check that you've added all scopes, and hit "Save".

Without all of these scopes, it's possible that the bot will not function correctly. If you're having issues with the bot working later, please reference that you've asked for all required permissions.

Bot Users

Click "Bot Users" in the Features navigation bar and click "Add a Bot User"

You can set the Display name and default username to whatever you'd like (for instance, "Finance Confluence"). Click the green "Add Bot User" button at the bottom.

Event Subscriptions

You can skip this section if your Confluence instance is behind a firewall so that Slack can't reach it.

Click on the "Event Subscriptions" navigation menu item and click the "Enable Events" toggle button.

Add your Request URL https://{{url}}/rest/slack/latest/event and click Change. Please validate that it says "Verified" to ensure your connection between Slack and your Confluence Server instance

Now you can subscribe to the following events under "Workspace Events"

`app_uninstalled`	`channel_archive`	`channel_deleted`	`channel_unarchive`	`group_archive`
`group_deleted`	group`_unarchive`	`link_shared`	`tokens_revoked`

Scroll down to Bot Events and add the following events here:

`member_joined_channel`	`message.channels`	`message.groups`
`message.im`	`message.mpim`

Scroll down to App Unfurl Domains and add your Confluence Server domain.

Validate all of the events have been added and click "Save Changes"

Install the App

You can now install your app to your workspace by clicking "Install App" under settings and "Install App to Workspace"

In the Confluence config screen, click the "Connect to a new Team" menu item. Then click on "advanced" for connection type. You'll need to copy each of the settings from your Slack app configuration into this screen. Once completed, you'll be able to start using your Confluence Server integration.

Can I distribute the Slack App I created to connect my Confluence instance to multiple workspaces?

Yes, if you have followed the steps above to created a custom App.

First, your instance needs to have at least one connection with a workspace using the App credentials. This is required so the integration knows the App's client and secret.

Then, find the installation URL in Slack:

Find your App in Slack API page.
Go to the Manage Distribution under Settings.
Activate distribution with other workspaces. You will need to meet Slack's requirements for that.
Copy the Sharable URL.
Navigate to the shareable URL in a browser. It will trigger an installation flow.
Select the target workspace and proceed.
At this point, if your App and the integration are correctly setup, you should be redirected to the integration configuration page in Confluence, with the new connection already setup for you.

I'm using Data Center. Does this integration work for me?

Yes, this integration is fully compatible with Confluence Data Center.

Which Slash commands does the Confluence Server integration support?

There are the slash commands you can use while interacting the integration:

Slash command	Action
`/confluence_server search <term>`	Search specified term across Confluence pages and blogs
`/confluence_server account`	Show Confluence account to which current Slack user is connected
`/confluence_server help`	Show help information about slash commands

How can I fine-tune the integration?

Various system properties are available that allows you to tune specific parts of the integration, as described in the table below:

System property name	Description	Plugin default value
`slack.client.max.channel.bulk.load`	Maximum number of Slack channels that are fetched at once, used in the administration page. It can affect how Slack rate limits the integration.	`50`
`slack.client.list.all.conversations`	If enabled, channel selector dropdown in configuration page will list all Slack channels for the selected workspace, rather than the user channels. Do not use this is large workspaces but could be useful for small ones.	`false`
`slack.client.pagination.limit`	Maximum number of channels to load if `slack.client.list.all.conversations` is enabled. Each page loads a thousand channels, so a pagination limit of 2 means 2000 channels max. Increasing this value too much will slow down or crash your browser, as it will try to render thousands of entries.	`2`

slack.client.retry.on.connection.failure	OkHttp3 boolean flag to retry if failed to establish a connection. Documentation.	true
slack.client.connect.timeout	OkHttp3 timeout in ms when establishing new connections. Documentation.	3000
slack.client.read.timeout	OkHttp3 timeout in ms while waiting for data in a connection. Documentation.	10000
slack.client.retry.count	Number of times the Slack client retries in case it gets a 5xx response. Backoff delays in seconds are 1, 3, 5, 8, 13, and 30 seconds, respectively.	3
`slack.client.rate.limit.retry.count`	Number of times the Slack client retries in case if gets a 429 HTTP response from Slack. Documentation. By default, Slack will return a `Retry-After` header with a time interval the client will use to delay the next attempt	`3`
`slack.client.thread.pool.size`	Affects how many threads will process Slack notifications but also affects other asynchronous operations in the integration, such as the ability of handling incoming requests from Slack.	`5`
`slack.client.queue.size`	Limits the memory consumed by the integration. For instance, if a big spike in events trigger a large number of notifications at once, if the queue maximum size is reached, new attempts to schedule notifications will fail and those notifications will be dropped. Note that, with a default value of 1000, it would require 1001 or more events happening at basically the same, without giving a change to the queue to be processed. A big bulk edit could reach such limit if the Slack notifications are enabled in that context.	`1000`
`slack.client.cache.expire.seconds`	Time in seconds to expire cached values from Slack requests (channels and user names, for instance). Note that values are cached according to the Slack token, so they are all restricted to the respective Slack user.	`900` (15mi)
`slack.search.max.results`	Maximum number of results returned from a search slash command.	`5`

Some of the system properties and the upper limits they represent, when in a clustered environment, will affect nodes individually. So limits such as queue size will scale according to the number of nodes available in the cluster.

How can I troubleshoot the integration?

Debug logging

You can enable DEBUG level logging in configuration, using the following packages:

com.atlassian.plugins.slack
com.atlassian.confluence.plugins.slack

Connectivity from Slack

If you're having connectivity issues between your instance and Slack, double-check the following:

Slack can reach your instance through a HTTPS-secured URL.
You have properly saved your base URL without a trailing slash in the Slack App configuration.
Make sure the path <baseUrl>/rest/slack/latest/* are whitelisted in your firewall and security filters in place.
Make sure those paths allows "anonymous" requests, since incoming requests from Slack use a different authentication mechanism.
If you're unable to expose your instance, you can still use the integration in notification-only mode, by creating a custom app as described in this page.

You can check the integration is available by making a request to the verification event endpoint. In a bash terminal it can be done with the following command:

curl -X POST \
  https://<confluence-base-url>/rest/slack/latest/event \
  -H 'Content-Type: application/json' \
  -H "X-Slack-Request-Timestamp: $(date +%s)" \
  -H 'X-Slack-Signature: any-value' \
  -d '{"challenge": "boo","type": "url_verification"}'

Failure to submit instance URL in Slack

The "Oops" error when submitting your instance URL is known to happen sometimes just after the App has been removed from a workspace, because Slack tries to reach out to the instance before completing the uninstallation.

This issue tends to fix itself within 15 or so as Slack finishes the process.

Notifications on page updates are not sent

Update notifications are not sent when user unchecks "Notify watchers" checkbox while editing the page.

Is this supported by Atlassian?

Yes, absolutely. This integration is built and maintained by Atlassian. If you need support, visit support.atlassian.com.

Page

Viewport

Confluence