Matrix for healthcare and the TI-Messenger standard

A Matrix homeserver alone does not define a TI-Messenger service. According to gematik's api-ti-messenger repository, the Messenger-Service is a combination of two parts: a Messenger-Proxy and a Matrix homeserver that offers the Matrix Client-Server API and the Server-Server API. The homeserver supplies the Matrix protocol behavior that clients and other servers expect, while the proxy sits in front of it and carries the TI-Messenger-specific requirements. A team that starts from a stock Synapse installation therefore has to identify what the proxy must do, and where it must sit, before it can describe its deployment as a TI-Messenger service.

The api-ti-messenger documentation supplements the TI-Messenger ePA and TI-Messenger Pro specifications rather than replacing them, so the requirements for a given deployment may be spread across several documents. The repository references the Matrix Client-Server, Server-Server and Push Gateway APIs at version 1.17. That is a Matrix specification version, not a Synapse release number, and it should be checked against the homeserver version and client versions you plan to run. Confirm that your chosen homeserver implements the referenced API version completely, and test mobile push through the Push Gateway path before you commit to a design.

The first planning decision is ownership of each component. Ask whether the Messenger-Proxy will be custom built, bought from a vendor, or hosted by a third party, and who maintains it after go-live. For the homeserver, decide whether to run Synapse, which Element develops under AGPL-3.0 with commercial licenses also available, or another implementation, and whether an Element offering such as ESS TI-Messenger covers both the proxy and the homeserver or only part of the stack. Get each vendor to state in writing which parts they supply, which they operate, and which remain your responsibility.

Obtain the current gematik specifications and conformance requirements directly from gematik rather than relying on secondary summaries, including the specification versions that apply to your use case. Confirm what evidence of conformance is expected, who assesses it, and whether any approval step must be completed before live use. Also confirm how federation scope will be restricted. Synapse's federation_domain_whitelist setting and firewalling of the federation listener are the controls that a homeserver team would typically configure, but whether the specification requires them, and in what form, must come from the specification itself.

Plan for version coordination. The Synapse upgrade notes warn that rolling back can be difficult because of database schema changes between releases. Because the proxy and the homeserver must both conform to the referenced Matrix API version, each upgrade of either component should be tested against the other, against the referenced API version, and against the current gematik conformance requirements before it reaches production.

The first decision is which homeserver will carry clinical traffic, and it should be settled before client or identity work begins. Synapse is the most widely documented option. Element develops it under AGPL-3.0-or-later, and Element also sells Synapse Pro under a commercial license. Dendrite, written in Go, is AGPL-3.0-or-later, while Conduit and its Rust forks Continuwuity and Tuwunel are Apache-2.0. The trade-off lies between vendor-backed documentation, tooling and support on one side and license terms and production history on the other. The TI-Messenger Messenger-Service pairs a Messenger-Proxy with a homeserver that must offer the Matrix Client-Server and Server-Server APIs. Ask gematik's specification and each vendor which implementations have been tested against the referenced API version (1.17), and do not assume that any spec-compliant homeserver satisfies the healthcare requirements on its own.

Element Server Suite comes in three editions, and the edition shapes both the license position and who answers when something fails. ESS Community is free and intended for non-professional deployments and evaluations, so it is a poor fit for a production clinical service. ESS Pro targets professional and government use and includes Synapse Pro, Matrix Authentication Service, LDAP and SCIM integration, and auditing. ESS TI-Messenger is aimed at German healthcare and is deployed on Kubernetes with Helm charts. Ask each vendor, in writing, what support covers, which component versions are supported, how upgrades are delivered, and whether the charts are supported when your own team or a partner operates the cluster. Confirm which edition is required to receive the TI-Messenger components, because that choice affects every later upgrade and audit trail. Plan the platform floors into your base images early, since Synapse upgrade notes require PostgreSQL 14 or newer from 1.143.0 and Python 3.10 or newer from 1.142.0.

Federation policy determines who a clinician can message outside the organization, so it is a clinical governance decision as much as a technical one. In Synapse, the federation_domain_whitelist setting restricts federation to the listed domains, and an empty list disables federation entirely. A closed deployment with an empty list keeps all conversations inside one server, while a named list lets a hospital message only the practices and partners it has agreed to trust. Decide which of these models applies for each care pathway before go-live, and record the list and its owner. The Synapse documentation recommends also firewalling the federation listener, which uses port 8448 by default, so that network controls match the policy. Confirm with your Synapse version whether the whitelist is enforced for inbound requests, outbound requests or both. Also decide the server_name value now, because user identifiers such as @user:example.com depend on it and changing it later is disruptive.

Identity determines who can sign in, so it should be brokered from the hospital or practice directory rather than from local Matrix accounts. Synapse can authenticate against OpenID Connect providers configured through oidc_providers, against SAML2 using pysaml2, and against CAS. Matrix Authentication Service uses OAuth 2.0 and OpenID Connect against upstream providers such as Keycloak, Microsoft Entra ID, Google and Authentik. It does not support SAML directly, and its documentation recommends a bridge such as Dex when the directory speaks SAML or LDAP. Identify the source of truth for each clinician, usually the hospital or practice directory, and confirm how deactivation propagates to active sessions and devices. ESS Pro includes LDAP and SCIM integration, so ask how those connectors map roles and removals. Verify the flow with a test account that is removed from the directory and confirm that its access ends.

A US covered entity or business associate that uses a hosted or supported Matrix service needs a business associate contract with that vendor before electronic protected health information (ePHI) moves through the service. Under 45 CFR 164.314(a)(2)(i), the contract must require the business associate to comply with the Security Rule, flow the same terms down to any subcontractor that handles ePHI, and report security incidents to the covered entity, including breaches of unsecured PHI. These three elements are the floor set by the rule. Counsel will add liability, termination and other commercial terms around them, and a signed template does not show that the vendor's controls work.

The Security Rule is organized into 18 standards across administrative, physical and technical safeguards, with 36 implementation specifications. Of those specifications, 14 are required and 22 are addressable, meaning the entity must assess whether each one is reasonable and appropriate and then implement it or document an equivalent measure. For a Matrix deployment, the technical safeguards in 45 CFR 164.312 matter most, including unique user identification, emergency access procedures, automatic logoff and encryption. The contract should state which party configures each of these on the homeserver, the identity provider, the database, the media store and the backups. Ask the vendor to provide that mapping in writing before any ePHI is loaded.

Subcontractor flow-down needs particular attention in a Matrix service. A managed deployment may depend on a cloud host, a database operator, a backup provider, a Kubernetes platform, a support engineering firm and an identity provider. Each one that can create, receive, maintain or transmit ePHI must accept terms at least as protective as the vendor's own. Ask for the current subcontractor list, the vendor's process for notifying you before a change, and your right to object. Confirm where each subcontractor stores data and whether support staff outside the country can reach production logs or message content.

Self-hosting does not remove the contract requirement. An organization that runs Synapse in its own cloud account or data center still needs business associate terms with any vendor that installs, operates, patches, troubleshoots or upgrades the system, and with any vendor that can reach it, including through remote sessions, support bundles or logs attached to a ticket. Whether a software license on its own creates a business associate relationship is a question for counsel, and the answer depends on what the vendor can access in practice. Document each access path, such as VPN accounts, break-glass credentials and vendor-held administrator keys, because those paths define the contract's scope.

Before signature, have counsel review the contract and pair it with a responsibility matrix that names the party responsible for each Security Rule control and each incident step. For each row, confirm who detects the incident, who decides whether it is a breach of unsecured PHI, who notifies the covered entity and who pays for notification. The contract should reference the Security Rule as in force at signing and include a change clause, because HHS proposed a major Security Rule revision on 6 January 2025 and, as of October 2026, no final rule had been published. Ask the vendor for its incident response plan, and check that its notification timing is written into the agreement itself.

A clinical Matrix service stays supportable only if upgrades are planned as a routine operating task rather than triggered by a problem. The Synapse upgrade notes set the first hard limits to check before any change. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. These floors apply to the database and runtime hosts, so the team should record the current versions of both, compare them with the release it intends to deploy, and treat any gap as a blocking item in the plan. Support for Python and PostgreSQL versions also ends when those versions reach upstream end of life, so the host baseline needs its own review schedule.

Set a release cadence that the clinical owner and the platform team both accept. Releases are published on the Synapse GitHub releases page, and the most recent entry in the supplied record is v1.163.0, published October 14, 2026. A newer release is not automatically a reason to deploy, but every release between your current version and the target has its own upgrade notes, and those notes must be read in sequence. Decide who reviews them, who approves a change window, and how far behind the current release the service may run. Confirm with gematik and your vendor whether the Messenger-Proxy and the homeserver in your TI-Messenger service must move together.

Every upgrade should run first in a staging environment that matches production in the parts that change behavior: the PostgreSQL version and data volume, the worker layout and Redis, the federation and server_name settings, and the SSO connections. Apply the upgrade, let background database updates finish, then test sign-in, message delivery, media upload, federation with the partners you depend on, and any bridges or calling features in use. Illustrative example: a staging run shows that a host still running an older Python build cannot start the new release. Finding that gap in staging, weeks before the production date, is far better than finding it during a clinical shift. Record each step so the production runbook matches what was actually tested.

Before each production upgrade, write a recovery plan backed by a database backup that has been restored successfully in a test, not just one that completed. The upgrade notes warn that rolling back can be difficult because of database schema changes between releases, so returning to the previous Synapse version may not be safe once the new schema has been applied. Take a PostgreSQL backup immediately before the change, define the point at which the team stops, restores from backup and names the people who make that call. Ask the vendor which restore steps apply to the target release, and keep a log of which versions run in which environments so that incident reviews and audits can reconstruct the system state.