 |
Summary | Discourse Events adds dynamic and interactive calendar and event features to your Discourse site. |
 |
Install Guide | This plugin is bundled with Discourse core. There is no need to install the plugin separately. |
Enabling Events
The Events plugin can be enabled either by the toggle or from its settings, both accessible from your admin/plugins page:
Features
Somewhat unsurprisingly, Discourse Events adds both the calendar and event features to your Discourse site. With these, you can create individual topic calendars to track important occasions or timelines, display calendars in categories, add a holiday calendar to mark vacations, absences, or sick days, create interactive event topics, as well as show an easy-access calendar summary of all of your upcoming events.
Calendars
Bespoke calendars can be created in multiple topics, and ones you wish to give higher visibility to can be displayed above a category’s topic list.
You can find more detailed information on how to create and use calendars in:
Events
The Event feature allows interactive elements to be inserted into topics which your members can use to sign up to attend or participate in your community’s activities. These are all summarised in a dedicated site-wide calendar, with the option to add an easy-access link to your navigation menu. You can find more information on how to create and use this feature in:
This should not be confused with Pavilion’s Events plugin (note the plural)
Calendar Settings
| Name | Description |
|---|---|
| calendar enabled | Enable the discourse-calendar plugin. This will add support for a [calendar][/calendar] tag in the first post of a topic. |
| holiday calendar topic id | Topic ID of staffs holiday / absence calendar. |
| holiday status emoji | Defines the emoji used for the holiday status. |
| delete expired event posts after | Posts with expired events will be automatically deleted after (n) hours. Set to -1 to disable deletion. |
| all day event start time | Events that do not have a start time specified will start at this time. Format is HH:mm. For 6:00 am, enter 06:00 |
| all day event end time | Events that do not have a end time specified will end at this time. Format is HH:mm. For 6:00 pm, enter 18:00 |
| calendar categories | Display a calendar at the top of a category. Mandatory settings are categoryId and postId. eg: categoryId=6;postId=453[1] Other valid settings: tzPicker[2], weekends[3] and defaultView[4]. |
| calendar categories outlet | Allows to change which outlet should show the category calendar. |
| working days | Set working days. You can display the availability of a group using the timezones tag in a post, eg: [timezones group=admins][timezones]
|
| working day start hour | Start time of the working day hours. |
| working day end hour | End time of the working day hours. |
| close to working day hours extension | Set extension time in working day hours to highlight the timezones. |
| calendar automatic holidays enabled | Automatically set holiday status based on a users region (note: you can disable specific automatic holidays in plugin settings) |
| map events title | Maps title of the sidebar calendar based on category. Defaults to “Upcoming events” |
Event Settings
| Name | Description |
|---|---|
| discourse post event enabled | Enables the Event features. Note: also needs calendar enabled to be enabled. |
| discourse post event allowed on groups | Groups that are allowed to create events. |
| displayed invitees limit | Limits the numbers of invitees displayed on an event. |
| display post event date on topic title | Displays the date of the event after the topic title. |
| use local event date | Use local date after topic title instead of relative time. |
| discourse post event edit notifications time extension | Extends (in minutes) the period after the end of an event when going invitees are still being notified from edit in the original post. |
| discourse post event allowed custom fields | Allows to let each event to set the value of custom fields. |
| events calendar categories | Display an events calendar at the top of a category. |
| sort categories by event start date enabled | Enable the sorting of category topics by event start date. |
| disable resorting on categories enabled | Allow categories to disable the ability for users to sort on the event category. |
| sidebar show upcoming events | Show upcoming events link in the sidebar under ‘More’. Requires post event enabled
|
| map events to color | Assigns an event color to a specified tag or category |
The
discourse-post-event/events.jsonendpoint now has an added parameter to switch between simple and detailed response. To get the detailed response you can add?include_details=true:
/discourse-post-event/events.json?include_details=true
Creating Events via the API
You can create events via POST /posts.json with [event][/event] BBCode in the raw field. Here are the details on how to setup your API request:
- Use
POST /posts.jsonwith therawparameter - Event syntax:
[event start="2024-05-10 20:00" status="public" timezone="America/Vancouver" end="2024-05-10 21:30" allowedGroups="trust_level_0"]\n[/event] - A literal
\nnewline is required between opening and closing tags - Double quotes must be escaped when using JSON (
\") - The API user account must have permission to create events (admin or a group with event creation rights)
- Set the category via the
categoryparameter, passing in the category’s id as the value.
Livestream events
For live events, use the livestream functionality to let members watch an event and participate in chat at the same time.
A livestream event includes:
- A video stream (using YouTube, for example)
- A calendar event using Discourse Events
- An accompanying chat channel automatically created for the event
Prerequisites for livestream events
To use livestream events, you must have chat enabled, since livestream creates a chat channel to accompany your event, in addition to discourse post event enabled and calendar enabled.
If you want to use livestream, but don't want chat elsewhere...
- Set
chat allowed groupsto the default configuration, or includetrust_level_0to let brand new users participate in livestream chat - Remove groups from the
direct message enabled groupssetting to prevent user-to-user DMs - Don’t create other chat channels
Creating a livestream event
To create a livestream event:
- Open a new topic.
- Select the + icon in the composer toolbar and click Create Event (if the event was not already added to your topic).
- Paste the link to the event video (e.g., a YouTube URL) in the location/URL field.
- Toggle on “livestream”
You will then see that the event and livestream has been created, along with an accompanying chat channel on the right side.
Once any user hits Going on the event, they will automatically join the chat channel, allowing them to participate in the conversation!
Livestreaming Zoom webinars
You can use livestream to host Zoom webinars directly in Discourse, so that members can watch the event and participate in the accompanying chat channel without leaving your community.
Prerequisites for Zoom webinars
In addition to the livestream prerequisites, you will also need to configure the following settings:
- Turn on
livestream zoom enabled - Enter your Zoom Meeting SDK key in the
livestream zoom sdk keysetting - Enter your Zoom Meeting SDK secret in the
livestream zoom sdk secretsetting
To obtain the Zoom Meeting SDK key and secret:
-
Go to marketplace.zoom.us, click Develop, and click Build app.
-
When asked what type of app you’re creating, choose General App and click Create.
-
From the app’s App Credentials page, copy the Client ID (SDK Key) and Client Secret (SDK Secret).
-
Under Embed, enable the Meeting SDK permission.
-
In your Discourse, go to Admin → All site settings and enter the values from step 3 in
livestream zoom sdk keyandlivestream zoom sdk secret.
For the Zoom webinar to work correctly in Discourse:
-
The webinar should not require registration or a passcode to join.
-
Disable Zoom’s built-in webinar chat to ensure all discussion happens in the single Discourse chat channel to keep all chat in one place and ensure the conversation can continue after the webinar ends.
Creating a Zoom webinar livestream event
To create a livestream event for your Zoom webinar:
- Open a new topic, select the + icon, and click Create Event.
- Paste your Zoom webinar link (e.g.,
https://zoom.us/``...) in the URL/Location field. - Toggle Livestream on.
- Set the event name, start time, end time, and other event details as desired.
- Post the topic.
Like other livestream events, this event will be created with an accompanying Discourse chat channel that members auto-join after they RSVP as “Going”.
Member experience
Here’s how your members will experience the webinar:
Before the event
A Join Zoom button is shown from 30 minutes before the event starts. Outside that window, the button is disabled with a message indicating when it will become available.
During the event
Once members click Join Zoom, the webinar will load into the topic page (or, if the host hasn’t yet started the event, the member will need to wait until they do so to see the video).
Audio does not automatically connect when joining the webinar; attendees need to click or tap the audio icon in the Zoom toolbar to connect. This is a Zoom SDK limitation and can’t be changed.
On mobile, the webinar opens in a full-screen Zoom view (which is also accessible on desktop by adding /zoom to the end of the event topic URL) with a floating Chat button that they can tap to open a chat overlay panel during the event.
After the event
The Join Zoom button is hidden 10 minutes after the event end time. The chat channel remains accessible to attendees until you close it.
Integrations with Other Plugins
You can use a component from this plugin with Right Sidebar Blocks. You’ll want to ensure the desired route is enabled in the Right Sidebar Blocks component. The block name will be upcoming-events-list. Historically, there were additional settings required in the Calendar plugin itself, but this has been streamlined.
This is how the sidebar calendar will appear by default.
If you don’t want the time, you can add an empty timeFormat value in the component’s block setting.
-
categoryId is the category the calendar will be displayed on top of.
postId is the post in which you put the calendar in with [calendar][/calendar] ↩︎ -
it can display a time zone picker on the upper right of the calendar. False by default, you can enable it with tzPicker=true ↩︎
-
it can hide Saturdays and Sundays from the calendar. True by default. You can set it to false with weekends=false. ↩︎
-
defaultView will set the calendar’s view (day, week, etc;). It can be set as:
defaultView=agendaDay
defaultView=agendaWeek
defaultView=month (default)
defaultView=listNextYear ↩︎
Last edited by @Moin 2026-08-26T14:37:57Z
Check document
Perform check on document:
