Slack Integration

Overview of Slack Integration (Slack Integration V1 - One Way)

📘

Consider using Slack Integration V2

A newer, two way Slack integration has been released as part of AnswerHub's new Messaging Integration Framework. Learn More about Slack V2 Here A corresponding TEAMS based integration is in development and planned for early 1Q2022 release.

The V1 Slack integration will be sunset in 2022 in favor of the V2 plugin, so if you are making an initial configuration, consider use of the V2 plugin. The two way functionality can be disabled so that the functionality will parallel the V1 plugin if so desired. Communities that currently make use of the V1 plugin, should migrate to V2 function by copying the space to channel and topic to channel mapping and the message templates to an external document (word or email), then disable the V1 plugin, Enable the V2 plugin, reconnect to the desired workspace and copy / paste over the message templates and re-enter the space and topic mapping. Note that the controls for the V2 integration are now consolidated in the 'Integrations' section of the admin.

Only an Admin/Super User can do the following:

1. Enable/disable the slack plugin.
2. Configure the slack plugin with an API Key Token.
3. Set a list of pairs: "Topic - Channel" to send slack messages.
4. Set a list of pairs: "Space - Channel" to send slack messages.

1. Enable the Plugin from the Admin Dashboard

a. Navigate to Plugins > Manage Plugins.
b. Select the Disabled Plugins tab.
c. Enable the slack integration plugin by opening the drop-down and clicking the ENABLE button.

2. Register a New Bot

To register a new bot, use the following URL:
https://.slack.com/services/new/bot

a. Replace "hostname" with the name of your slack workspace.
b. Give the bot a name similar to the name of your AnswerHub site.
c. The system will generate an API token when you create your new bot. Copy it for the next step.
c. To learn how to set up all the different available features for your slack bot, read slack's documentation provided on their site.

🚧

NOTE:

Only certain users can add and edit integrations. Get in touch with a Workspace Owner for help with whatever it is you need to do! If you can't install it on your workspace, you will need to ask a Workspace Admin to approve this app.

3. Enter Your API Token and Map Different Topics and Spaces

Go to /admin/integrations/slack.html in AnswerHub. Enter your API token and enter the default channel for messages along with any topic mappings.

Navigation Tree Access in the Admin Dashboard: Plugins > Slack Integration.

API Key

Paste your copied API key into the text field.

Topic to Channel List:

There are no limits to the number of topics you can pair with channels.

Separate each new topic pairing with a comma.

• Example Pairings: documentation=documentation, help=support, answerhub=general, default=main
• This means, if a (Question/Article/Idea) posts by having topic1 (documentation) as part of the set of tags, then it will publish to the documentation channel. If that post also has topic2 (help) as part of the tags, then it will publish to the support channel too. This implies one post would post in multiple channels at the same time. In case the post doesn’t have topic1 and topic2, then it will default to publish to the main channel.

Space to Channel List:

There are no limits to the number of spaces you can pair with channels.

You can only pair spaces with a channel name by pairing the space name with the channel name.

• Navigate to Content > Site Structure > Spaces and then hover over the spaces to see the ID from the URL in the bottom left-hand corner of the dashboard.

Separate each new space pairing with a comma.

• Example Pairings: Default=general, Help=support
• This means the pair values under Space To Channel List will only send a slack message if there isn’t already a match on the Topic To Channel List setting. If there is no matching on the space ID either, a message will send to the “default” channel, by specifying it in these settings.

TEMPLATES

Use the Template variables at the bottom of your Slack Integration page to create message templates to post in the paired slack channels.

$1 is the Question Author's name
$2 is the Question Title
$3 is the Question URL
$4 is a comma-separated list of the Question Topics
$5 is the site name
$6 is the space name

Message Templates For Questions:

To receive the message in slack, check the box next to Post message for questions?.

• Example Template: $1 has posted a new question with the title: $2 with the topic(s): $4, in _$6_space. To view the new post, click on the following link: $3.

Message Templates for Articles:

To receive the message in slack, check the box next to Post message for articles?.

• Example Template: $1 has posted the article with the title: $2 with the topic(s) $4. To view the new post, click on the following link: $3.

Message Templates for Ideas:

To receive the message in slack, check the box next to Post message for ideas?.

• Example Template:
  $1 has suggested a new idea with the following:
  Idea title: $2 in $6 space
  Idea Topic(s): $ 4
  The site name: $5
  Idea URL: $3

4. Save Your Changes

Save your changes by clicking the SAVE button.

5. Invite the Bot into Your Channel

Before you can send any messages to a channel besides #general, a user needs to invite the bot into that channel.

🚧

Changes between Slack v1 and Slack v2:

You can now include the space name in the messages templates to send to your slack channel by using the variable $6.

You can now pair your space to the channel name by using the space name instead of the space ID.