Note: this page of the Synapse documentation is now deprecated. For up to date documentation on setting up or writing a spam checker module, please see this page.

# Handling spam in Synapse

Synapse has support to customize spam checking behavior. It can plug into a variety of events and affect how they are presented to users on your homeserver.

The spam checking behavior is implemented as a Python class, which must be able to be imported by the running Synapse.

## Python spam checker class

The Python class is instantiated with two objects:

- Any configuration (see below).
- An instance of `synapse.module_api.ModuleApi`.

It then implements methods which return a boolean to alter behavior in Synapse. All the methods must be defined.

There's a generic method for checking every event (`check_event_for_spam`), as well as some specific methods:

- `user_may_invite`
- `user_may_create_room`
- `user_may_create_room_alias`
- `user_may_publish_room`
- `check_username_for_spam`
- `check_registration_for_spam`
- `check_media_file_for_spam`

The details of each of these methods (as well as their inputs and outputs) are documented in the `synapse.events.spamcheck.SpamChecker` class.

The `ModuleApi` class provides a way for the custom spam checker class to call back into the homeserver internals.

Additionally, a `parse_config` method is mandatory and receives the plugin config dictionary. After parsing, It must return an object which will be passed to `__init__` later.

### Example

    from synapse.spam_checker_api import RegistrationBehaviour

    class ExampleSpamChecker:
        def __init__(self, config, api):
            self.config = config
            self.api = api

        @staticmethod
        def parse_config(config):
            return config

        async def check_event_for_spam(self, foo):
            return False  # allow all events

        async def user_may_invite(self, inviter_userid, invitee_userid, room_id):
            return True  # allow all invites

        async def user_may_create_room(self, userid):
            return True  # allow all room creations

        async def user_may_create_room_alias(self, userid, room_alias):
            return True  # allow all room aliases

        async def user_may_publish_room(self, userid, room_id):
            return True  # allow publishing of all rooms

        async def check_username_for_spam(self, user_profile):
            return False  # allow all usernames

        async def check_registration_for_spam(
            self,
            email_threepid,
            username,
            request_info,
            auth_provider_id,
        ):
            return RegistrationBehaviour.ALLOW  # allow all registrations

        async def check_media_file_for_spam(self, file_wrapper, file_info):
            return False  # allow all media

## Configuration

Modify the `spam_checker` section of your `homeserver.yaml` in the following manner:

Create a list entry with the keys `module` and `config`.

- `module` should point to the fully qualified Python class that implements your custom logic, e.g. `my_module.ExampleSpamChecker`.

- `config` is a dictionary that gets passed to the spam checker class.

### Example

This section might look like:

    spam_checker:
      - module: my_module.ExampleSpamChecker
        config:
          # Enable or disable a specific option in ExampleSpamChecker.
          my_custom_option: true

More spam checkers can be added in tandem by appending more items to the list. An action is blocked when at least one of the configured spam checkers flags it.

## Examples

The Mjolnir project is a full fledged example using the Synapse spam checking API, including a bot for dynamic configuration.