What are Badges?

[erlend_sh (Erlend Sogge Heggen)]

Badges in Discourse reinforce positive user behaviour and facilitates “learning by doing”. It is a central part of Discourse’s gamification features.

Receiving Badges

There are two ways to receive a badge:

1. Manually granted by an administrative user
2. Automatically granted by the system

Furthermore, all badges have some optional properties.

• Allow badge to be used as a title
• Can be granted multiple times
• Show badge on the public badges page
• Show post granting badge on badge page

Creating Badges

Manual and automatic badges are created the same way, via the admin panel. What sets them apart is how they’re triggered.

Manual Badges

A badge can only be granted by an administrative user. See how to manually grant a badge.

Automatic Badges

Automatic badges are granted by special triggers. Discourse comes with a lot of default badges out of the box, but administrative users can also create custom ones. At their most basic, automatic badges are simple “kudos!” for users who are just starting out.

For example:

• Added a link
• Received a like.

Certain badges also coincide with trust levels. When you’ve attained a new trust level, you’ll receive a corresponding badge to notify you of the bump-up.

• Trust Level 1 --> Basic
• Trust Level 2 --> Member
• Trust Level 3 --> Regular
• Trust Level 4 --> Leader

Want to create your own automatic badge? Go read how to trigger custom badge queries.

Badge Types and Groups

By default, badges are grouped into the following categories:

• Getting Started
• Community
• Posting
• Trust Level
• Other

When viewing a badge in the admin panel, you can use the button next to the “Group” dropdown to create custom badge groups. You can also adjust the position of each badge group as they appear on the /badges page of your site. If you need to modify the names of the default badge groups, visit /admin/customize/site_texts?q=js.badges.badge_grouping on your site to customize the text.

In addition to badge groups, badges are classified into three types. These include Bronze, Silver, and Gold. Each badge group will display Bronze badges first, then Silver, then Gold. The idea is to have the type reflect how difficult the badge is to acquire, with Gold being the most challenging.

Further Reading

• Granting techniques

  • How to grant a custom badge through the API
  • How to make requests to the Discourse API with Zapier (see Grant a custom badge section)
  • How to award a non-custom badge through the console
  • Grant a badge to individual users manually
  • Award a badge to a set of users (Bulk award using CSV)
  • Grant a custom badge to all members of a group from the console

• Badge Queries

  • Automatically grant a badge for all members of a group
  • Triggered custom badge queries
  • What cool badge queries have you come up with?
  • Some common badge queries
  • A badge for all members of a group

• Miscellaneous

  • What badges, if any, should Discourse have?
  • Initial Discourse badge design spec

[AlexTheRota (Alex "Rota" Freeman)]

Hello,

After some googles and on-page-searches I was unable to find anything about custom badge series. What I mean by this is a series of two or more badges that contain SQL that removes the previous badge in the series and adds the current badge.

So for example I have unlocked “Custom Badge 1” by posting 100 posts, and on my 200th, I unlock “Custom Badge 2” which for business reasons should not share badge space with the previous badge, the “Custom Badge 1” would be programmatically removed from this user.

TL:DR; How to write a query that removes a badge in such a way to run concurrently with a badge awarding query?

[Mittineague]

I think it should be possible if the query uses the user_badges table likely using these fields in some manner.

badge_id    integer 
user_id    integer    fkey users 
granted_at    timestamp 

As long as “run revocation query daily” is enabled you could have the “first level” badge get revoked if the “next level” badge had been granted.

There may be a brief time between the grant and the revoke where a member might have both, but it would resolve itself within a day at most.

I recommend that you become more familiar with the Discourse database tables before you attempt crafting badge queries. They can be a “foot gun” and there is good reason it is slightly more work to get the interface functional.

[Nina_11 (Nina)]

For various Discourse discussion forums, I noticed that I can access Badge information. Members who have received a specific badge are listed and aggregated under that specific Badge.

Is that aggregate list of users under each badge a total tally since the forum was originally created? Or is that a snapshot of a particular time period, e.g. the last 7 days x number of members earned the Leader badge?

[sam (Sam Saffron)]

The numbers we display are always going to be a tally since the forum was created.

[Nina_11 (Nina)]

Super! Thanks for the help