### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [July 24, 2017, 4:45pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/1 "2017-07-24T16:45:28Z")
This #howto describes how to setup the Slack provider included in `discourse-chat-integration`.
It allows posting notifications to Slack, managing rules using Slash Commands, and posting transcripts back to Discourse. Slash command instructions can be found by typing `/discourse help`. Transcript can be created using the context menus on Slack posts.
# Install
If you haven’t already, install the [discourse-chat-integration](https://meta.discourse.org/t/chatroom-integration-plugin-discourse-chat-integration/66522) plugin, and make sure its enabled via the `chat integration enabled` site setting.
# Setup Slack
1. Head over to [Slack API: Applications | Slack](https://api.slack.com/apps) and create a new app. If you’re not already logged in, you’ll be prompted to do so. (you may need to click on this link again, as it doesn’t seem to redirect after login ☹ )
2. Click Create New App
3. Choose a name (can be anything), and select the Slack Team you want it to be a part of
4. In the left-hand menu, under “Features”, click “OAuth & Permissions”.
5. Scroll down to “Scopes / Bot Token Scopes”, and add each of these to enable the plugin to post messages to your Slack workspace:
> [@](#):
>
> ### For slash commands and transcript posting (If you don’t need this, skip this block)
>
> 1. Add the following scopes under “Scopes / Bot Token Scopes”
>
> 2. On the left-hand menu, under “Features”, go to the Slash Commands page. Click Create New Command
>
> 3. Save
>
> 4. Go to the Interactivity & Shortcuts page, enable the Interactivity section by switching it to On and enter this url under “Request URL”
>
> 5. Save Changes
>
> 6. Go to the Interactivity & Shortcuts page, click Create new Shortcut, choose “On messages”, and click Next. Enter these details:
1. Go to the Settings \> Install App page, click `Install to Workspace`, and authorise the app with your team
2. Copy the `Bot User OAuth Token`, and paste it into your Discourse site settings under `chat_integration_slack_access_token`
3. Go to the Basic Information page, copy the `Verification Token`, and paste it into your Discourse site settings under `chat_integration_slack_incoming_webhook_token`
4. At the bottom of the Basic Information page, you can set your bot’s icon, name and description.
5. Setup some “Rules” for your channels, according to the [discourse-chat-integration](https://meta.discourse.org/t/chatroom-integration-plugin-discourse-chat-integration/66522) instructions, or alternatively use the slash commands within a channel to get started.
6. Add the Discourse bot user to the channels you want it to be able to post to:
> [@](#):
>
> ## Upgrading to ‘Granular Scopes’
>
> If you set up your integration a while ago, you may need to upgrade to Slack’s “Granular Scopes” for things to work as described above.
>
> > **Instructions**
> >
> > 1. Go to [Slack API: Applications | Slack](https://api.slack.com/apps) and choose your Discourse integration app
> >
> > 2. On the left, choose “Update to Granular Scopes”
> >
> > 3. For “Bot Token Scopes”, select `chat:write` and `chat:write.customize`. If you’re using slash commands and/or transcript posting, also select `users:read`, `channels:history`, `groups:history`, `im:history`. You can unselect all other scopes.
> >
> > 4. Click Next
> >
> > 5. Uncheck all User Token scopes - we don’t need any of them
> >
> > 6. Click Next, and complete the migration by clicking “Yes, Migrate my app”
> >
> > 7. On the left, choose “Install App”, then “Reinstall to Workspace”
> >
> > 8. Copy the “Bot User OAuth Token”, and paste it into the “chat\_integration\_slack\_access\_token” setting in Discourse
> >
> > 9. In the Slack sidebar, under “Apps”, choose your Discourse integration.
> >
> > 10. Click its name at the top, then “Add this app to a channel”
> >
> > 11. Select all the channels which you want Discourse to integrate with
> >
> > 12. Done 🎉
## Troubleshooting
### /discourse slash command returns `dispatch_failed` error
**Symptom**
After configuring Slack integration, you try the `/discourse` slash command and see the following error in Slack:
```plaintext
/discourse failed with the error "dispatch_failed"
```
**Cause**
It’s likely that this is due to a configuration error. Verify that the value you have configured for **Request URL** is correct. It should be in this form:
```plaintext
/chat-integration/slack/command
```
**Fix**
Update your **Request URL** and pay particular attention to the following:
1. Ensure it begins with the correct protocol (e.g. `https://`)
2. Ensure it is using the domain for your Discourse site (not your Slack instance)
3. Ensure it has the correct path `/chat-integration/slack/command`
> Last edited by @JammyDodger 2024-05-26T07:10:40Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@ivar](https://meta.discourse.org/u/ivar)
#### Post date: [September 16, 2017, 10:12pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/2 "2017-09-16T22:12:24Z")
I’m very excited to try this plugin. I gave installing it a shot by following these instructions carefully, but when I go to test a slash command on slack I get:
```plaintext
slackbot Darn - that slash command didn't work (error message: `403_client_error`). Manage the command at Discourse Integration.
```
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 16, 2017, 10:15pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/3 "2017-09-16T22:15:12Z")
> [@ivar](#):
>
> 403\_client\_error
This would suggest that it’s an issue with the authentication of slack to your Discourse instance. Can you double check that the incoming webhook token has been copied across correctly? (step 12 above) Make sure there’s nothing weird being copied before/after (e.g. spaces)
---
### Author:  [@ivar](https://meta.discourse.org/u/ivar)
#### Post date: [September 16, 2017, 10:21pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/4 "2017-09-16T22:21:17Z")
Also, it seems Slack’s App config tools are subject to refinement as a details in this howto have changed.
1. in step 4:
- was “Under features and Functionality” select “Permissions”
- now is “Under Features” select “OAuth & Permissions”
1. in step 6: would be good to clarify “Under Features, select ‘Slash Commands’”, same with step 8 “Under Features, select ‘Interactive Messages’”
Thanks for building and sharing this plugin!
---
### Author:  [@ivar](https://meta.discourse.org/u/ivar)
#### Post date: [September 16, 2017, 10:23pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/5 "2017-09-16T22:23:02Z")
> [@david](#):
>
> he authentication of slack to your Discourse instance. Can you double check that the incoming webhook token has been copied
Ugh, I went through the instructions twice, and realized I copied the verification token incorrectly. My issue was completely PEBKAC :(- thanks for the (immediate) help!
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 16, 2017, 10:25pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/6 "2017-09-16T22:25:45Z")
> [@ivar](#):
>
> details in this howto have changed
Thanks - I’ve updated the two things you mentioned, and converted the first post to a wiki. Please feel free to update if you notice anything else.
> [@ivar](#):
>
> thanks for the (immediate) help!
No problem - glad it’s working 😃
---
### Author:  [@ivar](https://meta.discourse.org/u/ivar)
#### Post date: [September 16, 2017, 11:00pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/7 "2017-09-16T23:00:06Z")
re: rule generation. The help doc states:
* * *
_New rule:_ `/discourse [watch|follow|mute] [category] [tag:name]`
(you must specify a rule type and at least one category or tag)
- _watch_ – notify this channel for new topics and new replies
- _follow_ – notify this channel for new topics
- _mute_ – block notifications to this channel
* * *
The integration doesn’t seem to be able to find tags.
_edit:_ Ugh.. I just saw the docs that the syntax for tags is _[tag:name]_ :facepalm: .. sorry I missed that…
I noticed that the help files are hard coded to the slash command “_/discourse_”.. I pulled down the source and got as far as finding the strings in the locale files and where they’re invoked in the helper. I would like to issue a PR to allow the slash command in help files to be configurable (my integration uses my sitename as the command…) but I’m not sure how persistence works with Discourse plugins. If I submitted a partially complete PR would you be able to provide some pointers or would that be a waste of time ?
Also, where would be the best place to add feature requests ?
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 16, 2017, 11:07pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/8 "2017-09-16T23:07:22Z")
> [@ivar](#):
>
> I noticed that the help files are hard coded to the slash command
The easiest way to change this to a different command is to go to your discourse admin panel, Customize Text Content, then type `chat_integration.provider.slack` into the search bar. You’ll find the “help” string in this list. Changes to this should persist across discourse/plugin updates
> [@ivar](#):
>
> Also, where would be the best place to add feature requests ?
I think slack-specific ones in this topic, and general ones for the plugin in [the main topic](https://meta.discourse.org/t/chatroom-integration-plugin-discourse-chat-integration/66522) 🙂
---
### Author:  [@ivar](https://meta.discourse.org/u/ivar)
#### Post date: [September 16, 2017, 11:16pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/9 "2017-09-16T23:16:30Z")
> [@david](#):
>
> The easiest way to change this to a different command is to go to your discourse admin panel, Customize Text Content, then type chat\_integration.provider.slack into the search bar. You’ll find the “help” string in this list. Changes to this should persist across discourse/plugin updates
Wow. That’s pretty sweet - no code changes necessary. (I’m pretty new to Discourse but it seems pretty badass!)
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [September 23, 2017, 12:00am UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/10 "2017-09-23T00:00:15Z")
> [@david](#):
>
> It allows posting notifications to Slack, managing rules using Slash Commands, and posting transcripts back to Discourse (/discourse post 20 will create a draft topic containing the last 20 slack messages).
What am I missing? When I try that, I get
“Sorry, this integration isn’t setup to support posting transcripts.”
Did I miss something? Is the feature available only to some Slack communities and not the free ones?
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 23, 2017, 8:32am UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/11 "2017-09-23T08:32:59Z")
You need to use the “OAUTH Token” method of authentication to slack, not the “Webhook” method. The instructions above should walk you through setting up the oauth method.
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [September 26, 2017, 11:13pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/12 "2017-09-26T23:13:22Z")
That did it. I think I broke it by foolishly trying to migrate the settings from the other slack plugin.
One thing I don’t understand is who can use the slack App I created. It is just me? If so, that’s a little sucky. If not, wait, _anyone_ can control what categories get watched? I see “collaborators” in the slack API page. If I add a collaborator can they too control the rules?
Also, it seems that rules established in the Discourse web interface don’t show up in slack if you do a `/discourse status`. Is that right?
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 26, 2017, 11:22pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/13 "2017-09-26T23:22:45Z")
> [@pfaffman](#):
>
> who can use the slack App I created. It is just me?
When you create slack apps, they are private to you. Only you can edit the settings of the app, and only you can install it onto an organisation. Notice the “Not Distributed” status:
You can then install your app onto your Slack organisation. If you have slash commands set up, anyone in that organisation can control the ‘rules’ for any channel they have access to, and so you should make sure to set the `chat integration discourse username` appropriately.
> [@pfaffman](#):
>
> I see “collaborators” in the slack API page. If I add a collaborator can they too control the rules?
‘Collaborators’ of the Slack app means that they can edit the app’s settings (things like callback URLs, auth secrets etc.). It has absolutely nothing to do with who can configure ‘rules’ using slash commands.
> [@pfaffman](#):
>
> Also, it seems that rules established in the Discourse web interface don’t show up in slack if you do a /discourse status. Is that right?
`/discourse status` should list all of the rules **for the current channel**. So if you have set up rules for `#general` using the discourse admin interface, they should show up when you run `/discourse status` in `#general`. If that’s not working, it’s a bug.
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [September 26, 2017, 11:31pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/14 "2017-09-26T23:31:51Z")
Thanks, @david, that’s a huge help. It still seems a bit wild that any slack user can change what Discourse stuff gets posted to a channel, but I suspect that’s because I don’t understand slack.
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [September 26, 2017, 11:52pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/15 "2017-09-26T23:52:46Z")
> [@pfaffman](#):
>
> It still seems a bit wild that any slack user can change what Discourse stuff gets posted to a channel
I think it depends what kind of community you have in Slack. In my mind there are three main scenarios:
- If any member of the public can join your Slack organisation, Slash commands probably aren’t a good idea. In this case it’s probably easiest to just manage the rules from the discourse admin panel.
- If you have a fairly open forum, but a closed slack organisation (like I believe the discourse team do), then having slash commands is a nice convenience without any real issue (everyone in slack is trusted).
- If you have a roughly 1:1 mapping between forum members and slack members (e.g. a corporate environment), it can be useful to allow individuals to manage the rules in their own slack channel. For example, the dev team might want to watch #Development, and the support team #Support. Rather than forcing all this to be done by a discourse admin, they can do it themselves with slash commands. I think this is how @mcwumbly uses slack integration.
---
### Author:  [@mcwumbly](https://meta.discourse.org/u/mcwumbly)
#### Post date: [October 5, 2017, 2:27pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/16 "2017-10-05T14:27:33Z")
> [@david](#):
>
> and posting transcripts back to Discourse (/discourse post 20 will create a draft topic containing the last 20 slack messages).
We’re starting to see some healthy adoption of Slack threads in some channels. I was a big skeptic at first, but as people find good patterns for using them, I can see their value. Does the transcript feature work with threads at all?
---
### Author:  [@david](https://meta.discourse.org/u/david)
#### Post date: [October 5, 2017, 2:43pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/17 "2017-10-05T14:43:02Z")
That’s great to hear - I was a little skeptical how useful it would be as well, so glad to hear people like it 🙂
> [@mcwumbly](#):
>
> Does the transcript feature work with threads at all?
Sadly not. I don’t know if the slack API allows loading messages from a specific thread, so we might need to do the filtering on the Discourse end.
---
### Author:  [@erlend\_sh](https://meta.discourse.org/u/erlend_sh)
#### Post date: [October 25, 2017, 3:40pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/18 "2017-10-25T15:40:56Z")
Should transcript export work with Direct Messages? I just tried with two different ones and it’ll say `Loading the transcript...` but nothing happens after that.
---
### Author:  [@alttext](https://meta.discourse.org/u/alttext)
#### Post date: [December 22, 2017, 7:09pm UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/20 "2017-12-22T19:09:38Z")
> [@ivar](#):
>
> slackbot Darn - that slash command didn’t work (error message: `403_client_error`)
I’m getting the same thing, and have checked my access and webhook tokes very carefully. Other things to try?
---
### Author:  [@alttext](https://meta.discourse.org/u/alttext)
#### Post date: [December 24, 2017, 1:05am UTC](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730/21 "2017-12-24T01:05:42Z")
Also - is it possible to connect Discourse to multiple Slack orgs?
[Next page](https://meta.discourse.org/t/set-up-slack-notifications-using-the-discourse-chat-integration-plugin/66730.md?page=2)