Viafoura Conversations — Making Custom User Badges using Python
This article looks at how The Telegraph are using the custom badge feature in our recently-integrated, new commenting system, ‘Conversations’ by Viafoura. It’s just one of the tools in their community-building suite, which we chose to implement for its automated moderation and real-time interaction capabilities, to help us drive user engagement. There are also some examples of how to create and assign badges to users by interacting with Viafoura’s API, and how to process a batch of users with a simple Python script.
On all news websites, there exists a never-ending drive to increase user engagement, and having a comments block at the end of an article certainly helps. What’s even better, and makes the comments block more like a conversation, is having your authors contribute to the thread.
Getting an author to stand out against other users in the comment thread is achieved by adding a label or badge next to their name.
In Viafoura Conversations, there are quite a few options you can use for labelling up different types of users, with varying results. ‘Trusted Users’ get an icon next to their name, which looks very similar to the Twitter ‘verified account’ status tick. A ‘Moderator’ user type outputs a similar icon in a different style (‘M’ on a green background), and there is also the capability to set up a basic-looking ‘AUTHOR’ badge by adding some meta tags to the page.
These are all good features, but at The Telegraph we wanted to label our authors with a bespoke ‘Telegraph author’ label, so we needed a more flexible labelling option.
Custom Badges
We found we could achieve this by using Viafoura’s custom badge functionality. It allows you to create badges containing some arbitrary text, and then assign those badges to specific users, so you can label up as many users you like, with anything you like! You can even assign multiple badges to a single user.
Setting up custom badges for your users is not as straightforward as you might think. The functionality is somewhat hidden away and you won’t find it when you look inside Viafoura’s admin console in the User tab, as you might intuitively expect.
In the admin console, the only information you’ll see about a user is their name, email address and a link to the comments they have posted. You might expect to also be able to configure things like badges in here, but sadly (at the time of writing) there is currently no interface for doing this. Instead, you have to make use of Viafoura’s API.
Using Viafoura’s API
To start making calls to Viafoura’s API, you’ll need to know your ‘section_uuid’. This is a unique ID for your domain, provided to you by your client success representative.
Each time you make calls, you’ll need to generate an access token by sending your ‘section_uuid’ to their /authorize_client endpoint. Once you’ve generated your access token, which is valid for 5 minutes at a time, you can then make calls to the api endpoints that you need to create and assign a badge.
First step — Create the badge
To create a badge you need to make a PUT request to the /profile/badge endpoint with a json payload containing the badge label and badge description. The label is the unique identifier and the description is what will actually be displayed on the front-end. For example:
This same call will also update the description in an existing badge if the label matches an existing one. So, if you’ve created a badge by mistake and want to remove it, then just send a DELETE request to the same /profile/badge endpoint with just the label of the badge you want to get rid of in the json payload, for example:
Note that, at the time of writing, there is no endpoint for obtaining a list of all the current badges you have already created in Viafoura’s system, so it’s useful to keep your own record of the badges you’ve created.
Second Step: Assign the Badge
Once you’ve created the badge, you can move on to the next step of assigning it to a specific user. To do this, you’ll need to make a PUT request to the Viafoura API /users/profile/badge endpoint, with a json payload containing user id of the person you want to assign the badge to, their login type, and label of the badge you want to assign to them, for example:
If a 200 response is received back, then you have successfully assigned the badge to the user. If you get a 400 response, then the badge doesn’t exist in Viafoura and will need to be created (see above).
Third Step — Automate!
But what if you have a lot of users that need to be assigned badges? You won’t want to waste time making individual API calls for each person when a simple Python script can do the job.
A Python script to assign badges to a list of users needs to have the following steps:
- Obtain a list of users to process (which could be stored in a separate file).
- Make a Viafoura API call to get an Access Token.
- For each user in the list, make a Viafoura API call to assign the badge.
Note in the following example, the use of the Python requests library which will need to be installed first.
Example Python Script:
That’s it. The last request will return a 200 status code if successful (response.status_code == 200) and your desired badge name will be assigned to the user.
Multiple Users’ Badges
To assign multiple badges to a list of users, you can expand your script and have it read a list of user Ids from a file, loop over the Ids and make the API assignment request.
To get Python to open and read from a plain text file, you can use the Python urllib library. The text file should be set up with each user’s ID on a new line. For example:
After getting the basic Python script working, you can add extras like checking the response codes of your requests, printing out helpful messages and allowing raw inputs for badge names and environments. You could also expand the script to include badge creation and deletion.
For more information and documentation on the badges API, you can refer to Viafoura’s detailed API documentation.
Wendy Cocksedge is a Senior Software Engineer at Telegraph Media Group. Follow her on Twitter.
