Discourse Integration Guide

Overview

Connect Discourse to import all topics, posts, and replies from your community Contacts. Common Room's integration with Discourse offers robust analytics and intelligent insights so you can scale and measure your impact.

Common Room creates a profile for every participant in your Discourse community and an activity for each message, allowing you to see when they joined, the channels they are more active in, the messages they post, and their replies and reactions to other posts.

Setup

1. Open Settings and select Discourse.
2. Confirm that you have admin access to Discourse. If you aren't an admin, you can click to invite an admin to your Common Room.
3. Enter your Discourse information and API key. First, paste in the URL from your Discourse community (for example, https://mydiscoursecommunity.discourse.group). Next, enter your username that you use to login (make sure the username you use has admin permissions in Discourse). Lastly, enter your Discourse API key (click here for instructions on how to setup the Discourse API).
   1. You can use a global or a non-global (granular) API key with our integration, though there are key differences in how each works:
   2. Global - A global key works with all Discourse setups and allows imports to run the fastest. We recommend this for import speed and completeness for larger-sized Discourse instances.
   3. Non-global (granular) - A non-global (granular) key works with most Discourse setups and requires reduced permissions, but cannot import data as quickly as with a global key.
4. Setup webhook retries in Discourse by following the instructions here.
   

Technical details

The Discourse integration with Common Room is available on Essentials, Team, and Enterprise plans.

You must be an administrator of your Discourse instance to set up this integration. The integration leverages the official Discourse API and requires two credentials: an API key and a webhook secret.

Contacts and Activities

When you connect a Discourse forum to Common Room, we’ll import all of the users who have accounts in the forum. Activities are created for every post and reply.

Import History

Once you configure your Discourse integration, Common Room will import its entire Contact list and Activity history. This may take some time depending on the size and age of your forum.

Sync frequency

Once Discourse is connected to Common Room, we'll import new Contacts and Activity within a few minutes after they are created in Discourse.

FAQ

Can Discourse badges be imported into Common Room?

We do not currently import Discourse badges. If you’d like to see these features or others, join Uncommon and let us know.

Is there a difference in how Common Room and Discourse count topics and posts?

Yes. For example, in a Discourse topic with 5 total posts (including the original), Discourse counts that as 1 topic and 5 posts. Common Room counts this differently as 1 topic with 4 posts.

Why is the Discourse "First Active" metric in Contact Explorer higher than the "Active Between" metric in Reporting?

In Common Room, joining Discourse counts as being active in the Contact explorer “First Active” filter, but does not count as being active in the Reporting view’s definition of active.