Chatroom Integration Plugin (discourse-chat-integration)

official

(David Taylor) #1

Continuing from Common event system for chatrooms

:speech_balloon: discourse-chat-integration :speech_balloon:

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:

16

Getting Started

  1. Install the plugin by following the Install Plugin instructions. The plugin’s repository address is
    https://github.com/discourse/discourse-chat-integration.git
    
  2. In your site settings, check chat_integration_enabled is :heavy_check_mark:
  3. Click on one of the providers below to see provider-specific setup instructions
  4. For more details, read ‘Configuring Rules’ below
Provider Notifications Slash Commands Post Transcripts
Slack :white_check_mark: :white_check_mark: :white_check_mark:
Telegram :white_check_mark: :white_check_mark:
Discord :white_check_mark:
HipChat :white_check_mark:
Mattermost :white_check_mark: :white_check_mark:
Matrix (riot.im) :white_check_mark:
Zulip :white_check_mark:
Rocket.Chat :white_check_mark:
Gitter :white_check_mark:
Flowdock :white_check_mark:
Stride Docs
Microsoft Teams Docs
Basecamp Docs
IRC Cloud Docs
Flock Docs

Terminology

There are three key concepts in discourse-chat-integration: Providers, Channels and Rules

Configuring 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:

  • Type:
    • 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 @mentioned in a standard post on the forum (mentions in private messages are ignored)
  • Filter:
    • 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
  • Tags
    • Enter a list of tags to match posts with at least one of the listed tags. Leave blank to match all posts

Multiple rules

When multiple rules match a post, the top-most rule in the user interface is executed. Rules are first sorted according to the criteria:

  1. Group mentions
  2. Group messages
  3. Normal

and then sorted within that by

  1. Mute
  2. All posts and replies
  3. First post only

For example, with the following rules

Filter Category Tags
All posts and replies Mentions of: @team (all tags)
Mute #support (all tags)
First post only #support #unsupported-install
All posts and replies (all categories) (all tags)

Notifications would be triggered for

but not for

Security/Permissions

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.

Slash Commands

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.

The commands available are

Posting a transcript

If 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.

Send /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.


Set up Slack notifications using the discourse-chat-integration plugin
Set up Mattermost notifications using the discourse-chat-integration plugin
Set up Rocket Chat notifications using the discourse-chat-integration plugin
Set up HipChat notifications using the discourse-chat-integration plugin
Set up Matrix (riot.im) notifications using the discourse-chat-integration plugin
Set up CA Flowdock notifications using the discourse-chat-integration plugin
Set up Gitter notifications using the discourse-chat-integration plugin
Set up Zulip notifications using the discourse-chat-integration plugin
Telegram Notifications Plugin (discourse-telegram-notifications)
Telegram Notifications Plugin (discourse-telegram-notifications)
Chat client suggestions?
[Deprecated] The Official Discourse Slack Plugin
Does Discourse have a chat room function?
Tool for Tossing out Notifications via Discord
Chat Integration leaks Babble chats
Contributor Interviews – David Taylor
iOS Mobile App Notifications
Recommended chat platform for Discourse
Notifications integration for Facebook and Twitter
Send summary of new posts to chat instead of every post update
Auto Post New Topics to Social Media
HipChat Integration
Dynamic of community with a chat and discourse page
Adding a new provider to discourse-chat-integration
Steam Authentication & Integration
Discourse-official-slack: no error message after failed post to slack
Help configuring Slack Discourse plugin
Set up Slack notifications using the discourse-chat-integration plugin
About the chat-integration category
[Deprecated] The Official Discourse Slack Plugin
(Michael Downey) #2

Very exciting!

Hope you’ll also consider looking at Zulip & Rocket.Chat, both open source platforms.


(David Taylor) #3

Have just updated this with the ability to post a transcript of a Slack chat to Discourse. The implementation is very simple, with no user interface at all. Just send

/discourse post 30

and the bot will reply with a link

Click the magic link, and your Discourse instance will open up, with the composer pre-filled with a transcript. You can then add a title/category, edit it if necessary, and post it to discourse.

It’ll look something like this:

You will need to be using the “Access Token” method of connecting to Slack, which is described in the #howto I just posted (see OP for link).


[Deprecated] The Official Discourse Slack Plugin
(Dave McClure) #4

:rocket:

A few thoughts on potential niceties here that could save some vertical space:

  1. Use > @name: the message instead of separate quote blocks
  2. Collapse sequential messages from the same user
  3. Include a link back to the original Slack conversation

So, in your example, it’d just end up looking like:

from #foo-channel in MyOrg Slack (Jul 6, 9:03 am):

@david01: First message
Well this is quite a boring message
I guess this is what happens when you have a slack organization with only one person in it
Lets post a link to https://meta.discourse.org

Discourse Meta

And if it weren’t a single person slack organization, then a conversation among a couple of users might look like:

from #bar-channel in MyOrg Slack (Jul 16, 11:26 am):

@alice01: First message
Second message

@bob02: Some random thought form bob
Another message from Bob
And a third

@alice01: yep, sounds great

@bob02: cool!


see here to view raw markdown for this suggestion


(David Taylor) #5

Sounds good - a lot tider. Might stick ** around the username to make it clearer where each new user starts. The slack API also gives us slack avatars which could be pulled in, so it would look something like this:

I didn’t even realise this was possible - now I do! I’m assuming that this would be just a link back to the first post of the conversation? Or is there a way to link to a range of posts?

I’ve avoided dates/times so far because of time zone differences… Should the times be local to the user that posted the transcript? Or the default locale of the forum? I’m thinking probably the former…


