Auto Moderator

Auto Moderator

The Auto Moderator allows you to write custom rules that are run when a post is captured in your feed.
We've collated below some useful information about how to use the tool. But the best way for you to familiarise yourself and get comfortable with it, is just to try it out. Give your Auto Moderator some simple rules to begin with and see how it looks. Then, you can start to get more creative as you learn.

Syntax

Syntax is a term referring to the structure of code.
An Auto Moderator rule is created using a block of YAML code with a fixed structure. In order to work, each rule needs to contain the properties name, conditions, and an event.

When you make a new rule, you give it a name. Then, you set some conditions to outline what situations it applies to. The event is the action the rule takes.

Sample Block

This is a sample block of YAML creating an example rule.

rules:
  - name: Cat text posts
    conditions:
      all:
        - fact: post_text
          operator: includes
          value: cat
    event:
      type: log

This code creates a rule called Cat text posts. The conditions block (which means the text underneath Conditions) outlines that the rule applies to all text posts that include the word 'cat'. The event block instructs the rule to log that each relevant post was posted.

Properties Glossary

Below are all of the properties which Auto Moderator can currently use to moderate.

name:
The name of the rule. This name is used in logs and reports and shows which rule was triggered.
conditions:
Defines the situation in which the rule will run.
Conditions can be grouped under the property all (AND logic - this condition and also this condition must be true) or any (OR logic - this condition or this condition must be true). For each rule, you will specify at least one condition.
The criteria that you define for your conditions must be met in order for the rule to run.
- all:
  An array of conditions where the rule will run if all of them are true.
- any:
  An array of conditions where the rule will run if at least one is true.
event:
The action which the rule takes when the conditions are met. The event can be any of the types below.
- type:
  The type of action which the rule will take. Supported event types include:
  - log: Records the event in the logs, does not affect the post.
  - remove: Permanently removes the post from your feed.
  - hide: Hides the post in your feed.
  - deny: Denies the post so it does not appear in your feed.
  - approve: Approves the post so it appears in your feed.
  - require-approval: Flags the post for manual review before it appears in your feed. The hyphen must be included for this type to work.

Operators

The full list of available operators is:

includes (matches whole words, supports wildcards)
doesNotInclude (matches whole words, supports wildcards)
equal
notEqual
in (meaning: in a given list)
notIn (meaning: not in a given list)
contains (simple text contains)
doesNotContain (simple text does not contain)
lessThan
lessThanInclusive (less than a given number or that number e.g. 5 or less)
greaterThan
greaterThanInclusive (greater than a given number or that number e.g. 5 or more)

Example Rules

Here are some more examples of how you might define rules using the Auto Moderator:

Example 1: Logging All Posts

This rule logs every post that comes through the feed.
The line with the # sign at the front is a comment. It doesn't affect how the code runs but is included so that you can keep track of what your rules are without having to think too much about the code itself. You don't have to put them in if you don't want to!

rules:
  #This is a rule that will match any post captured, and then log that post. All posts have an id greater than 1.
  - name: Log All Posts
    conditions:
      any:
        - fact: id
          operator: greaterThan
          value: 1
    event:
      type: log

Example 2: Remove Offensive Content

This rule removes posts that contain specific words (dog and fish, for the purposes of our example, but you can set whichever words you like).

rules:
  # Match any post that includes either "dog" or "fish" as whole words.
  # Uses the same logic as capturing feeds.
  - name: Remove Dog and Fish
    conditions:
      any:
        - fact: post_text
          operator: includes
          value: 
           - dog
           - fish
    event:
      type: remove

Example 3: Require Approval for External Links

This rule requires manual approval for posts that contain external links. We've done this by setting up a condition where the action is triggered by a post containing 'http' which is typically in a URL. The embedded_link fact refers to a Bluesky link card.

rules:
  # Match any post that has a link card
  # Assuming all links will contain http
  - name: Require Approval for External Links
    conditions:
      any:
        - fact: embedded_link
          operator: contains
          value: http
    event:
      type: require-approval

Example 4: Automatically approve certain posts

This rule automatically approves posts if they include certain words. For example, if this feed were capturing posts about "dahlia" and "dahlias", then we might want to automatically approve a post if it also contains any common gardening terms.

rules:
  - name: Auto Approve
    conditions:
      any:
        - fact: post_text
          operator: includes
          value: 
            - garden*
            - flower
            - seed*
            - plant*
            - grass
            - bloom*
    event:
      type: approve

Example 5: Hiding replies from specific users

This rule will automatically hide posts that are Replies, if the person who is replying is a specific user. This might be useful if your feed captures all their posts normally, but you only want to show their Original and Quote posts.

