Discourse Chat Integration

Discourse
Thu, 20 Jul 2017 15:52:38 +0000
Plugin

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.
| Install Guide | This plugin is bundled with Discourse core. There is no need to install the plugin separately.

As this is an official plugin maintained by the Discourse team, Support, Contribute > Bug, Contribute > UX, and Contribute > 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 | | | |
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 Customization > 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.

https://d11a6trkgmumsb.cloudfront.net/original/3X/4/8/48ed362a57d59f70fd4c3632d1d0fcecc1d7d949.mp4

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 Developer Guides

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 Contribute > Feature… or feed your fish whenever there’s a new Customization > Plugin.

CHANGELOG

TODO

Last edited by @Moin Wednesday, April 8, 2026 6:33 AM UTC
Check document (clicca per ulteriori dettagli)

22 messaggi - 13 partecipanti