(Dave McClure) #6

I like the avatars and the boldness. Nice touch.

Yeah, I was just thinking it’d link to the first post.

Related, this idea to get this transcript into Discourse via "pull’ instead of “push”:

Fair point. Maybe just the date would be good? (Again, more relevant in the “pull” model, where I might be referencing a conversation from 2 months ago instead of 2 minutes ago).


(David Taylor) #7

Just pushed an update to the slack transcript formatting, so it now looks like this:

(screenshot so you can see the raw/processed markdown)

I’m using commonmark “Link reference definitions” to do the avatars, so the URL only needs to be included once :content:

If a user with the same username exists on the forum, they will get @mentioned… Dunno whether to class that as a feature or a bug, but I’ll leave it like that until someone complains :wink:


(Robert) #8

Looking forward for that!

I have another feature request: Wouldn’t be nice if notification could also be sent to e.g. slack on mentions of a group?


(David Taylor) #9

This plugin can now send notifications for messages sent to groups, and also whenever a group is mentioned (thanks for that suggestion @rriemann)

When creating a rule in the admin panel, you can now change the “type” to “group message” or “group mention”, and then specify the group.

The “filter” still applies - so if you only want to be notified about new messages to @team, you can set it to “First post only”.

Group-based rules have precedence over all others. So if you have ‘muted’ a category, and then someone @mentions the group, you will still receive a notification.

Posts are formatted exactly the same as for “normal” rules. So a “mention” notification in Slack would look like this:

36

This should work seamlessly with all the providers listed in the OP :smiley:


(Robert) #10

What about topics with resticted access? Does the integration will also post mentions in let’s say staff-only topics or private messages?


(David Taylor) #11

Good question. I’m going to write up some more detailed instructions in the OP to describe all the edge cases properly. But for the two you describe:

Mentions for topics in restricted-access categories follow the same rules as the rest of the plugin: it uses the access rights of the user specified in the chat_integration_discourse_username site setting.

By default this is the system account, so has access to all private categories. If you don’t trust everyone in your Slack/Telegram/etc. chats then you should create a non-admin account with the permissions you want.

Here is a test describing this behaviour.

I hadn’t thought of this one, so thanks for pointing it out! I’ve now made it so that mentions are never considered when they’re in private messages. A worst-case-scenario test for this can be found here.


(David Taylor) #12

Today I’ve been trying to get Facebook Messenger integration working, but sadly I don’t think it’s going to be possible. I know a lot of people use facebook messenger, so here’s an explanation for those who are interested:

Issue 1: I can confirm @MakaryGo was not exaggerating here! The number of steps required to set up an integration is huge compared to that of slack/telegram etc. There is then the further complication that every Discourse admin would have to get their app approved by facebook before it can actually be used. I didn’t get that far so can’t comment on how strict they are.

Issue 2: Facebook has strict rules about bots sending messages without user interaction. In their platform policy they list cases where it is allowed:

I think it could be open to interpretation whether Discourse notifications would fit into any of the three allowed categories, which could potentially become a problem at the app review stage.

Issue 3: Facebook does not support their full “Messenger Platform API” in group chats. This is the massive show-stopper. The only integration available for groups is the “Chat Extensions” API. This is purely user-interaction based, so we can’t send “subscription-based messaging”. I have confirmed this with members of their “Developer Community” Facebook group.

There are a number of unofficial bot APIs for Facebook Messenger, which pretend to be ‘real’ users on Facebook. This is against their terms-of-service, so I have not explored this option.


Hopefully Facebook will add group chats to their API in future and we can get a working integration.


Notifications via Facebook
#13

A post was split to a new topic: Notifications via Facebook


(David Taylor) #14

Totally agree that getting some kind of integration with Facebook would be great for attracting and keeping users interested in a community.

I think as far as this discourse-chat-integration plugin goes, doing anything other than group-chat notifications would be out-of-scope. This plugin is designed to link a community’s instant messaging system to their forum.

Let’s make a new topic to discuss the idea of facebook notifications


(David Taylor) #15

The slack transcript posting now has an improved UI, using Slack’s “Message Buttons”. Here’s a quick video demonstrating its use:

You can go up to 500 messages in the past. The dropdowns will contain 20 messages outside of the current transcript range.

To get this working it requires another step in the setup - if you’ve already set up this plugin, you need to go back to the slack setup and complete the “interactive messages” setup in step 8.


(Dave McClure) #16

I’m confused by this. If I want to start from 500 messages ago, how do I do that?


(David Taylor) #17

Two ways at the moment:

  • Type /discourse post 500, and the first message will be 500 messages in the past
  • Keep clicking the top option in the list - you’ll move up the history in steps of 20 (the dropdowns are reloaded after you change messages). Obviously getting to 500 that way will be very tedious, but it works for less extreme numbers

There’s nothing technically stopping me increasing the “20”, but I think any more than that is going to make the menus incredibly hard to navigate. I could include all 500 in both dropdowns, and rely on the “filtering”, but I’m not sure that’s a better UX.

I can’t really think of a better interface using the available UI elements (buttons or textual dropdowns). Suggestions for improvements are very welcome :slight_smile:


(Dave McClure) #18

Makes sense, thanks!

One idea would be this:

  1. Copy the starting message URL
  2. /discourse post <paste message URL>

Is that feasible?


(David Taylor) #19

This enables /discourse post <message URL>:


(David Taylor) #20

I have updated the OP with some detailed information on how to use the plugin. Hopefully it covers all the edge cases, but if anyone notices anything missing please let me know :slight_smile: