templates.html 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486
  1. <!DOCTYPE HTML>
  2. <html lang="en" class="sidebar-visible no-js light">
  3. <head>
  4. <!-- Book generated using mdBook -->
  5. <meta charset="UTF-8">
  6. <title>Templates - Synapse</title>
  7. <!-- Custom HTML head -->
  8. <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  9. <meta name="description" content="">
  10. <meta name="viewport" content="width=device-width, initial-scale=1">
  11. <meta name="theme-color" content="#ffffff" />
  12. <link rel="icon" href="favicon.svg">
  13. <link rel="shortcut icon" href="favicon.png">
  14. <link rel="stylesheet" href="css/variables.css">
  15. <link rel="stylesheet" href="css/general.css">
  16. <link rel="stylesheet" href="css/chrome.css">
  17. <link rel="stylesheet" href="css/print.css" media="print">
  18. <!-- Fonts -->
  19. <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
  20. <link rel="stylesheet" href="fonts/fonts.css">
  21. <!-- Highlight.js Stylesheets -->
  22. <link rel="stylesheet" href="highlight.css">
  23. <link rel="stylesheet" href="tomorrow-night.css">
  24. <link rel="stylesheet" href="ayu-highlight.css">
  25. <!-- Custom theme stylesheets -->
  26. <link rel="stylesheet" href="docs/website_files/table-of-contents.css">
  27. <link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css">
  28. <link rel="stylesheet" href="docs/website_files/indent-section-headers.css">
  29. <link rel="stylesheet" href="docs/website_files/version-picker.css">
  30. </head>
  31. <body>
  32. <!-- Provide site root to javascript -->
  33. <script type="text/javascript">
  34. var path_to_root = "";
  35. var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
  36. </script>
  37. <!-- Work around some values being stored in localStorage wrapped in quotes -->
  38. <script type="text/javascript">
  39. try {
  40. var theme = localStorage.getItem('mdbook-theme');
  41. var sidebar = localStorage.getItem('mdbook-sidebar');
  42. if (theme.startsWith('"') && theme.endsWith('"')) {
  43. localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
  44. }
  45. if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
  46. localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
  47. }
  48. } catch (e) { }
  49. </script>
  50. <!-- Set the theme before any content is loaded, prevents flash -->
  51. <script type="text/javascript">
  52. var theme;
  53. try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
  54. if (theme === null || theme === undefined) { theme = default_theme; }
  55. var html = document.querySelector('html');
  56. html.classList.remove('no-js')
  57. html.classList.remove('light')
  58. html.classList.add(theme);
  59. html.classList.add('js');
  60. </script>
  61. <!-- Hide / unhide sidebar before it is displayed -->
  62. <script type="text/javascript">
  63. var html = document.querySelector('html');
  64. var sidebar = 'hidden';
  65. if (document.body.clientWidth >= 1080) {
  66. try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
  67. sidebar = sidebar || 'visible';
  68. }
  69. html.classList.remove('sidebar-visible');
  70. html.classList.add("sidebar-" + sidebar);
  71. </script>
  72. <nav id="sidebar" class="sidebar" aria-label="Table of contents">
  73. <div class="sidebar-scrollbox">
  74. <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="setup/forward_proxy.html">Configuring a Forward/Outbound 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 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/config_documentation.html">Configuration Manual</a></li><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="templates.html" class="active">Templates</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 "><a href="usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></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><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/refresh_tokens.html">Refresh 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="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/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_data_callbacks.html">Account data callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></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="usage/administration/admin_api/background_updates.html">Background Updates</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/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</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/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><li class="chapter-item expanded "><a href="usage/administration/admin_api/federation.html">Federation</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><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/monitoring/reporting_homeserver_usage_statistics.html">Reporting Homeserver Usage Statistics</a></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_faq.html">Admin FAQ</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="development/reviews.html">Reviewing Code</a></li><li class="chapter-item expanded "><a href="development/releases.html">Release Cycle</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/demo.html">Demo scripts</a></li></ol></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 "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><a href="development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/synapse_architecture/cancellation.html">Cancellation</a></li><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="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></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><li class="chapter-item expanded "><a href="other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</a></li></ol>
  75. </div>
  76. <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
  77. </nav>
  78. <div id="page-wrapper" class="page-wrapper">
  79. <div class="page">
  80. <div id="menu-bar-hover-placeholder"></div>
  81. <div id="menu-bar" class="menu-bar sticky bordered">
  82. <div class="left-buttons">
  83. <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
  84. <i class="fa fa-bars"></i>
  85. </button>
  86. <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">
  87. <i class="fa fa-paint-brush"></i>
  88. </button>
  89. <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
  90. <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
  91. <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
  92. <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
  93. <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
  94. <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
  95. </ul>
  96. <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">
  97. <i class="fa fa-search"></i>
  98. </button>
  99. <div class="version-picker">
  100. <div class="dropdown">
  101. <div class="select">
  102. <span></span>
  103. <i class="fa fa-chevron-down"></i>
  104. </div>
  105. <input type="hidden" name="version">
  106. <ul class="dropdown-menu">
  107. <!-- Versions will be added dynamically in version-picker.js -->
  108. </ul>
  109. </div>
  110. </div>
  111. </div>
  112. <h1 class="menu-title">Synapse</h1>
  113. <div class="right-buttons">
  114. <a href="print.html" title="Print this book" aria-label="Print this book">
  115. <i id="print-button" class="fa fa-print"></i>
  116. </a>
  117. <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
  118. <i id="git-repository-button" class="fa fa-github"></i>
  119. </a>
  120. <a href="https://github.com/matrix-org/synapse/edit/develop/docs/templates.md" title="Suggest an edit" aria-label="Suggest an edit">
  121. <i id="git-edit-button" class="fa fa-edit"></i>
  122. </a>
  123. </div>
  124. </div>
  125. <div id="search-wrapper" class="hidden">
  126. <form id="searchbar-outer" class="searchbar-outer">
  127. <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
  128. </form>
  129. <div id="searchresults-outer" class="searchresults-outer hidden">
  130. <div id="searchresults-header" class="searchresults-header"></div>
  131. <ul id="searchresults">
  132. </ul>
  133. </div>
  134. </div>
  135. <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
  136. <script type="text/javascript">
  137. document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
  138. document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
  139. Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
  140. link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
  141. });
  142. </script>
  143. <div id="content" class="content">
  144. <main>
  145. <!-- Page table of contents -->
  146. <div class="sidetoc">
  147. <nav class="pagetoc"></nav>
  148. </div>
  149. <h1 id="templates"><a class="header" href="#templates">Templates</a></h1>
  150. <p>Synapse uses parametrised templates to generate the content of emails it sends and
  151. webpages it shows to users.</p>
  152. <p>By default, Synapse will use the templates listed <a href="https://github.com/matrix-org/synapse/tree/master/synapse/res/templates">here</a>.
  153. Server admins can configure an additional directory for Synapse to look for templates
  154. in, allowing them to specify custom templates:</p>
  155. <pre><code class="language-yaml">templates:
  156. custom_templates_directory: /path/to/custom/templates/
  157. </code></pre>
  158. <p>If this setting is not set, or the files named below are not found within the directory,
  159. default templates from within the Synapse package will be used.</p>
  160. <p>Templates that are given variables when being rendered are rendered using <a href="https://jinja.palletsprojects.com/en/2.11.x/">Jinja 2</a>.
  161. Templates rendered by Jinja 2 can also access two functions on top of the functions
  162. already available as part of Jinja 2:</p>
  163. <pre><code class="language-python">format_ts(value: int, format: str) -&gt; str
  164. </code></pre>
  165. <p>Formats a timestamp in milliseconds.</p>
  166. <p>Example: <code>reason.last_sent_ts|format_ts(&quot;%c&quot;)</code></p>
  167. <pre><code class="language-python">mxc_to_http(value: str, width: int, height: int, resize_method: str = &quot;crop&quot;) -&gt; str
  168. </code></pre>
  169. <p>Turns a <code>mxc://</code> URL for media content into an HTTP(S) one using the homeserver's
  170. <code>public_baseurl</code> configuration setting as the URL's base.</p>
  171. <p>Example: <code>message.sender_avatar_url|mxc_to_http(32,32)</code></p>
  172. <pre><code class="language-python">localpart_from_email(address: str) -&gt; str
  173. </code></pre>
  174. <p>Returns the local part of an email address (e.g. <code>alice</code> in <code>alice@example.com</code>).</p>
  175. <p>Example: <code>user.email_address|localpart_from_email</code></p>
  176. <h2 id="email-templates"><a class="header" href="#email-templates">Email templates</a></h2>
  177. <p>Below are the templates Synapse will look for when generating the content of an email:</p>
  178. <ul>
  179. <li><code>notif_mail.html</code> and <code>notif_mail.txt</code>: The contents of email notifications of missed
  180. events.
  181. When rendering, this template is given the following variables:
  182. <ul>
  183. <li><code>user_display_name</code>: the display name for the user receiving the notification</li>
  184. <li><code>unsubscribe_link</code>: the link users can click to unsubscribe from email notifications</li>
  185. <li><code>summary_text</code>: a summary of the notification(s). The text used can be customised
  186. by configuring the various settings in the <code>email.subjects</code> section of the
  187. configuration file.</li>
  188. <li><code>rooms</code>: a list of rooms containing events to include in the email. Each element is
  189. an object with the following attributes:
  190. <ul>
  191. <li><code>title</code>: a human-readable name for the room</li>
  192. <li><code>hash</code>: a hash of the ID of the room</li>
  193. <li><code>invite</code>: a boolean, which is <code>True</code> if the room is an invite the user hasn't
  194. accepted yet, <code>False</code> otherwise</li>
  195. <li><code>notifs</code>: a list of events, or an empty list if <code>invite</code> is <code>True</code>. Each element
  196. is an object with the following attributes:
  197. <ul>
  198. <li><code>link</code>: a <code>matrix.to</code> link to the event</li>
  199. <li><code>ts</code>: the time in milliseconds at which the event was received</li>
  200. <li><code>messages</code>: a list of messages containing one message before the event, the
  201. message in the event, and one message after the event. Each element is an
  202. object with the following attributes:
  203. <ul>
  204. <li><code>event_type</code>: the type of the event</li>
  205. <li><code>is_historical</code>: a boolean, which is <code>False</code> if the message is the one
  206. that triggered the notification, <code>True</code> otherwise</li>
  207. <li><code>id</code>: the ID of the event</li>
  208. <li><code>ts</code>: the time in milliseconds at which the event was sent</li>
  209. <li><code>sender_name</code>: the display name for the event's sender</li>
  210. <li><code>sender_avatar_url</code>: the avatar URL (as a <code>mxc://</code> URL) for the event's
  211. sender</li>
  212. <li><code>sender_hash</code>: a hash of the user ID of the sender</li>
  213. <li><code>msgtype</code>: the type of the message</li>
  214. <li><code>body_text_html</code>: html representation of the message</li>
  215. <li><code>body_text_plain</code>: plaintext representation of the message</li>
  216. <li><code>image_url</code>: mxc url of an image, when &quot;msgtype&quot; is &quot;m.image&quot;</li>
  217. </ul>
  218. </li>
  219. </ul>
  220. </li>
  221. <li><code>link</code>: a <code>matrix.to</code> link to the room</li>
  222. <li><code>avator_url</code>: url to the room's avator</li>
  223. </ul>
  224. </li>
  225. <li><code>reason</code>: information on the event that triggered the email to be sent. It's an
  226. object with the following attributes:
  227. <ul>
  228. <li><code>room_id</code>: the ID of the room the event was sent in</li>
  229. <li><code>room_name</code>: a human-readable name for the room the event was sent in</li>
  230. <li><code>now</code>: the current time in milliseconds</li>
  231. <li><code>received_at</code>: the time in milliseconds at which the event was received</li>
  232. <li><code>delay_before_mail_ms</code>: the amount of time in milliseconds Synapse always waits
  233. before ever emailing about a notification (to give the user a chance to respond
  234. to other push or notice the window)</li>
  235. <li><code>last_sent_ts</code>: the time in milliseconds at which a notification was last sent
  236. for an event in this room</li>
  237. <li><code>throttle_ms</code>: the minimum amount of time in milliseconds between two
  238. notifications can be sent for this room</li>
  239. </ul>
  240. </li>
  241. </ul>
  242. </li>
  243. <li><code>password_reset.html</code> and <code>password_reset.txt</code>: The contents of password reset emails
  244. sent by the homeserver.
  245. When rendering, these templates are given a <code>link</code> variable which contains the link the
  246. user must click in order to reset their password.</li>
  247. <li><code>registration.html</code> and <code>registration.txt</code>: The contents of address verification emails
  248. sent during registration.
  249. When rendering, these templates are given a <code>link</code> variable which contains the link the
  250. user must click in order to validate their email address.</li>
  251. <li><code>add_threepid.html</code> and <code>add_threepid.txt</code>: The contents of address verification emails
  252. sent when an address is added to a Matrix account.
  253. When rendering, these templates are given a <code>link</code> variable which contains the link the
  254. user must click in order to validate their email address.</li>
  255. </ul>
  256. <h2 id="html-page-templates-for-registration-and-password-reset"><a class="header" href="#html-page-templates-for-registration-and-password-reset">HTML page templates for registration and password reset</a></h2>
  257. <p>Below are the templates Synapse will look for when generating pages related to
  258. registration and password reset:</p>
  259. <ul>
  260. <li><code>password_reset_confirmation.html</code>: An HTML page that a user will see when they follow
  261. the link in the password reset email. The user will be asked to confirm the action
  262. before their password is reset.
  263. When rendering, this template is given the following variables:
  264. <ul>
  265. <li><code>sid</code>: the session ID for the password reset</li>
  266. <li><code>token</code>: the token for the password reset</li>
  267. <li><code>client_secret</code>: the client secret for the password reset</li>
  268. </ul>
  269. </li>
  270. <li><code>password_reset_success.html</code> and <code>password_reset_failure.html</code>: HTML pages for success
  271. and failure that a user will see when they confirm the password reset flow using the
  272. page above.
  273. When rendering, <code>password_reset_success.html</code> is given no variable, and
  274. <code>password_reset_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
  275. for the password reset failure. </li>
  276. <li><code>registration_success.html</code> and <code>registration_failure.html</code>: HTML pages for success and
  277. failure that a user will see when they follow the link in an address verification email
  278. sent during registration.
  279. When rendering, <code>registration_success.html</code> is given no variable, and
  280. <code>registration_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
  281. for the registration failure.</li>
  282. <li><code>add_threepid_success.html</code> and <code>add_threepid_failure.html</code>: HTML pages for success and
  283. failure that a user will see when they follow the link in an address verification email
  284. sent when an address is added to a Matrix account.
  285. When rendering, <code>add_threepid_success.html</code> is given no variable, and
  286. <code>add_threepid_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
  287. for the registration failure.</li>
  288. </ul>
  289. <h2 id="html-page-templates-for-single-sign-on-sso"><a class="header" href="#html-page-templates-for-single-sign-on-sso">HTML page templates for Single Sign-On (SSO)</a></h2>
  290. <p>Below are the templates Synapse will look for when generating pages related to SSO:</p>
  291. <ul>
  292. <li><code>sso_login_idp_picker.html</code>: HTML page to prompt the user to choose an
  293. Identity Provider during login.
  294. This is only used if multiple SSO Identity Providers are configured.
  295. When rendering, this template is given the following variables:
  296. <ul>
  297. <li><code>redirect_url</code>: the URL that the user will be redirected to after
  298. login.</li>
  299. <li><code>server_name</code>: the homeserver's name.</li>
  300. <li><code>providers</code>: a list of available Identity Providers. Each element is
  301. an object with the following attributes:
  302. <ul>
  303. <li><code>idp_id</code>: unique identifier for the IdP</li>
  304. <li><code>idp_name</code>: user-facing name for the IdP</li>
  305. <li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
  306. for the IdP</li>
  307. <li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
  308. for the brand of the IdP
  309. The rendered HTML page should contain a form which submits its results
  310. back as a GET request, with the following query parameters:</li>
  311. </ul>
  312. </li>
  313. <li><code>redirectUrl</code>: the client redirect URI (ie, the <code>redirect_url</code> passed
  314. to the template)</li>
  315. <li><code>idp</code>: the 'idp_id' of the chosen IDP.</li>
  316. </ul>
  317. </li>
  318. <li><code>sso_auth_account_details.html</code>: HTML page to prompt new users to enter a
  319. userid and confirm other details. This is only shown if the
  320. SSO implementation (with any <code>user_mapping_provider</code>) does not return
  321. a localpart.
  322. When rendering, this template is given the following variables:
  323. <ul>
  324. <li><code>server_name</code>: the homeserver's name.</li>
  325. <li><code>idp</code>: details of the SSO Identity Provider that the user logged in
  326. with: an object with the following attributes:
  327. <ul>
  328. <li><code>idp_id</code>: unique identifier for the IdP</li>
  329. <li><code>idp_name</code>: user-facing name for the IdP</li>
  330. <li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
  331. for the IdP</li>
  332. <li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
  333. for the brand of the IdP</li>
  334. </ul>
  335. </li>
  336. <li><code>user_attributes</code>: an object containing details about the user that
  337. we received from the IdP. May have the following attributes:
  338. <ul>
  339. <li><code>display_name</code>: the user's display name</li>
  340. <li><code>emails</code>: a list of email addresses</li>
  341. <li><code>localpart</code>: the local part of the Matrix user ID to register,
  342. if <code>localpart_template</code> is set in the mapping provider configuration (empty
  343. string if not)
  344. The template should render a form which submits the following fields:</li>
  345. </ul>
  346. </li>
  347. <li><code>username</code>: the localpart of the user's chosen user id</li>
  348. </ul>
  349. </li>
  350. <li><code>sso_new_user_consent.html</code>: HTML page allowing the user to consent to the
  351. server's terms and conditions. This is only shown for new users, and only if
  352. <code>user_consent.require_at_registration</code> is set.
  353. When rendering, this template is given the following variables:
  354. <ul>
  355. <li><code>server_name</code>: the homeserver's name.</li>
  356. <li><code>user_id</code>: the user's matrix proposed ID.</li>
  357. <li><code>user_profile.display_name</code>: the user's proposed display name, if any.</li>
  358. <li>consent_version: the version of the terms that the user will be
  359. shown</li>
  360. <li><code>terms_url</code>: a link to the page showing the terms.
  361. The template should render a form which submits the following fields:</li>
  362. <li><code>accepted_version</code>: the version of the terms accepted by the user
  363. (ie, 'consent_version' from the input variables).</li>
  364. </ul>
  365. </li>
  366. <li><code>sso_redirect_confirm.html</code>: HTML page for a confirmation step before redirecting back
  367. to the client with the login token.
  368. When rendering, this template is given the following variables:
  369. <ul>
  370. <li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
  371. <li><code>display_url</code>: the same as <code>redirect_url</code>, but with the query
  372. parameters stripped. The intention is to have a
  373. human-readable URL to show to users, not to use it as
  374. the final address to redirect to.</li>
  375. <li><code>server_name</code>: the homeserver's name.</li>
  376. <li><code>new_user</code>: a boolean indicating whether this is the user's first time
  377. logging in.</li>
  378. <li><code>user_id</code>: the user's matrix ID.</li>
  379. <li><code>user_profile.avatar_url</code>: an MXC URI for the user's avatar, if any.
  380. <code>None</code> if the user has not set an avatar.</li>
  381. <li><code>user_profile.display_name</code>: the user's display name. <code>None</code> if the user
  382. has not set a display name.</li>
  383. </ul>
  384. </li>
  385. <li><code>sso_auth_confirm.html</code>: HTML page which notifies the user that they are authenticating
  386. to confirm an operation on their account during the user interactive authentication
  387. process.
  388. When rendering, this template is given the following variables:
  389. <ul>
  390. <li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
  391. <li><code>description</code>: the operation which the user is being asked to confirm</li>
  392. <li><code>idp</code>: details of the Identity Provider that we will use to confirm
  393. the user's identity: an object with the following attributes:
  394. <ul>
  395. <li><code>idp_id</code>: unique identifier for the IdP</li>
  396. <li><code>idp_name</code>: user-facing name for the IdP</li>
  397. <li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
  398. for the IdP</li>
  399. <li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
  400. for the brand of the IdP</li>
  401. </ul>
  402. </li>
  403. </ul>
  404. </li>
  405. <li><code>sso_auth_success.html</code>: HTML page shown after a successful user interactive
  406. authentication session.
  407. Note that this page must include the JavaScript which notifies of a successful
  408. authentication (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
  409. This template has no additional variables.</li>
  410. <li><code>sso_auth_bad_user.html</code>: HTML page shown after a user-interactive authentication
  411. session which does not map correctly onto the expected user.
  412. When rendering, this template is given the following variables:
  413. <ul>
  414. <li><code>server_name</code>: the homeserver's name.</li>
  415. <li><code>user_id_to_verify</code>: the MXID of the user that we are trying to
  416. validate.</li>
  417. </ul>
  418. </li>
  419. <li><code>sso_account_deactivated.html</code>: HTML page shown during single sign-on if a deactivated
  420. user (according to Synapse's database) attempts to login.
  421. This template has no additional variables.</li>
  422. <li><code>sso_error.html</code>: HTML page to display to users if something goes wrong during the
  423. OpenID Connect authentication process.
  424. When rendering, this template is given two variables:
  425. <ul>
  426. <li><code>error</code>: the technical name of the error</li>
  427. <li><code>error_description</code>: a human-readable message for the error</li>
  428. </ul>
  429. </li>
  430. </ul>
  431. </main>
  432. <nav class="nav-wrapper" aria-label="Page navigation">
  433. <!-- Mobile navigation buttons -->
  434. <a rel="prev" href="structured_logging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  435. <i class="fa fa-angle-left"></i>
  436. </a>
  437. <a rel="next" href="usage/configuration/user_authentication/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  438. <i class="fa fa-angle-right"></i>
  439. </a>
  440. <div style="clear: both"></div>
  441. </nav>
  442. </div>
  443. </div>
  444. <nav class="nav-wide-wrapper" aria-label="Page navigation">
  445. <a rel="prev" href="structured_logging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  446. <i class="fa fa-angle-left"></i>
  447. </a>
  448. <a rel="next" href="usage/configuration/user_authentication/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  449. <i class="fa fa-angle-right"></i>
  450. </a>
  451. </nav>
  452. </div>
  453. <script type="text/javascript">
  454. window.playground_copyable = true;
  455. </script>
  456. <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
  457. <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
  458. <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
  459. <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
  460. <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
  461. <script src="book.js" type="text/javascript" charset="utf-8"></script>
  462. <!-- Custom JS scripts -->
  463. <script type="text/javascript" src="docs/website_files/table-of-contents.js"></script>
  464. <script type="text/javascript" src="docs/website_files/version-picker.js"></script>
  465. <script type="text/javascript" src="docs/website_files/version.js"></script>
  466. </body>
  467. </html>