1 files changed, 40 insertions, 15 deletions
diff --git a/develop/print.html b/develop/print.html
index 154a6789f0..150dc0f29c 100644
--- a/develop/print.html
+++ b/develop/print.html
@@ -3073,20 +3073,6 @@ presence:
   #
   #enabled: false
 
-  # Presence routers are third-party modules that can specify additional logic
-  # to where presence updates from users are routed.
-  #
-  presence_router:
-    # The custom module's class. Uncomment to use a custom presence router module.
-    #
-    #module: &quot;my_custom_router.PresenceRouter&quot;
-
-    # Configuration options of the custom module. Refer to your module's
-    # documentation for available options.
-    #
-    #config:
-    #  example_option: 'something'
-
 # Whether to require authentication to retrieve profile data (avatars,
 # display names) of other users through the client API. Defaults to
 # 'false'. Note that profile data is also available via the federation
@@ -7582,6 +7568,40 @@ for a list of possible parameters), and a boolean indicating whether the user pe
 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>
+<h4 id="presence-router-callbacks"><a class="header" href="#presence-router-callbacks">Presence router callbacks</a></h4>
+<p>Presence router callbacks allow module developers to specify additional users (local or remote)
+to receive certain presence updates from local users. Presence router callbacks can be 
+registered using the module API's <code>register_presence_router_callbacks</code> method.</p>
+<p>The available presence router callbacks are:</p>
+<pre><code class="language-python">async def get_users_for_states(
+    self,
+    state_updates: Iterable[&quot;synapse.api.UserPresenceState&quot;],
+) -&gt; Dict[str, Set[&quot;synapse.api.UserPresenceState&quot;]]:
+</code></pre>
+<p><strong>Requires</strong> <code>get_interested_users</code> to also be registered</p>
+<p>Called when processing updates to the presence state of one or more users. This callback can
+be used to instruct the server to forward that presence state to specific users. The module
+must return a dictionary that maps from Matrix user IDs (which can be local or remote) to the
+<code>UserPresenceState</code> changes that they should be forwarded.</p>
+<p>Synapse will then attempt to send the specified presence updates to each user when possible.</p>
+<pre><code class="language-python">async def get_interested_users(
+        self, 
+        user_id: str
+) -&gt; Union[Set[str], &quot;synapse.module_api.PRESENCE_ALL_USERS&quot;]
+</code></pre>
+<p><strong>Requires</strong> <code>get_users_for_states</code> to also be registered</p>
+<p>Called when determining which users someone should be able to see the presence state of. This
+callback should return complementary results to <code>get_users_for_state</code> or the presence information 
+may not be properly forwarded.</p>
+<p>The callback is given the Matrix user ID for a local user that is requesting presence data and
+should return the Matrix user IDs of the users whose presence state they are allowed to
+query. The returned users can be local or remote. </p>
+<p>Alternatively the callback can return <code>synapse.module_api.PRESENCE_ALL_USERS</code>
+to indicate that the user should receive updates from all known users.</p>
+<p>For example, if the user <code>@alice:example.org</code> is passed to this method, and the Set 
+<code>{&quot;@bob:example.com&quot;, &quot;@charlie:somewhere.org&quot;}</code> is returned, this signifies that Alice 
+should receive presence updates sent by Bob and Charlie, regardless of whether these users 
+share a room.</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>
@@ -7749,7 +7769,12 @@ action is blocked when at least one of the configured spam checkers flags it.</p
 <p>The <a href="https://github.com/matrix-org/mjolnir">Mjolnir</a> project is a full fledged
 example using the Synapse spam checking API, including a bot for dynamic
 configuration.</p>
-<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="presence-router-module"><a class="header" href="#presence-router-module">Presence Router Module</a></h1>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h2 style="color:red">
+This page of the Synapse documentation is now deprecated. For up to date
+documentation on setting up or writing a presence router module, please see
+<a href="modules.html">this page</a>.
+</h2>
+<h1 id="presence-router-module"><a class="header" href="#presence-router-module">Presence Router Module</a></h1>
 <p>Synapse supports configuring a module that can specify additional users
 (local or remote) to should receive certain presence updates from local
 users.</p>