<!DOCTYPE HTML> <html lang="en" class="sidebar-visible no-js light"> <head> <!-- Book generated using mdBook --> <meta charset="UTF-8"> <title>Pluggable Modules - Synapse</title> <!-- Custom HTML head --> <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="theme-color" content="#ffffff" /> <link rel="icon" href="favicon.svg"> <link rel="shortcut icon" href="favicon.png"> <link rel="stylesheet" href="css/variables.css"> <link rel="stylesheet" href="css/general.css"> <link rel="stylesheet" href="css/chrome.css"> <link rel="stylesheet" href="css/print.css" media="print"> <!-- Fonts --> <link rel="stylesheet" href="FontAwesome/css/font-awesome.css"> <link rel="stylesheet" href="fonts/fonts.css"> <!-- Highlight.js Stylesheets --> <link rel="stylesheet" href="highlight.css"> <link rel="stylesheet" href="tomorrow-night.css"> <link rel="stylesheet" href="ayu-highlight.css"> <!-- Custom theme stylesheets --> <link rel="stylesheet" href="docs/website_files/table-of-contents.css"> <link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css"> <link rel="stylesheet" href="docs/website_files/indent-section-headers.css"> <link rel="stylesheet" href="docs/website_files/version-picker.css"> </head> <body> <!-- Provide site root to javascript --> <script type="text/javascript"> var path_to_root = ""; var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light"; </script> <!-- Work around some values being stored in localStorage wrapped in quotes --> <script type="text/javascript"> try { var theme = localStorage.getItem('mdbook-theme'); var sidebar = localStorage.getItem('mdbook-sidebar'); if (theme.startsWith('"') && theme.endsWith('"')) { localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); } if (sidebar.startsWith('"') && sidebar.endsWith('"')) { localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); } } catch (e) { } </script> <!-- Set the theme before any content is loaded, prevents flash --> <script type="text/javascript"> var theme; try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } if (theme === null || theme === undefined) { theme = default_theme; } var html = document.querySelector('html'); html.classList.remove('no-js') html.classList.remove('light') html.classList.add(theme); html.classList.add('js'); </script> <!-- Hide / unhide sidebar before it is displayed --> <script type="text/javascript"> var html = document.querySelector('html'); var sidebar = 'hidden'; if (document.body.clientWidth >= 1080) { try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } sidebar = sidebar || 'visible'; } html.classList.remove('sidebar-visible'); html.classList.add("sidebar-" + sidebar); </script> <nav id="sidebar" class="sidebar" aria-label="Table of contents"> <div class="sidebar-scrollbox"> <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules.html" class="active">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/shutdown_room.html">Shutdown Room</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="dev/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="dev/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol> </div> <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div> </nav> <div id="page-wrapper" class="page-wrapper"> <div class="page"> <div id="menu-bar-hover-placeholder"></div> <div id="menu-bar" class="menu-bar sticky bordered"> <div class="left-buttons"> <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> <i class="fa fa-bars"></i> </button> <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list"> <i class="fa fa-paint-brush"></i> </button> <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li> <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> </ul> <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar"> <i class="fa fa-search"></i> </button> <div class="version-picker"> <div class="dropdown"> <div class="select"> <span></span> <i class="fa fa-chevron-down"></i> </div> <input type="hidden" name="version"> <ul class="dropdown-menu"> <!-- Versions will be added dynamically in version-picker.js --> </ul> </div> </div> </div> <h1 class="menu-title">Synapse</h1> <div class="right-buttons"> <a href="print.html" title="Print this book" aria-label="Print this book"> <i id="print-button" class="fa fa-print"></i> </a> <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository"> <i id="git-repository-button" class="fa fa-github"></i> </a> <a href="https://github.com/matrix-org/synapse/edit/develop/docs/modules.md" title="Suggest an edit" aria-label="Suggest an edit"> <i id="git-edit-button" class="fa fa-edit"></i> </a> </div> </div> <div id="search-wrapper" class="hidden"> <form id="searchbar-outer" class="searchbar-outer"> <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> </form> <div id="searchresults-outer" class="searchresults-outer hidden"> <div id="searchresults-header" class="searchresults-header"></div> <ul id="searchresults"> </ul> </div> </div> <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> <script type="text/javascript"> document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); }); </script> <div id="content" class="content"> <main> <!-- Page table of contents --> <div class="sidetoc"> <nav class="pagetoc"></nav> </div> <h1 id="modules"><a class="header" href="#modules">Modules</a></h1> <p>Synapse supports extending its functionality by configuring external modules.</p> <h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2> <p>To use a module on Synapse, add it to the <code>modules</code> section of the configuration file:</p> <pre><code class="language-yaml">modules: - module: my_super_module.MySuperClass config: do_thing: true - module: my_other_super_module.SomeClass config: {} </code></pre> <p>Each module is defined by a path to a Python class as well as a configuration. This information for a given module should be available in the module's own documentation.</p> <p><strong>Note</strong>: When using third-party modules, you effectively allow someone else to run custom code on your Synapse homeserver. Server admins are encouraged to verify the provenance of the modules they use on their homeserver and make sure the modules aren't running malicious code on their instance.</p> <p>Also note that we are currently in the process of migrating module interfaces to this system. While some interfaces might be compatible with it, others still require configuring modules in another part of Synapse's configuration file. Currently, only the spam checker interface is compatible with this new system.</p> <h2 id="writing-a-module"><a class="header" href="#writing-a-module">Writing a module</a></h2> <p>A module is a Python class that uses Synapse's module API to interact with the homeserver. It can register callbacks that Synapse will call on specific operations, as well as web resources to attach to Synapse's web server.</p> <p>When instantiated, a module is given its parsed configuration as well as an instance of the <code>synapse.module_api.ModuleApi</code> class. The configuration is a dictionary, and is either the output of the module's <code>parse_config</code> static method (see below), or the configuration associated with the module in Synapse's configuration file.</p> <p>See the documentation for the <code>ModuleApi</code> class <a href="https://github.com/matrix-org/synapse/blob/master/synapse/module_api/__init__.py">here</a>.</p> <h3 id="handling-the-modules-configuration"><a class="header" href="#handling-the-modules-configuration">Handling the module's configuration</a></h3> <p>A module can implement the following static method:</p> <pre><code class="language-python">@staticmethod def parse_config(config: dict) -> dict </code></pre> <p>This method is given a dictionary resulting from parsing the YAML configuration for the module. It may modify it (for example by parsing durations expressed as strings (e.g. "5d") into milliseconds, etc.), and return the modified dictionary. It may also verify that the configuration is correct, and raise an instance of <code>synapse.module_api.errors.ConfigError</code> if not.</p> <h3 id="registering-a-web-resource"><a class="header" href="#registering-a-web-resource">Registering a web resource</a></h3> <p>Modules can register web resources onto Synapse's web server using the following module API method:</p> <pre><code class="language-python">def ModuleApi.register_web_resource(path: str, resource: IResource) -> None </code></pre> <p>The path is the full absolute path to register the resource at. For example, if you register a resource for the path <code>/_synapse/client/my_super_module/say_hello</code>, Synapse will serve it at <code>http(s)://[HS_URL]/_synapse/client/my_super_module/say_hello</code>. Note that Synapse does not allow registering resources for several sub-paths in the <code>/_matrix</code> namespace (such as anything under <code>/_matrix/client</code> for example). It is strongly recommended that modules register their web resources under the <code>/_synapse/client</code> namespace.</p> <p>The provided resource is a Python class that implements Twisted's <a href="https://twistedmatrix.com/documents/current/api/twisted.web.resource.IResource.html">IResource</a> interface (such as <a href="https://twistedmatrix.com/documents/current/api/twisted.web.resource.Resource.html">Resource</a>).</p> <p>Only one resource can be registered for a given path. If several modules attempt to register a resource for the same path, the module that appears first in Synapse's configuration file takes priority.</p> <p>Modules <strong>must</strong> register their web resources in their <code>__init__</code> method.</p> <h3 id="registering-a-callback"><a class="header" href="#registering-a-callback">Registering a callback</a></h3> <p>Modules can use Synapse's module API to register callbacks. Callbacks are functions that Synapse will call when performing specific actions. Callbacks must be asynchronous, and are split in categories. A single module may implement callbacks from multiple categories, and is under no obligation to implement all callbacks from the categories it registers callbacks for.</p> <p>Modules can register callbacks using one of the module API's <code>register_[...]_callbacks</code> methods. The callback functions are passed to these methods as keyword arguments, with the callback name as the argument name and the function as its value. This is demonstrated in the example below. A <code>register_[...]_callbacks</code> method exists for each module type documented in this section.</p> <h4 id="spam-checker-callbacks"><a class="header" href="#spam-checker-callbacks">Spam checker callbacks</a></h4> <p>Spam checker callbacks allow module developers to implement spam mitigation actions for Synapse instances. Spam checker callbacks can be registered using the module API's <code>register_spam_checker_callbacks</code> method.</p> <p>The available spam checker callbacks are:</p> <pre><code class="language-python">async def check_event_for_spam(event: "synapse.events.EventBase") -> Union[bool, str] </code></pre> <p>Called when receiving an event from a client or via federation. The module can return either a <code>bool</code> to indicate whether the event must be rejected because of spam, or a <code>str</code> to indicate the event must be rejected because of spam and to give a rejection reason to forward to clients.</p> <pre><code class="language-python">async def user_may_invite(inviter: str, invitee: str, room_id: str) -> bool </code></pre> <p>Called when processing an invitation. The module must return a <code>bool</code> indicating whether the inviter can invite the invitee to the given room. Both inviter and invitee are represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p> <pre><code class="language-python">async def user_may_create_room(user: str) -> bool </code></pre> <p>Called when processing a room creation request. The module must return a <code>bool</code> indicating whether the given user (represented by their Matrix user ID) is allowed to create a room.</p> <pre><code class="language-python">async def user_may_create_room_alias(user: str, room_alias: "synapse.types.RoomAlias") -> bool </code></pre> <p>Called when trying to associate an alias with an existing room. The module must return a <code>bool</code> indicating whether the given user (represented by their Matrix user ID) is allowed to set the given alias.</p> <pre><code class="language-python">async def user_may_publish_room(user: str, room_id: str) -> bool </code></pre> <p>Called when trying to publish a room to the homeserver's public rooms directory. The module must return a <code>bool</code> indicating whether the given user (represented by their Matrix user ID) is allowed to publish the given room.</p> <pre><code class="language-python">async def check_username_for_spam(user_profile: Dict[str, str]) -> bool </code></pre> <p>Called when computing search results in the user directory. The module must return a <code>bool</code> indicating whether the given user profile can appear in search results. The profile is represented as a dictionary with the following keys:</p> <ul> <li><code>user_id</code>: The Matrix ID for this user.</li> <li><code>display_name</code>: The user's display name.</li> <li><code>avatar_url</code>: The <code>mxc://</code> URL to the user's avatar.</li> </ul> <p>The module is given a copy of the original dictionary, so modifying it from within the module cannot modify a user's profile when included in user directory search results.</p> <pre><code class="language-python">async def check_registration_for_spam( email_threepid: Optional[dict], username: Optional[str], request_info: Collection[Tuple[str, str]], auth_provider_id: Optional[str] = None, ) -> "synapse.spam_checker_api.RegistrationBehaviour" </code></pre> <p>Called when registering a new user. The module must return a <code>RegistrationBehaviour</code> indicating whether the registration can go through or must be denied, or whether the user may be allowed to register but will be shadow banned.</p> <p>The arguments passed to this callback are:</p> <ul> <li><code>email_threepid</code>: The email address used for registering, if any.</li> <li><code>username</code>: The username the user would like to register. Can be <code>None</code>, meaning that Synapse will generate one later.</li> <li><code>request_info</code>: A collection of tuples, which first item is a user agent, and which second item is an IP address. These user agents and IP addresses are the ones that were used during the registration process.</li> <li><code>auth_provider_id</code>: The identifier of the SSO authentication provider, if any.</li> </ul> <pre><code class="language-python">async def check_media_file_for_spam( file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper", file_info: "synapse.rest.media.v1._base.FileInfo", ) -> bool </code></pre> <p>Called when storing a local or remote file. The module must return a boolean indicating whether the given file can be stored in the homeserver's media store.</p> <h4 id="account-validity-callbacks"><a class="header" href="#account-validity-callbacks">Account validity callbacks</a></h4> <p>Account validity callbacks allow module developers to add extra steps to verify the validity on an account, i.e. see if a user can be granted access to their account on the Synapse instance. Account validity callbacks can be registered using the module API's <code>register_account_validity_callbacks</code> method.</p> <p>The available account validity callbacks are:</p> <pre><code class="language-python">async def is_user_expired(user: str) -> Optional[bool] </code></pre> <p>Called when processing any authenticated request (except for logout requests). The module can return a <code>bool</code> to indicate whether the user has expired and should be locked out of their account, or <code>None</code> if the module wasn't able to figure it out. The user is represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p> <p>If the module returns <code>True</code>, the current request will be denied with the error code <code>ORG_MATRIX_EXPIRED_ACCOUNT</code> and the HTTP status code 403. Note that this doesn't invalidate the user's access token.</p> <pre><code class="language-python">async def on_user_registration(user: str) -> None </code></pre> <p>Called after successfully registering a user, in case the module needs to perform extra operations to keep track of them. (e.g. add them to a database table). The user is represented by their Matrix user ID.</p> <h4 id="third-party-rules-callbacks"><a class="header" href="#third-party-rules-callbacks">Third party rules callbacks</a></h4> <p>Third party rules callbacks allow module developers to add extra checks to verify the validity of incoming events. Third party event rules callbacks can be registered using the module API's <code>register_third_party_rules_callbacks</code> method.</p> <p>The available third party rules callbacks are:</p> <pre><code class="language-python">async def check_event_allowed( event: "synapse.events.EventBase", state_events: "synapse.types.StateMap", ) -> Tuple[bool, Optional[dict]] </code></pre> <p><strong><span style="color:red"> This callback is very experimental and can and will break without notice. Module developers are encouraged to implement <code>check_event_for_spam</code> from the spam checker category instead. </span></strong></p> <p>Called when processing any incoming event, with the event and a <code>StateMap</code> representing the current state of the room the event is being sent into. A <code>StateMap</code> is a dictionary that maps tuples containing an event type and a state key to the corresponding state event. For example retrieving the room's <code>m.room.create</code> event from the <code>state_events</code> argument would look like this: <code>state_events.get(("m.room.create", ""))</code>. The module must return a boolean indicating whether the event can be allowed.</p> <p>Note that this callback function processes incoming events coming via federation traffic (on top of client traffic). This means denying an event might cause the local copy of the room's history to diverge from that of remote servers. This may cause federation issues in the room. It is strongly recommended to only deny events using this callback function if the sender is a local user, or in a private federation in which all servers are using the same module, with the same configuration.</p> <p>If the boolean returned by the module is <code>True</code>, it may also tell Synapse to replace the event with new data by returning the new event's data as a dictionary. In order to do that, it is recommended the module calls <code>event.get_dict()</code> to get the current event as a dictionary, and modify the returned dictionary accordingly.</p> <p>Note that replacing the event only works for events sent by local users, not for events received over federation.</p> <pre><code class="language-python">async def on_create_room( requester: "synapse.types.Requester", request_content: dict, is_requester_admin: bool, ) -> None </code></pre> <p>Called when processing a room creation request, with the <code>Requester</code> object for the user performing the request, a dictionary representing the room creation request's JSON body (see <a href="https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-createroom">the spec</a> for a list of possible parameters), and a boolean indicating whether the user performing the request is a server admin.</p> <p>Modules can modify the <code>request_content</code> (by e.g. adding events to its <code>initial_state</code>), or deny the room's creation by raising a <code>module_api.errors.SynapseError</code>.</p> <h3 id="porting-an-existing-module-that-uses-the-old-interface"><a class="header" href="#porting-an-existing-module-that-uses-the-old-interface">Porting an existing module that uses the old interface</a></h3> <p>In order to port a module that uses Synapse's old module interface, its author needs to:</p> <ul> <li>ensure the module's callbacks are all asynchronous.</li> <li>register their callbacks using one or more of the <code>register_[...]_callbacks</code> methods from the <code>ModuleApi</code> class in the module's <code>__init__</code> method (see <a href="#registering-a-callback">this section</a> for more info).</li> </ul> <p>Additionally, if the module is packaged with an additional web resource, the module should register this resource in its <code>__init__</code> method using the <code>register_web_resource</code> method from the <code>ModuleApi</code> class (see <a href="#registering-a-web-resource">this section</a> for more info).</p> <p>The module's author should also update any example in the module's configuration to only use the new <code>modules</code> section in Synapse's configuration file (see <a href="#using-modules">this section</a> for more info).</p> <h3 id="example"><a class="header" href="#example">Example</a></h3> <p>The example below is a module that implements the spam checker callback <code>user_may_create_room</code> to deny room creation to user <code>@evilguy:example.com</code>, and registers a web resource to the path <code>/_synapse/client/demo/hello</code> that returns a JSON object.</p> <pre><code class="language-python">import json from twisted.web.resource import Resource from twisted.web.server import Request from synapse.module_api import ModuleApi class DemoResource(Resource): def __init__(self, config): super(DemoResource, self).__init__() self.config = config def render_GET(self, request: Request): name = request.args.get(b"name")[0] request.setHeader(b"Content-Type", b"application/json") return json.dumps({"hello": name}) class DemoModule: def __init__(self, config: dict, api: ModuleApi): self.config = config self.api = api self.api.register_web_resource( path="/_synapse/client/demo/hello", resource=DemoResource(self.config), ) self.api.register_spam_checker_callbacks( user_may_create_room=self.user_may_create_room, ) @staticmethod def parse_config(config): return config async def user_may_create_room(self, user: str) -> bool: if user == "@evilguy:example.com": return False return True </code></pre> </main> <nav class="nav-wrapper" aria-label="Page navigation"> <!-- Mobile navigation buttons --> <a rel="prev" href="message_retention_policies.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> <i class="fa fa-angle-left"></i> </a> <a rel="next" href="spam_checker.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> <i class="fa fa-angle-right"></i> </a> <div style="clear: both"></div> </nav> </div> </div> <nav class="nav-wide-wrapper" aria-label="Page navigation"> <a rel="prev" href="message_retention_policies.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> <i class="fa fa-angle-left"></i> </a> <a rel="next" href="spam_checker.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> <i class="fa fa-angle-right"></i> </a> </nav> </div> <script type="text/javascript"> window.playground_copyable = true; </script> <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script> <script src="mark.min.js" type="text/javascript" charset="utf-8"></script> <script src="searcher.js" type="text/javascript" charset="utf-8"></script> <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script> <script src="highlight.js" type="text/javascript" charset="utf-8"></script> <script src="book.js" type="text/javascript" charset="utf-8"></script> <!-- Custom JS scripts --> <script type="text/javascript" src="docs/website_files/table-of-contents.js"></script> <script type="text/javascript" src="docs/website_files/version-picker.js"></script> <script type="text/javascript" src="docs/website_files/version.js"></script> </body> </html>