rules:
    - name: Hide replies by specific users
      conditions:
        all:
            - fact: post_author_handle
              operator: in
              value: 
                - dailynous.com

            - fact: reply_parent
              operator: includes
              value: "*"
      event:
        type: hide

Example 6: Automatically delete posts from users who block you

This rule will try to download a post via your own Bluesky connection, as it is captured by your feed.

If the post cannot be seen by your user account, then it is likely that there is a blocking relationship between you and the post author: you have blocked them, or they have blocked you.

In either case, it is assumed that you do not want posts from that author in your feed, and Auto Moderator will then automatically hide it from your feed and label it as "Blocked by Auto Moderator".

This behaviour is an intended side-effect of the download requested in the logging rule. You do not have to explicitly request that the post be hidden in your rule, only that a post is downloaded for testing.

rules:
  # This will download the post via your own Bluesky API connection instead of our service connection
  # If your connection is not able to see the post, it will be treated as "blocked"
  # and be automatically removed from your feed regardless of any conditions
  - name: Check not blocked    
    conditions:
      any:
        - fact: post_from_api 
          path: $.uri
          operator: doesNotContain
          value: "at://"

    event:
      type: log

Other Facts and Examples

A fact is a piece of information about a post which your Auto Moderator rule looks at to determine whether a condition is met.

rules:
  #This is a rule that will match any post captured, and then log that post. All posts have an id greater than 1.
  - name: Log All Posts
    conditions:
      any:
        - fact: id
          operator: greaterThan
          value: 1
    event:
      type: log

You can start to see all available facts by creating a logging rule such as the one above. In fact, you can copy and paste the block above to start logging all the posts that come through your feed.
As posts come through the feed, they will appear in the Auto Moderator logs with a detailed record of all available facts.

In addition to this, there are a few more special facts that you can take advantage of:

fact: author_profile

fact: author_profile will download the profile of the author who created the post.

Using the path: option, you can then access information about the author such as their bio, and any labels they have applied. In the example below, we use the path $.description to check if the author of the post indicates that they are a NSFW account. The Auto Moderator will therefore hide any posts that were captured if the author has either 🔞 or the word "nsfw" in their bio.

rules:
- name: Hide NSFW authors
  conditions:
    any:
      - fact: author_profile
        path: $.description
        operator: includes
        value: 
          - 🔞
          - nsfw
        
  event:
    type: hide

fact: quoted_post

fact: quoted_post will download the post that is being quoted by your captured post (the one that comes into your feed).

From there, you can access all the same facts as a regular post, if you use the path: option. In the example below, we using the path $.post_author_handle to check if the author of the quoted post is fyodork.bsky.nz. The Auto Moderator will therefore log posts where fyodork.bsky.nz is the original author and someone else has quoted the post.

rules:
- name: Quoted Post Author
  conditions:
    all:
      - fact: quoted_post
        path: $.post_author_handle
        operator: equal
        value: fyodork.bsky.nz
        
  event:
    type: log

fact: replied_parent_post

fact: replied_parent_post looks at a post which has been replied to and logs relevant replies. In the example below, the Auto Moderator will log all replies to posts by Fyodork.

rules:
- name: Fyodork Posts with Replies
  conditions:
    all:
      - fact: replied_parent_post
        path: $.post_author_handle
        operator: equal
        value: fyodork.bsky.nz
        
  event:
    type: log

fact: replied_root_post

fact: replied_root_post will look at the top most parent of a post that is in a reply thread. If a down thread reply has been captured by your feed, the Auto Moderator will log the captured post, and look at the original (root) post at the top of the thread. For example, you might want to run a rule which acts on that root post based on how many likes it has.

In the example below, replies that have been captured in the feed will be logged if there are more than 4 likes on the root post at the time of capture.

rules:
- name: Parent Posts Likes
  conditions:
    all:
      - fact: replied_root_post
        path: $.raw_post_view.likeCount
        operator: greaterThan
        value: 4
        
  event:
    type: log

fact: rate_limit_posts

fact: rate_limit_posts will look at how many posts have been captured by your feed over a given period of time and take action based on the number. You can set a value of your choosing, which the rule will work off.

This rule makes use of the special rate_limit_posts fact, which counts how many posts have been captured either per feed or per author within a certain time frame (which can be defined as seconds, minutes, hours, days, weeks, months, years). You can then use this number to test if your rate limit exceeds a set amount (e.g. 2 posts) and take action if it does.

In the example below, posts will be rate limited i.e. the Auto Moderator will hide them if there have been more than 14 posts in the hour prior.

