Summary	Discourse Chat adds chat functionality to your Discourse instance.
	Install Guide	This plugin is bundled with Discourse core. There is no need to install the plugin separately.

Features

As mentioned in our initial announcement and most recent update, this plugin adds chat functionality to your Discourse so it can natively support both, long-form and short-form communication needs of your online community.

Configuration

Initial Setup

Head to your /admin/plugins page to click the chat  Settings button.

On that page, Chat can be enabled by checking the chat enabled site setting. By default, Chat will be available to the staff group only, but you can add more groups (or open it up to everyone) by adding them to the chat allowed groups setting.

Channel retention

By default, channels are configured to retain messages for 90 days and direct messages are configured to retain messages forever, but these are configurable site settings:

• chat channel retention days (default 90 days)
  Choose how long to retain Chat messages for channels
• chat dm retention days (default forever)
  Choose how long to retain your Chat messages for personal chats

Other site settings

Additional site settings allow you to configure a set of default emoji reactions and a range of safety features (such as maximum chat messages per second, minimum message length, silence duration, and whether to allow uploads).

Accessing Channels and Creating New Ones

After the plugin is enabled, a speech bubble will appear in the header next to the Search icon, and clicking on that will open your Full Screen Chat window, where you can access default channels as well as start new personal chats. To navigate back to your Full Screen Chat window from inside each channel, use the < icon in the top left corner.

Using the button on any Chat window, you can toggle between Full Screen mode and Drawer mode.

Create a channel

To create a new channel (staff only), select the icon in the top-right corner of your Full Screen Chat window and select Create a channel. Choose a category to associate it with, give it a name, and add an optional description to display on the Browse Channels page.

A Category can have multiple channels associated to it, and more can be added anytime. As a channel is always linked to a category, you can rely on existing category permissions to automatically limit who has access to that particular conversation.

Want a channel just for your TL3+ users? Then creating a new channel for your Lounge category will do just that.

Joining a channel

You can preview and join channels from the ‘Browse channels’ page. From this page, you can view all the channels that are visible to you and eligible to join, as well as control your notifications for each channel using the options in the bell icon.

Inviting users to channels

@mentioning individual users or groups will give the option to invite them to the channel if they aren’t participants already. To invite groups in this way, the ‘Who can @mention this group?’ on the group’s /manage/interaction page must be set to something other than ‘Nobody’.

Closing and deleting channels

Admins and moderators can close or delete channels from the channel’s settings page, which can by accessed by clicking the channel name in the channel’s header. A closed channel can be reopened any time, but deleting a channel is not reversible, so there is an additional confirmation check in place.

Starting a personal chat

To start a personal chat, use the icon on your Full Screen Chat window and start adding usernames to the recipients list. To leave a personal chat click the X icon next to the channel name (only on desktop).

If you accidentally leave a personal chat, starting a new chat with the same person/people will link you back to the messages sent previously.

In-Chat options

Like topics, Chat Messages support:

• edits
• replies
• quoting
• oneboxing
• reactions
• bookmarks
• deletion

In the composer, you can insert dates, upload files, and GIFs! Chat channels support channel-wide @here and @all mentions with per channel while presence features like a green halo for online users & username is typing… indicator are also present.

You can also select one or more Chat Messages and ‘Quote to topic’ to take a quick conversation and make it into a Discourse topic for in-depth discussion.

Admins and moderators also have the ability to select Chat Messages and move them to a different channel.

Automatically add users to a channel

Chat Information panel

Clicking a channel title will now take users to a useful info panel with three tabs:

• The About tab will display title, description and linked category, so users have the context they need for each channel.
• The Members tab lets users see who else is in the room with them (member list and total count). It includes a filter so they can use search.

• The Settings tab will let you set notification preferences (mute, desktop / mobile push notifications). For admins, this tab also includes the auto-join mode toggle.

Chat preferences

When Chat is enabled, users see a new /preferences/chat page in their preferences. On this page, they can opt-out of Chat, opt-out of the @here and @all notifications, manage their Chat email notifications or choose a desktop sound.

