Discourse Chat Integration

[Discourse]

Chat Integration is for using an external chat system together with Discourse — you may be looking for Discourse Chat which adds Chat functionality directly to Discourse.

	Summary	Discourse Chat Integration allows you to integrate your chat system of choice with Discourse.
	Repository Link	https://github.com/discourse/discourse-chat-integration
	Install Guide	How to install plugins in Discourse

As this is an official plugin maintained by the Discourse team, support, bug, ux, and feature requests can be made in the respective categories here on Meta, and tagged with the appropriate plugin tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

Features

discourse-chat-integration allows sending notifications about new Discourse posts to ‘group chats’ on a number of instant messaging platforms.

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:

Configuration

1. In your site settings, check chat_integration_enabled is
2. Click on one of the providers below to see provider-specific setup instructions
3. For more details, read ‘Configuring Rules’ below

Provider	Notifications	Slash Commands	Post Transcripts	Threaded Replies
Slack
Telegram
Discord
Mattermost
Google Chat
Matrix (element.io)
Zulip
Rocket.Chat
Gitter
Flowdock
Stride	Docs
Microsoft Teams
Basecamp	Docs
IRC Cloud	Docs
Flock	Docs
Webex

Before you enable “Slash Commands” for your provider, make sure to read the Security/Permissions section below

Terminology

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

Provider: An external ‘instant messaging’ provider. See the list above for examples. A provider can contain multiple ‘Channels’.

Channel: Represents a single chat in your instant messaging application. They might be called ‘group chats’, ‘channels’, ‘rooms’ etc. by your provider. Each channel can contain multiple ‘Rules’

Rule: The plugin checks the list of rules for each channel when deciding whether to send a notification about a new post on Discourse. It can get confusing when you have lots of rules, so make sure to check the information below!

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 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
  • Tag added to topic - notify when a tag is added to a topic (the create post for category and tag changes site setting must be enabled for this to work)
  • 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

• A post in plugin
• A post in support mentioning @team

but not for

• A post in support
• A post in support with tag unsupported-install

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.

If you have “Slash Commands” enabled for your provider, and do not trust every member of the external “Channel”, it is absolutely essential that you set this up to avoid them having access to private categories on your forum.

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. (Note that at this time, only the Slack integration implements threads.)

The commands available are

New rule: /discourse [thread|watch|follow|mute] [category] [tag:name]
(you must specify a rule type and at least one category or tag)

• thread – notify this channel for new topics, thread replies if possible
• watch – notify this channel for new topics and new replies
• follow – notify this channel for new topics
• mute – block notifications to this channel

Remove rule: /discourse remove [rule number]
([rule number] can be found by running /discourse status)

List rules: /discourse status

Help: /discourse help

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.

To load a transcript for a Slack thread, you can use /discourse post thread {url}, where {url} is the permalink of the first message in the thread. For example:

/discourse post thread https://<slackname>.slack.com/archives/C6029G78F/p1522952993000017

Alternatively, you can use /discourse post with a thread-specific permalink like this:

/discourse post https://foo.slack.com/archives/G49KKS6AX/p1523062012000911?thread_ts=1523091738.000088&cid=G49KKS6AC

In both cases the “first/last message” UI is skipped - the entire thread is included in the transcript.

Adding new providers

Option 1: Submit a PR implementing your provider:

Add a new provider to discourse-chat-integration

discourse-chat-integration abstracts away the boilerplate for integrating Discourse with external chatroom systems. There are three features which a provider implementation can support: Notifications, Slash Commands and Transcripts. There are two ways you can add a provider: in your own plugin, or by submitting a pull request to discourse-chat-integration. This post will detail the latter, but most of the information will work in either scenario. This post gives a general overview of how thing…

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.

CHANGELOG

TODO

Last edited by @JammyDodger 2024-06-18T15:54:32Z

Check document

Perform check on document:

[sunjam (james.network)]

It would be interesting to add support for Discourse’s own ActivityPub Plugin so that publishing could be triggered based on tags and other filters from chat integration.

[Aizada_M]

Hello, last year Telegram announced forums/topics (mini chats within group chats). I tried to connect each individual mini chat to one or another category of my site. But as I understand, topic addresses are not supported by the plugin? For example, in my case, each topic has an address as follows: @telegram_topic /1, @telegram_topic /2, @telegram_topic /3 …
If I insert a standard chat name into the line, for example @telegram_chat, it works without problems.
It would be very convenient if the plugin had the ability to insert similar chat addresses (…/1), then users would not have to be subscribers to many independent channels tied to certain categories of the site.

[sunjam (james.network)]

@Aizada_M

then users would not have to be subscribers to many independent channels tied to certain categories of the site.

Have you considered using tags to accomplish this?

[Aizada_M]

I think using tags is not entirely suitable for my case. Because even with the help of tags, I wouldn’t want all notifications to go into one channel, creating information noise. At the same time, instead of having 20 channels for 20 categories/tags, I would prefer to have one group chat where I could organize several mini-themed chats (by category/tag) where each user can view the one they need minichat and the ability to look into other minichat. I’m so bothered because in my region (Asia) most people use WhatsApp and Telegram chats - forums are not popular. But I’m trying to find a compromise).

