Higgs

Higgs is a generic dashboard for viewing and providing feedback to bots found in SOBotics. It originated alongside Boson - a framework for creating SOBotics bots. This blog post will run you through the process of setting up your own bot and integrating it with Higgs.

Setting up a dashboard

Bot setup is now entirely self-service! If you’re not already a bot owner, you’ll need to ask a Higgs admin to grant your account bot privileges. Once that’s done, you’ll be able to create a new bot yourself.

  1. You should now see an ‘Admin’ dropdown in the top left of Higgs:

    enter image description here

  2. Clicking ‘Bots’ will bring you to the bot management page. Here, you’ll see all bots that you own. Admins are able to see and edit every bot. From here, you’re also able to create a new bot:

    enter image description here

  3. When creating a new bot, you’ll be presented with the following page:

    enter image description here

    The following fields are required:

    1. The name of the bot
    2. The dashboard name
    3. The description of the bot
    4. The secret
    5. Optionally, you may also enter:
    • A link to the homepage of the bot.
    • A link to the bot’s logo.
    • A favicon. This will change the page’s favicon when viewing one of your bots reports. Must point to a URL.
    • Tab Title. This will change the page’s title when viewing one of your bots.

  4. Once you’ve submitted your bot, you’ll need to set up the feedback types. You can manage this from the /admin/bots page (as shown above).

  5. You’ll be presented with the following page:

    enter image description here

    • Name: The name of the feedback. This is what will be rendered on buttons for reviewers.
    • Colour: A browser-supported colour string. Hex or named colours are supported. Styles the colour of the feedback button, as well as the icon.
    • Icon: An icon to represent already cast feedback. It’s simply a string, and can technically be anything, but we recommend using a Unicode character.
    • Actionable: Whether or not this type of feedback is counted when putting reports into the review queue.
    • Enabled: Whether or not this type of feedback is allowed to be cast by a review.

Getting started in code

Higgs uses swagger to document its API. A benefit of this is that the boilerplate API code can be automatically generated. Here’s an example script being used to generate the API structure for Higgs’ frontend.

Note that the above is entirely optional. Generating the boilerplate is a nice-to-have, and not required. If you’d like to implement the API calls yourself, you can see the available endpoints here, as well as what security is required for each call.

Here’s an example of a bot authenticating itself, and then sending feedback for a user:

// Point the API to Higgs
const string basePath = "http://45.77.238.226";

var botApi = new BotApi(basePath);

// Here, 1 is the ID of your bot. This makes a POST request to /bot/AquireToken
var tokenResponse = botApi.BotAquireTokenPost(1, "THIS IS MY SECRET KEY");

// Now we've got the bot's access token, we need to configure our API to add it to future requests
// If you're not using swagger gen, you need to ensure future api requests add the following header:
// Authorization: Bearer [token]
botApi = new BotApi(new Configuration
{
    BasePath = basePath,
    AccessToken = tokenResponse.Token
});

// Example request after the bot has been authenticated
botApi.BotRegisterUserFeedbackPost(new RegisterUserFeedbackRequest(5, 1, "False Positive"));

The access token is a JWT token, and is currently valid for 7 days. Bots will be able to decode the token to inspect what scopes (permissions) it has been granted, and when the token expires.