How to integrate Discourse Gamification with an external system (redeem and award points)

documentation developers
1

Since we launched Discourse Gamification a year ago, one of the most requested features from our roadmap has been the ability to make it possible to integrate Discourse Gamification with external gamification system . Examples are plenty:

  • Integrate with existing gamification programs in companies

  • ability to award points for events that happen outside of Discourse, like IRL events, or elsewhere online, like being a customer in a community, or buying a product.

  • the ability to allow users to redeem their points for swag, products or benefits

Today, just in time for the plugin’s first anniversary, we made all of the above possible with a full API to handle custom scoring events :tada:.

This new system allows admins to:

  • Award users a custom score event

  • Award users with negative score events, to accommodate redeem or penalties events

  • Update and list custom events previously created

API

:warning: Points awarded via API will take up to 10 minutes to reflect on a user overall score for events created with the current date, and up to 24h for events created in the last 10 days. For events created with a date past the last 10 days you need to run the backfill rake task.

There are 3 different API endpoints currently.

List Events

curl http://example/admin/plugins/gamification/score_events.json -H "Api-Key: apikeyhere" -H "Api-Username: system"

You can also list specific user or date events:

curl http://example/admin/plugins/gamification/score_events.json?user_id=1&date=2023-05-01 -H "Api-Key: apikeyhere" -H "Api-Username: system"

Create Event

jo -p user_id="13" date="2023-04-14" points="15" description="May 2023 Karaoke atendee" | curl --json @- -XPOST http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"

Update Event

jo -p id="1" points="25" description="May 2023 Karaoke atendee" | curl --json @- -XPUT http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"
25 Likes
2

Is/will there be a way to do this through the UI?

7 Likes
3

That’s something I would consider if an Enterprise customer wants to sponsor it.

10 Likes
6

This is incredible. We’re just in the middle of starting and piloting an ambassador/champions program, and we’ve been using Airtable to monitor webhooks from our different sources (Discourse, GitHub, Ghost) and aggregate our champions program there. I’m excited to check this out and see if it could be used for us to manage/monitor our program and contributions.

It would be great if you could award points to a user group instead of a user. The use case for us as an enterprise customer would be that we essentially want to award points to the company the users work for and aggregate their points for each company. What is the feasibility of something like this?

8 Likes
7

Ahh I don’t know how to use this :smiling_face_with_tear:
We’re using a business plan.

I wish we could operate this via the UI.

But still, thanks for building this team! Keep up the good work.

5 Likes
11

That could help to give one-time points within Discourse with Automation plugin?

1 Like
12

How does redeeming points work? I see there is an update event that could be used to subtract points from individual events, but that seems like an inefficient way to redeem points.

13

Also, when attempting to list events in my discourse instance, I get a 404.

GET https://developer.sailpoint.com/discuss/admin/plugins/gamification/score_events.json

404 Not Found
“The requested URL or resource could not be found.”

I have enabled the plugin and can configure it through the UI. Am I missing something to enable the external system API?

1 Like
14

It may be my decade of experience working at banks, but the way I envision redeeming points is issuing negative value custom events.

For example, let’s say you have a user who wants to redeem points for a T-Shirt, and that T-Shirt costs 10k points. The flow on your redeeming system would be:

  1. Check if the user has enough points:

    curl https://meta.discourse.org/u/falco.json -s | jq . | grep score
    "gamification_score": 89386,

  2. Issue a “point withdraw” event

    jo -p user_id="13" date="2023-04-14" points="-10000" description="T-Shirt Redeem - order #123" | curl --json @- -XPOST http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"

You will want to wrap this in a semaphore of some sorts, as this is the text book example of using those, but that is the gist of the proposed workflow.

This is a very recent feature, so let me know if the proposed workflow doesn’t work correctly.

image
image804Ă—134 12.2 KB

It’s working fine for me, both in the browser and via API. It’s an admin endpoint, so you need to be a logged in admin via browser, or pass API keys like explained in the OP.

3 Likes
15

Ok, that’s what I was missing. I didn’t realize you could issue negative points. That should work perfectly then.

:man_facepalming: I was using expired credentials. Thanks for confirming anyway.

2 Likes
16

@Falco

Are there any plans to add scopes to this API? It appears that the only way I can create or update scores is by having an admin API key that has global access. I would love to have a scope that restricts a key to just being able to update scores. This would give me more confidence using this API in automation tools as I wouldn’t have an admin key that can do much more than just update scores.

3 Likes
17

That’s a good idea, but I personally don’t have the bandwidth to work on this in the near future.

If you are keen on sponsoring this feature, please contact our support channel so we can get you a quote.

3 Likes
18

Facing the same issue here:

{"errors":["The requested URL or resource could not be found."],"error_type":"not_found"}
19

That error was caused by

So you want to check yours :wink:

1 Like
20

Thanks, I’m also gonna update to latest just in case

21

Updating to latest worked! ty

1 Like
22

I’ve been testing this a bit today. I see the events I can track, though unsure if there is a direct query to view only events by userid. Looking for a way to maybe have an audit log or present to users how they have gained/lost points.

1 Like
23

There is something logged in UI when API call get sucess adding points?

24

Awesome! And I have another suggestion, is it possible to add a feature that enable users to redeem points for subscriptions in the ui interface? And the ability to add a limit to the number of points a user can earn per day on an event ( like create topics).

Thanks!

25

No, the feature is 100% API based. You can call the “List Events” endpoint to check for events as described in the OP.

3 Likes