Ps. If I repeat myself often, don’t judge me, I’m just trying to convey my thoughts correctly, as I use Google translator.

[sunjam (james.network)]

@Aizada_M

I wouldn’t want all notifications to go into one channel, creating information noise.

You should be able to filter which tags would apply to which chats, at least as far as I am understanding you.

[Aizada_M]

@sunjam

You should be able to filter which tags would apply to which chats, at least as far as I am understanding you.

It seems to me that we are talking about different things I don’t have a question about filtering chats by tags/categories.
For context. Previously, Telegram had channels and chats (except for bots). These channels/chat rooms have a username, approximately @chat_username or @channel_username.
Since last year, Telegram has had the opportunity to turn chats into forums containing mini thematic chats like this. These mini chats have their own usernames, for example @chat_username /1, @chat_username /2. The convenience of such chats with minichat is that the user no longer needs to subscribe to several chats separate from each other, but just subscribe to one chat (for example, with the name of my site) and have access to many mini chats (in my case, each mini chat would target a specific category on the site) that are of interest to the user.
Now I want to connect these mini chats to this plugin, but it seems to me that the plugin does not support the mini chat username as chat_username /1.

[atwong (Albert Wong)]

Is there a way to create a rule where I can tag a new message and/or reply so it won’t post to target chat system (in this case Slack)?

[david (David Taylor)]

Hey Albert, if we’re talking about normal Discourse tags, you can set up a ‘mute’ filter to prevent topics with that tag triggering notifications in Slack.

But in terms of individual posts, there is no way to filter them out.

[ErlendMS (Erlend Markussen Saltnes)]

I think I have the same want as you, Aizada:

I’d love to be able to have a Telegram group chat, with topics enabled (that somewhat correspond to the categories on Discourse), and then, in the Discourse/Chat integration settings, specify which topic it should post to.

I’ve tried to create a group chat with topics now (with just the bot and me), but when I type /help within a topic, the bot answers in the general chat.

Have you looked into this @david? I found this Stack Overflow thread, that shows how to get the message_thread_id (which is the topic id) and says that the bot API got support for this in 6.3.

Thanks for your work anyway! 🫶🏻

[david (David Taylor)]

Hi @ErlendMS . We don’t have any enhancements for this plugin on our roadmap at the moment, but if someone would like to add ‘threading’ (aka topic) support for the telegram integration that would likely be pr-welcome.

We do have some threading support in the slack integration, so it should be possible to reuse some of that logic.

[PeakProsperity (Aaron McKeon)]

Is it possible to use this plugin to get notifications in Slack whenever a post is flagged for review? Thanks.

[BrainFried]

Does this plugin expose additional API functions?

[crossheadscrewdriver]

Where do I request a PR review? I’ve submitted this PR late last week to add a new provider and it is still pending a reviewer. I’ve looked around different developer guides on meta and couldn’t find one for proper PR requests.

Here’s my PR: FEATURE: Added Power Automate as a new provider by benoitdesnoyers · Pull Request #204 · discourse/discourse-chat-integration · GitHub

Thanks,

[grubba (Gabriel Grubba)]

Hello guys! we’ve just merged this pr for chat integration plugin

This change aims to remove the tags_changed option from the rule filtering from chat integration–we are doing this change because we are removing the Creation of a small action post when a topic's category or tags change setting.

But the functionality will remain the same, if you have discourse automation installed. The next time you run the migrations for this plugin, it will add a script to the discourse automation plugin that will run similarly to what we currently have.

This is an example of automation that will be created:

It will be sent to my channel based on the categories and watching tags that I have.

${ADDED_AND_REMOVED} is the default text; it will behave the same as the rule would.

We have also added for this script option a few options that can be used in the message:

• ${TOPIC} for the topic name
• ${REMOVED_TAGS} for the removed tags
• ${ADDED_TAGS} for the added tags
  both removed and added will only trigger if they have a tag in them.
  For example: added: ${ADDED_TAGS} message will only trigger if there are added tags

[grubba (Gabriel Grubba)]

We had an issue with the other PR(users who used other providers could not use the automation when topic tags changed), so to address it, we have made this new PR, where we account for every provider.

The Creation of a small action post when a topic's category or tags change setting will not appear in chat integration.

If you have discourse automation installed the next time you run the migrations for this plugin, it will add a script to the discourse automation plugin that will run similarly to what we currently have.

---

Your automations will look something like this:

And your providers are the enabled providers.

For example, I have Discord,Slack, Telegram and Google Chat enabled

Your channel name is the name you gave it in the chat integration settings.

For example, the name here is Spidey

[grubba (Gabriel Grubba)]

We have a new batch of changes for the Automation/chat-integration

In this new batch, notable changes are:

• We added Trigger with PMs, which lets you control whether this automation should be triggered even on private messages.
• Solved an issue where Topic tags changed trigger automation was being triggered during topic creation.

[grubba (Gabriel Grubba)]

As mentioned before – here

The create post for category and tag changes site setting currently can leak private tags/categories; one way that we found to keep that feature was by moving it to whispers:

It works similarly to small posts, but now, you need to have whisper allowed groups with some group to make it work.

I’ve merged a PR for core with this change and one for chat-integration, removing the usage of that setting; the automation feature added back should be 1:1 with the small action if anyone has any issue, please let us know!