rules:
- name: Rate Limit posts in the feed
  conditions:
    all:
        - fact: rate_limit_posts
          params:
            over: 1 hour
            per: feed
          operator: greaterThan
          value: 14
  event:
    type: hide

In this example, you can see that the users fyodork.bsky.nz and blueskyfeedcreator.com are only allowed to post 2 posts per hour before the Auto Moderator will begin taking action by hiding excess posts.

You can continue to list authors like this and they will all be subject to the rule.

The rate limit count will apply to each user's posts separately, so they are both allowed to post up to two times per hour.

rules:
- name: Rate Limit certain authors
  conditions:
    all:
      - fact: post_author_handle
        operator: in
        value: 
          - blueskyfeedcreator.com
          - fyodork.bsky.nz
          
      - fact: rate_limit_posts
        params:
          over: 1 hour
          per: author
        operator: greaterThan
        value: 2
        
  event:
    type: hide

fact: list_members

fact: list_members allows you to take action if a post's author is or is not in one of your Synced Lists. The rule below looks at a post in the feed, determines whether the author is in a given list (list number 5, in this case) and takes action based on that: in this case, requiring approval for that post.

rules:
- name: Require approval for people in a certain list
  conditions:
    all:
      - fact: list_members
        params:
          list_id: 5 # This is the BSFC id of your Synced List. You can only access lists Synced under your own account.
        operator: contains
        value: 
          fact: post_author # post_author is the Bluesky DID, rather than the handle. Lists store DIDs so we are comparing like for like.
        
  event:
    type: require-approval

You can find the list_id required by opening your Synced List in BSFC:
../assets/Pasted image 20240818161844.png

Set Yourself Up for Success

Start Simple: Begin with basic rules and gradually add complexity as you become more comfortable with the Auto Moderator's capabilities.
Test Thoroughly: Before deploying your rules, test them by using event type: log to log rule matches without taking any action. If you are wanting to use a rule to remove a post, start out by just hiding them until you are confident in the rule's conditions. It's easy to unhide a post if the Auto Moderator gets it wrong.
Document Your Rules: Keep a record of all rules, their purposes, and any changes you make. This will help in maintaining and troubleshooting your Auto Moderator setup. Using comments will help with this; you can enter a comment by starting a line with the # character.

Available Facts

There are a lot of facts available that you can use in your rules. Below is a table of some of the most useful ones. To see all available facts, you can look in your Auto Moderator Logs.

Fact	Description	Example
post_text	Contains the entire text of the captured post	We keep our cats indoors but they LOVE grass so we bring some in every now and then. Toni was particularly excited today 😂 #aotearoapets
post_author	The internal Bluesky DID of the author. Doesn't change even if they change their handle.	did:plc:4h4vxzyu7h3aedk4wz4mat2v
post_author_handle	The Bluesky handle of the post author.	fyodork.bsky.nz blueskyfeedcreator.com
languages	The languages of the captured post.	en es fr
detected_language	Tries to detect the language of the post text regardless of what language the author identifies it as.	zh es en
labels	A list of labels that have been applied to the post.	nsfw porn nudity sexual
alt_text	All the alt-text from all the images in a post.	A silver tabby is standing on her hind legs, with one paw touching a woman's leg. She is holding a bundle of grass above the cat's head and the cat is staring at it with her tongue out.
embedded_link	If a post has embedded a link card, the URL will be shown here.	https://blueskyfeedcreator.com/documentation/
has_images	Does the post have at least one image.	true false
has_gif	Does the post have an embedded GIF.	true false
raw_post_view	Access the post's raw data from the Bluesky API.	`fact: raw_post_view` `path: $.likeCount`

Using Auto Moderator to Filter Posts by User Bio

You can use Auto Moderator to filter posts by things found in user bios, including, excluding or requiring approval on that basis.

First you need to open Auto Moderator using the button below, which is found between ‘Manage allowed users and lists’ and the feed view graph.

You will have a large black box for writing YAML code in, and this is where you can put a block of code to take action on user posts, based on things found in their bios.

In the example code block below you can see that for the rule called ‘Dogs Drool’, when a user bio (here called author_profile) includes the text ‘dog lover’ or ‘my dog’ then their post will be automatically hidden by the Auto Moderator.

rules:
- name: Dogs Drool
  conditions:
    any:
      - fact: author_profile
        path: $.description
        operator: includes
        value: 
          - dog lover
          - my dog
        
  event:
    type: hide

And the result of the code block is seen here when Wag E. Tail tries to infiltrate the cat pictures feed.

Because of the term ‘dog lover’ in Wag E. Tail’s bio, his posts are automatically hidden in the feed.

You can copy and paste our example block of YAML into your own feed and adjust the values and actions to suit your needs.