The existing settings on /preferences/users page also apply to chat direct messages, so users can also turn off direct messages or mute or ignore other individual users.

Integrations

Discourse Chat supports Incoming webhooks but has no support for interactive bots or slash commands yet.

Sending Chat messages using Incoming webhooks [Slack-compatible]

image1397×441 32.9 KB

The UI for creating webhooks can be found at Admin > Plugins > Chat > New incoming webhook. You can configure a name, description, username (that posts messages), destination channel and emoji for each webhook.

Hosted by us? Chat is included as a bundled plugin for everyone.

A post was merged into an existing topic: Using the translator API’s on chat

4 posts were split to a new topic: Remove a user from a channel

Request a feature that allowing iframe in Discourse Chat

Request a feature to add free webRTC or jitsi based audio and video personal and group video and audio calls in the chat please. It will hugely increase community engagement.

How do we allow anonymous users and guest to participate in DMs and group channels chats?

How to stop external links from being sent to avoid spammers spamming urls and links in chats? Any filtering or banned words or regex to filter in the chat?

Allow admins and mods to make group announcements in all DMs and all private group channels.

That already exists with Jitsi:

We found that with our own Jitsi instance we could improve the oneboxing so that it is much more obvious what is going on.

2 posts were split to a new topic: NSFW image blurring in chat

Are these messages retained in the database once deleted?

I just happened to have a chat channel that was no longer active… so I ran a Data Explorer query. And the answer is no, they are completely deleted from the database.

Any plans on incorporating voice chat into this?

Hello!, I was exploring chat features, and I have added some images to a chat message. The images show up properly, but, I thought that when I click on the images they will jump into an overlay and enlarge the image to the original size, or something that makes it possible to visualize the image in a larger size, but nothing happened. Is that something I need to configure?, or that feature is not available for chats?
Thanks!

Hello and welcome @c0d3m3nt0r

There’s actually been another report of this in Chat: Make Images Clickable / Expandable. There’s a possibility it may be a non-official plugin that’s interfering somehow.

From what we can tell, it’s working as intended in chat here on meta and clicking on an image in chat does enlarge it.

Do you have any special setup/plugins/configuration that may help narrow it down?

As an Admin, being able to reorder the Channels in the sidebar, similar to Discord, would be great. I was thinking of using both Discourse and Discord, but I can see how I can now remove a lot of things from Discord and use my forum for that, but having a specific structure for my channels order would be essential.

I also think that we should be able to create channels that are not linked to categories. There’s nothing in a channel that seems linked to a category when we are in a chat room, so I don’t see why they need to be linked.

If someone with a forum wants to have a chat for “gaming”, that doesn’t mean they need to go and create a category for that, because maybe that category will not have any traffic at all and it’s just another thing to crowd the categories list, when there’s no need to.

You can create multiple channels all associated with a single category – no need to create a category for every channel.

That said, you’re not the first to point out that the category relationship feels unnecessary. Here’s another recent feature topic about this: Make it easier to add people to channels through chat UX

In that case, it makes the feature even more “obsolete”, because there’s no real connection to the categories.
Not that this is an issue, but it’s just another thing that’s just there without real meaning behind it.

But at least knowing that multiple channels can be linked ot the same category, avoids adding categories just for the sake of creating new channels. Thanks for the info.

Yes the category currently serves primarily as a means to define access control for the channels within it.

So the feature I linked to above would make that part obsolete. In the meantime, that’s the main purpose the relationship serves.

Just to make sure I understand: you mean that for example a certain group of people that can access category A, is the same group of people that can access one or more channels that are linked to that category A? Is that what you mean?

If so, since I believe that categories and channels should be separate features, then the permissions could be set on a Channel level by type of user, or by creating Channel Groups, if that makes sense?

I’m thinking of how Discord works where each channel can be assigned to different Roles.

Yes, exactly.

