Summary: Integrate your chat system of choice with Discourse
Install: Follow the plugin installation guide.
Continuing from Common event system for chatrooms
discourse-chat-integration is the product of my Google Summer of Code project with Discourse. It allows sending notifications about new Discourse posts to ‘group chats’ on a number of instant messaging platforms.
It is based on, and aims to supersede, the existing discourse-slack-official plugin.
Notifications can be triggered by new topics, new replies, messages to a group, or mentions of a group. A notification in your instant messaging system will look something like this:
- In your site settings, check
- Click on one of the providers below to see provider-specific setup instructions
- For more details, read ‘Configuring Rules’ below
|Provider||Notifications||Slash Commands||Post Transcripts||Threaded Replies|
There are three key concepts in
discourse-chat-integration: Providers, Channels and Rules
In your forum’s admin panel, under Plugins, you should see a Chat Integrations section. Within that there will be tabs for each of your enabled providers:
Rules have a number of options which can be configured:
- Normal - send notifications based on standard posts on the forum
- Group Message - send notifications based on private messages which a specified group is a part of
Group Mention - send notifications whenever specified group is
@mentionedin a standard post on the forum (mentions in private messages are ignored)
- All posts with threaded replies - notify for new posts matching this rule, create per-topic threads on the chat provider (not available in all integrations)
- All posts and replies - notify for new posts matching this rule
- First post only - notify only for new topics matching this rule
- Mute - prevent notifications matching this rule
Category (if type is ‘Normal’)
- Match posts based on their category. Leave as “(all categories)” to match all posts on the forum
Group (if type is ‘Group Message’ or ‘Group Mention’)
- Specify the group you want to receive notifications for
- Enter a list of tags to match posts with at least one of the listed tags. Leave blank to match all posts
When multiple rules match a post, the top-most rule in the user interface is executed. Rules are first sorted according to the criteria:
- Group mentions
- Group messages
and then sorted within that by
- All posts and replies
- First post only
For example, with the following rules
|All posts and replies||Mentions of:
|First post only||#support||#unsupported-install|
|All posts and replies||(all categories)||(all tags)|
Notifications would be triggered for
but not for
The site setting “
chat integration discourse username” allows you to secure your notifications against leaking private information.
By default the
system account is used, which means that there is no restriction on notifications sent. To secure your notifications you should create a non-staff user with appropriate access privileges, and enter its username in the site setting.
If your provider supports slash commands, you can manage rules from within your chat interface. Each provider varies slightly in syntax, but in general they follow a similar structure. (Note that at this time, only the Slack integration implements threads.)
The commands available are
Posting a transcriptIf your provider supports transcript posting, you can post your instant messaging history to discourse. This is currently only supported for the Slack provider. Note: You will need to be using the “Access Token” method of connecting to Slack.
/discourse post to see the interface. The plugin will try and “guess” where your current conversation starts, by looking for a gap in the message history of more than 3 minutes.
Alternatively, you can specify a number of posts after the command, or a URL to the first message.
Adding new providers
Option 1: Submit a PR implementing your provider:
Option 2: Use your own plugin:
It is possible for third party plugins to register new “providers”. As an example, I’ve created a provider which sends webhooks to IFTTT. This could be used to automatically publish all posts in a category to facebook… or turn on your light when someone posts in #feature… or feed your fish whenever there’s a new #plugin.