Grant a custom badge through the API

[simon]

Custom badges that you have created on your forum can be granted through the API. This is a great way to award badges without having to use custom badge SQL.

To grant a badge through the API, you need to know the username of the user that you wish to grant the badge to, and the ID of the badge you wish to grant. You also need to make sure you have generated an All Users API Key from your site’s Admin/API section.

Finding your API Key

This screenshot is from my local development site. Generally, you need to be very careful about sharing your API keys:

Finding the Badge ID

You can get the Badge ID from the badge’s URL. Go to your Admin/Badges section and then click on the badge that you wish to grant. The URL will look something like this: https://forum.example.com/admin/badges/102. The last number in the URL is the badge ID.

Making the API call

To test an API call, you can try granting a badge using curl or Postman. Here is how I grant a badge from my computer’s terminal with curl.

First, to make things easier, set an api_key variable:

 api_key=yourallusersapikey

Then to grant a badge with the ID of 102 to the user bobby:

curl -X POST "https://forum.example.com/user_badges" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: $api_key" \
-H "Api-Username: system" \
-F "username=bobby" \
-F "badge_id=102" \
-F "reason=https://forum.example.com/t/whats-the-best-photo-youve-ever-taken/160/2"

The reason parameter is optional. If you supply it, it must be set to the URL of a topic or a post on your site.

You should get a JSON response with details about the badge and when it was granted.

[jtbayly]

Has anybody added a badge (or flair) via Zapier to Discourse API like outlined here?

Discourse Webhooks and Zapier

[image] Want to use Discourse Webhooks to trigger a task via Zapier? Let’s get started! Zapier requires a trigger and an action. In this howto the trigger will be a Discourse Webhook and the action will be to send an email. Send an Email on any User event We will now set up a Zap to send email on any user event (i.e when a user is created, approved or updated). To trigger on a specific user event, see Trigger on a specific user event below. Create a Discourse Webhook Create a new Discour…

Also, seems like a great candidate for an action via the official integration, @HAWK.

[mattdm (Matthew Miller)]

See also How to create a custom badge with an image through the API, which shows how to upload, and also has another example of granting the badge (in python).

[smileBeda (Beda)]

What is the reason this method is not described in the API Docs at https://docs.discourse.org/?

I couldn’t find this there.

[pfaffman (Jay Pfaffman)]

@smileBeda

What is the reason this method is not described in the API Docs at https://docs.discourse.org/?

Because it doesn’t seem to be anyone’s job to keep those docs complete or up to date and some kind soul posted these instructions here. Generally, the documentation for the API is Reverse engineer the Discourse API and looking at the source.

[sunjam (james.network)]

Nice, so there is no way to automate such badge giving via API?

Example, someone who receives 5,000 likes on their replies is granted a badge.

[pfaffman (Jay Pfaffman)]

@sunjam

someone who receives 5,000 likes on their replies is granted a badge.

If you’re self-hosted, or on Enterprise, you want to Enable Badge SQL.

[simon]

@sunjam

someone who receives 5,000 likes on their replies is granted a badge.

If you can’t enable badge SQL, it would be technically possible to automate this, but it would be a two step process. First, make an API request to run a Data Explorer query that returns the usernames of users who meet your criteria who have not yet been granted the badge: Run Data Explorer queries with the Discourse API. Then, use the usernames returned by that query to grant the badge via the API.

This feels kind of inefficient though. As far as I can tell, there isn’t a route that can be used to grant a badge to multiple users with a single API call, so depending on how many users qualify for the badge, you could end up making a lot of API requests.

Ultimately, this feels like the kind of thing that could be handled by the Automation plugin. There could be a recurring trigger that runs a Data Explorer query with a given query ID. Based on the fields returned by the query, the results could be used to trigger various scripts. For example, if a username field was returned by the query, it could be used to run scripts that awarded badges, added users to groups, etc.

[pfaffman (Jay Pfaffman)]

@simon

There could be a recurring trigger that runs a Data Explorer query with a given query ID

Won’t the have the same problems that caused the badge sql to get disabled in the first place?

[simon]

I don’t think so. Data Explorer queries are run in a transaction block that times out after 10 seconds. I think the point of that is to avoid the kind of issue that badge queries can trigger. If things weren’t configured that way, an inefficient Data Explorer query could crash the site.

Thinking about that now, I wonder if custom badge sql could have the same kind of safeguard.