Skip to main content Link Search Menu Expand Document (external link)
ContextMod

Getting Started

This getting started guide is for reddit moderators – that is, someone who wants an existing ContextMod bot to run on their subreddit. If you are trying to run a ContextMod instance (software) please refer to the operator getting started guide.

Table of Contents

Prior Knowledge

Before continuing with this guide you should first make sure you understand how a ContextMod works. Please review this documentation:

Choose A Bot

First determine what bot (reddit account) you want to run ContextMod with. (You may have already discussed this with your operator)

Use the Operator’s Bot

If the Operator has communicated that you should add a bot they control as a moderator to your subreddit this is the option you will use.

Pros:

  • Do not have to create and keep track of another reddit account
  • Easiest option in terms of setup for both moderators and operator

Cons:

  • Shared api quota among other moderated subreddits (not great for high-volume subreddits)

Ensure that you are in communication with the operator of this bot. The bot will only accept a moderator invitation if your subreddit has been whitelisted by the operator. This is an intentional barrier to ensure moderators and the operator are familiar with their respective needs and have some form of trust.

Now invite the bot to moderate your subreddit. The bot should have at least these permissions:

  • Manage Users
  • Manage Posts and Comments
  • Manage Flair
  • Manage Wiki Pages
    • Required to read the moderator-only visible wiki page used to configure the bot
    • Required to read/write to Toolbox User Notes

Bring Your Own Bot (BYOB)

If the operator has communicated that they want to use a bot you control this is the option you will use.

Pros:

  • Dedicated API quota
    • This is basically a requirement if your subreddit has high-volume activity and you plan on running checks on comments
  • More security guarantees since you control the account
    • Note: authenticating an account does NOT give the operator access to view or change the email/password for the account
  • Established history in your subreddit

Cons:

  • You must have access to the credentials for the reddit account (bot)

The operator will send you an invite link that you will use to authenticate your bot with the operator’s application. Example link: https://operatorsUrl.com/auth/invite?invite=4kf9n3o03ncd4nd

Review the information shown on the invite link webpage and then follow the directions shown to authorize your bot for the operator.

Note: There is information display after authentication that you will need to communicate to your operator – Refresh and Access token values. Make sure you save these somewhere as the invite link is one-use only.

Configuring the Bot

The bot’s behavior is defined using a configuration, like automoderator, that is stored in the wiki of each subreddit it moderates.

The default location for this page is at https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot

Setup wiki page

The bot automatically tries to create its configuration wiki page. You can find the result of this in the log for your subreddit in the web interface.

If this fails for some reason you can create the wiki page through the web interface by navigating to your subreddit’s tab, opening the built-in editor (click View), and following the directions in Create configuration for… link found there.

If neither of the above approaches work, or you do not wish to use the web interface, expand the section below for directions on how to manually setup the wiki page:

  • Visit the wiki page of the subreddit you want the bot to moderate
    • The default location the bot checks for a configuration is at https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot
    • If the page does not exist create it
  • Ensure the wiki page visibility is restricted
    • On the wiki page click settings (Page settings in new reddit)
    • Check the box for Only mods may edit and view and then save

Procure a configuration

Now you need to make the actual configuration that will be used to configure the bot’s behavior on your subreddit. This may have already been done for you by your operator or you may be copying a fellow moderator’s configuration.

If you already have a configuration you may skip the below step and go directly to saving your configuration

Using an Example Config

Visit the Examples folder to find various examples of individual rules or see the subreddit cookbook examples.

After you have found a configuration to use as a starting point:

  • Copy the URL for the configuration file EX https://github.com/FoxxMD/context-mod/blob/master../examples/subredditReady/freekarma.json5 and either:

Build Your Own Config

CM comes equipped with a configuration explorer to help you see all available options, with descriptions and examples, that can be used in your configuration.

To create or edit a configuration you should use CM’s buit-in editor which features:

  • syntax validation and formatting
  • full configuration validation with error highlighting, hints, and fixes
  • hover over properties to see documentation and examples

To use the editor either:

PROTIP: Find an example config to use as a starting point and then build on it using the editor.

Saving Your Configuration

Using the built-in Editor

In the web interface each subreddit’s tab has access to the built-in editor. Use this built-in editor to automatically create, load, or save the configuration for that subreddit’s wiki.

  • Visit the tab for the subreddit you want to edit the configuration of
  • Open the built-in editor by click View
  • Edit your configuration
  • Follow the directions on the Save to r/.. link found at the top of the editor to automatically save your configuration

Manually Saving

  • Open the wiki page you created in the wiki setup step and click edit
    • Copy-paste your configuration into the wiki text box
    • Save the edited wiki page

The bot automatically checks for new configurations on your wiki page every 5 minutes. If your operator has the web interface accessible you may login there and force the config to update on your subreddit.

Monitor the Bot

Monitoring the behavior of the bot is dependent on how your operator setup their instance. ContextMod comes with a built-in web interface that is secure and accessible only to moderates of subreddits it is running on. However there is some additional setup for the operator to perform in order to make this interface accessible publicly. If you do not have access to this interface please communicate with your operator.

After logging in to the interface you will find your subreddit in a tab at the top of the web page. Selecting your subreddit will give you access to:

  • Current status of the bot
  • Current status of your configuration
  • Statistics pertaining to the number of checks/rules/actions run and cache usage
  • A real-time view for bot logs pertaining to your subreddit

The logs are the meat and potatoes of the bot and the main source of feedback you have for fine-tuning the bot’s behavior. The verbose log level will show you:

  • The event being processed
  • The individual results of triggered rules, per check
  • The checks that were run and their rules
  • The actions performed, with markdown content preview, of triggered checks

This information should enable you to tweak the criteria for your rules in order to get the required behavior from the bot.

Additionally, you can test your bot on any comment/submission by entering its permalink in the text bot at the top of the logs and selecting Dry Run – this will run the bot on an Activity without actually performing any actions allowing you to preview the results of a run.