When I read this I understood it to mean that only admins can create channels. But I just had a moderator create a channel.

What is going on. Does admin not mean admin user?

It seems to be a typo. Based on the code, the access level has consistently been for staff (admin and moderator). Thanks for pointing out this error! (EDIT: I updated the first post)

Thanks! I love how active and responsive the community is. Thank you!

Hello! I have a specific use case in which I would need to be able to create channels and add users using an API

And to then add users to existing channels using an API as well

1. Is this something possible to do using this plugin?
2. If so, is there an API documentation for this plugin I can refer to?

I know you can create users via API. You could add them to a chat by adding them to a group that has chat access. I don’t see a method to create the chat itself via API though.

I’d like to open or link to a topic with the chat window opens by default in drawer mode on the right hand side, showing the channel of the the topic’s category. Is that possible?

Not out of the box atm, you can have multiple channels for one category too so we would need a more explicit way to decide which one to show.

It would be nice if there is a way to set a channel as the default channel of a category.

And a setting to always display the chat in drawer mode.

Our users have difficulties with switching between the forum and chat.

I think I may have found a bug related to this plugin.

On my forum, https://scarletandblackinsider.com/, when the Discourse Chat plugin is enabled, the post composer box on mobile starts auto-scrolling to the very top of the topic while the user is typing. This causes the text editor to bounce up and down and makes it almost impossible to reply in longer threads.

Key details:

• Hosted on Discourse standard plan

• Core is fully up to date

• Reproduced across multiple fresh themes

• Reproduced with all theme components disabled

• Issue immediately disappears when the Chat plugin is disabled

This feels like a scroll or focus handler conflict between the Chat plugin and the mobile composer. Happy to provide any additional testing details if helpful.

The bug was fixed a few days ago. Things should get better after the next update.

This bug has been resolved in Discourse Chat-settings/members can’t scroll on ios/ipados 26.2 - #10 by small-lovely-cat, just sync with the latest commit.

Hello!

First off we love this plugin, we use it to stay in touch with our most active users in our forum.

We often have a message or something important for a short period of time to convey. We would love for the ability to pin chat messages that would show up a the top of the chat window.

I am thinking for our bigger group chats we may only want admins to be able to pin chats, so maybe an additional toggle in the chat settings to only allow admins to pin messages.

I am curious if anyone else would use this feature in their community!

Then you might want to add your vote to the feature request about pinning chat messages

I swear I searched for this… Thank you!

Do I turn of email_digest summary, every message automatically email to user.

Unlike other preferences, as an admin you cannot set a default for this, so each user has to disable it for themselves. There is a feature request to add this: Can't set Email Notifications for Chat in admin setting

Currently, your only option is to use the Rails console with the script in that topic to change the preference for all users (and to repeat this for new users).

Hello, I am not sure if this is the correct place for this, but images uploaded into chat are not using my CDN for the thumbnails, which is what I want. So the thumbnail appears broken, but clicking on the image correctly opens the original resolution. Is there no option for the thumbnails to use the CDN?

I’m playing with one of the free-tier hosted Discourse forums to see if it might be a good option for a Discord community replacement for a Twitch stream - and so far I’m impressed! I was wondering, is sticker support and/or a GIF picker on the roadmap for the chat feature?

hi @baralheia welcome.

I don’t know about stickers - i think there might be a theme component somewhere but i don’t know if they work in chat.

there is a stickers theme component:

and a gifs theme component:

Im pretty sure the free plan doesnt support theme components though

@mentioning individual users or groups will give the option to invite them to the channel if they aren’t participants already

Does this imply there’s no way to send people a link to a chat? Or could we @mention and then send a link?

Is this accessible by the API at all? I can see a world where we want to automatically generate and close chats for cohorts.

You could give them a link that automatically adds them to a group with access to the chat. Perhaps the “Arrive at topic” can be a topic explaining what the chat is and contain a link to the chat/how to use it.

there is no official documentation on chat api, but it is accessible

If they’re already in a group can we point them to the chat directly, though?