Synapse WebRTC is the combination of the Matrix Synapse homeserver as a signaling and identity layer with WebRTC as the peer-to-peer media transport. Synapse relays SDP offers, answers, and ICE candidates between participants through Matrix events, while audio and video flow directly between browsers. For teams that want managed signaling plus production-grade media, VideoSDK's video calling SDK handles both layers out of the box.
Decentralized communication is having a moment. Since the mainstream shift away from centralized chat platforms, developers have been building on Matrix, the open standard for federated messaging, at a pace the protocol has never seen before. And the most requested feature in that ecosystem is video chat.
That is where synapse webrtc comes in. Synapse, the most widely deployed Matrix homeserver, was never designed to carry media itself. But it turns out to be an excellent signaling backbone for WebRTC, the browser-native real-time communication stack. Combine the two and you get decentralized video chat where no single vendor owns your users, your rooms, or your media paths.
In practice, teams integrating Synapse with WebRTC consistently find that the signaling side is the easy part. The hard parts are NAT traversal, TURN fallback, and production hardening. This guide walks through the full picture: architecture, configuration, signaling flow, and the gotchas that bite people in production.
What Is Synapse?
Synapse is defined as the reference implementation of a Matrix homeserver, the server-side component that stores accounts, rooms, and message history for the Matrix federation protocol. Developed originally by Matrix's creators and now maintained as an open-source project, Synapse handles user identity management, room membership, event distribution, and federation with other homeservers across the decentralized Matrix network.
Synapse works by persisting every room interaction as a signed event in a directed acyclic graph of conversation history. Clients connect to it over HTTPS, authenticate with access tokens, and synchronize state through long-polling or server-sent events. Every message, membership change, and room attribute lives as an event that all participating homeservers replicate.
For WebRTC developers, the important detail is that Synapse already solves three problems you would otherwise build yourself: authenticated user identity, room membership semantics, and a reliable delivery mechanism for arbitrary JSON payloads between room members. Those three capabilities map almost perfectly onto what WebRTC signaling requires. Synapse does not touch your media. It only carries the negotiation messages that let two peers find each other.
Fundamentals of WebRTC
WebRTC is defined as a browser and native API standard for real-time peer-to-peer exchange of audio, video, and arbitrary data, standardized by the W3C and the IETF. WebRTC works by letting two clients negotiate a direct, encrypted media session using the DTLS-SRTP protocol suite, then streaming media between them without an intermediary server on the happy path.
Before media can flow, the peers must complete ICE negotiation. ICE, Interactive Connectivity Establishment, is the process by which each client gathers every possible network address it can reach itself through, including local addresses, addresses discovered via a STUN server, and relay addresses provisioned by a TURN server. The two sides exchange these candidates through signaling, test connectivity pairwise, and select the first working route.
STUN servers simply tell a client what its public address looks like from the outside. TURN servers go further: they relay media when a direct path fails, which happens constantly behind corporate firewalls, symmetric NATs, and mobile carrier networks. Industry experience, tracked across deployments on webrtcstats.com, consistently shows that a meaningful share of real-world sessions need TURN relay to connect at all.
Alongside media, WebRTC data channels provide an ordered, reliable message pipe between peers, useful for chat overlays, file transfer, and game state in peer-to-peer scenarios.
Why Combine Synapse With WebRTC?
The core insight is separation of concerns. WebRTC deliberately leaves signaling undefined: the standard specifies how to exchange SDP offers, answers, and ICE candidates, but not how those messages travel between peers. Most teams bolt on a bespoke WebSocket signaling server, which then needs its own authentication, room management, and reconnection logic.
Synapse already has all of that. User login and identity management come from Matrix accounts. Room creation and membership come from Matrix rooms, which are federated, persistent, and access-controlled. Message delivery comes from Synapse's event pipeline, which handles retries and synchronization for you.
The result is decentralized video chat where signaling works across federation boundaries. A user on one homeserver can call a user on another, because the signaling events traverse the Matrix network the same way text messages do. Media still flows peer-to-peer, so latency stays low and the homeserver carries no bandwidth burden.
There is a trade-off worth naming honestly: you inherit Synapse's operational complexity. Running a production homeserver means managing Postgres, federation, and state resolution. Teams that want decentralized identity but not homeserver operations often evaluate WebRTC SDK alternatives, and VideoSDK's Rooms-based architecture is a common choice because it provides managed signaling, token authentication, and TURN infrastructure as a single service.
Architecture Overview: The Synapse WebRTC Stack
A typical synapse webrtc deployment has four moving parts: the browser client, the Synapse homeserver for signaling and identity, a TURN server for NAT traversal fallback, and the direct peer-to-peer media path. Understanding the boundary between signaling and media is the single most important architectural concept here.
The flow works like this. Both users authenticate against Synapse and join the same Matrix room. When one user initiates a call, the client generates an SDP offer and publishes it as a Matrix event in the room. The other client receives the event through Synapse's sync mechanism, generates an answer, and sends it back the same way. ICE candidates flow through additional events. Once both sides have candidates, ICE negotiation happens directly between the clients, possibly via the TURN server, and media flows peer-to-peer.
The key property of this architecture: Synapse never sees a single media packet. It only carries small JSON signaling events, which means homeserver load scales with call setup frequency, not with video bitrate.
Component Breakdown
The Synapse homeserver provides identity management, room state, and event delivery. The WebRTC client layer, typically a browser library or a Matrix client SDK with VoIP support, handles peer connection setup, SDP generation, and media capture. The TURN server, usually coturn in Synapse deployments, provides address discovery and media relay when direct connectivity fails. Each component is independently replaceable, which is the appeal of the modular Synapse backend approach.
Setting Up the Development Environment
Getting a synapse webrtc development stack running involves three preparation tracks that converge at integration time.
First, install and run a Synapse homeserver. The standard path is a local deployment using Synapse's own tooling or a container image, followed by creating an administrator account and generating registration credentials for test users. During development, a single homeserver without federation is enough; you can enable federation later.
Second, set up a TURN server. Coturn is the de facto standard in the Matrix ecosystem. You need a machine with a public IP address, a range of UDP relay ports opened in the firewall, and a long-term credential mechanism configured so Synapse can issue time-limited TURN passwords to clients.
Third, prepare the web client. You need an HTTPS origin for the browser to permit camera and microphone access, since browsers block media device access on plain HTTP except on localhost. Register your test application as a client of the homeserver, obtain client credentials, and confirm you can log in and join a room before touching any WebRTC logic.
The expected outcome of environment setup: two browser tabs, both logged into the same Synapse instance, both members of a shared test room, with the TURN server reachable and its ports open.
Configuring Synapse for WebRTC Signaling
Synapse ships with built-in support for announcing TURN credentials to clients, which is the main configuration surface for WebRTC integration. The homeserver configuration file exposes a set of keys that control how clients discover and authenticate to your TURN infrastructure.
The essential settings are the TURN server URIs, which tell clients where to send STUN and TURN requests; the shared secret, which Synapse uses to generate short-lived TURN credentials on demand; the TURN user lifetime, which controls how long those credentials stay valid; and the list of static STUN URIs for basic address discovery. When these are set, Synapse automatically publishes the current TURN credentials into the client capability response, so any Matrix client that supports VoIP picks them up without manual provisioning.
The signaling side needs no special configuration. Synapse exposes its standard client-server endpoints for syncing, sending events, and room membership, and WebRTC signaling messages ride on those same endpoints as ordinary room events. This is the elegance of the design: there is no dedicated signaling API to configure or secure separately.
One configuration detail that bites people: TURN credential rotation. Because Synapse issues time-limited credentials, a client that holds stale credentials from an old session will fail ICE relay silently. Make sure your client refreshes credentials from the homeserver capability response at the start of each call, not just at login.
Implementing WebRTC Signaling with Synapse
The signaling implementation follows a logical flow that maps cleanly onto Matrix primitives, and understanding the sequence matters more than any individual API call.
The flow begins with user login. Each client authenticates against Synapse and begins syncing with the homeserver, receiving room state and new events as they arrive. Room creation or reuse comes next: the calling client either creates a dedicated room for the call or uses an existing direct-message room, and invites the other participant.
Call setup then proceeds through event exchange. The initiating client captures local media, generates an SDP offer describing its audio and video capabilities, and sends it as a call invitation event in the room. The receiving client sees the event, alerts the user, and on acceptance generates an SDP answer returned as a corresponding event. ICE candidates trickle through separate candidate events as each side gathers network addresses, and both clients feed these into their peer connections until a working route is established.
Two best-practice patterns are worth adopting. First, treat Matrix events as the single source of truth for call state, including hangup and rejection, so a client that reconnects mid-call can reconstruct what happened from room history. Second, handle reconnections by re-syncing from Synapse and comparing the call state events against your local peer connection state, rather than assuming the call died when the socket dropped.
For teams that would rather not own this signaling logic, VideoSDK's video calling SDK implements the equivalent flow with server-side token generation, automatic reconnection, and participant lifecycle events managed for you.
Handling NAT and TURN Fallback
TURN is not optional in production. Behind symmetric NAT, strict corporate firewalls, and most mobile carrier networks, direct peer-to-peer paths simply fail, and without a working TURN relay those users cannot connect at all.
The common pitfalls are predictable: UDP relay ports blocked in the firewall, credentials expired because of rotation, and TURN configured only over UDP when the network only permits TCP or TLS transport. Troubleshooting starts with checking whether ICE negotiation completed with a relay candidate selected, then verifying the TURN server is reachable on the ports you opened. A useful diagnostic habit is testing with two clients on deliberately hostile networks, one behind a strict NAT, before shipping.
Production Considerations
Shipping synapse webrtc to production changes the requirements in four areas.
Security comes first. Serve everything over HTTPS, scope access tokens narrowly, and rely on the fact that WebRTC media is always encrypted end-to-end between peers via DTLS-SRTP regardless of what the signaling layer sees. For sensitive deployments, Matrix's end-to-end encryption can protect the signaling events themselves, though note that some VoIP event types have historically had uneven E2EE support across clients, so verify your client's behavior.
Scalability is about the homeserver, not the media. Synapse carries only small signaling events, so a modest deployment handles thousands of call setups. The real scaling concerns are federation traffic and database load, which are standard Synapse operations problems. Load-balance TURN servers horizontally if relay volume grows, and monitor relay bandwidth, since TURN is the one component where media does traverse your infrastructure.
Monitoring should track ICE failure rates, TURN relay usage percentage, and signaling event delivery latency. Deployment requires HTTPS everywhere, open UDP and TCP TURN ports, and firewall rules that permit the ephemeral UDP port ranges WebRTC uses for direct media.
Real-World Use Cases
Decentralized video conferencing is the flagship use case: organizations running their own Synapse instances get federated video chat where employees on different homeservers can call each other, with no vendor in the middle.
Secure telehealth is a strong fit where data sovereignty matters. A clinic operating its own Matrix infrastructure keeps patient identity and signaling metadata in-house, while WebRTC's mandatory encryption protects the media itself.
Peer-to-peer gaming lobbies use the same pattern with WebRTC data channels instead of, or alongside, media. Synapse handles matchmaking and lobby state as room events, and game state syncs peer-to-peer with sub-100-millisecond latency on good routes.
Privacy-first social platforms and community-run chat networks round out the picture, using Synapse identity management to avoid central account databases entirely.
Common Pitfalls and How to Avoid Them
Four failure modes account for most synapse webrtc debugging sessions.
Token expiry: Matrix access tokens and TURN credentials both expire or rotate. Refresh both at call start rather than relying on values cached at login.
Mismatched ICE candidates: sending candidates before the remote peer connection exists, or dropping candidates during a reconnect. Buffer candidates until the peer connection is ready, and replay them on reconnection.
TURN misconfiguration: the classic is opening the listening port but not the relay port range. Both must be open, on both UDP and TCP.
Client-side permission issues: browsers require HTTPS and a user gesture before granting camera and microphone access. Test on a real HTTPS origin early, not only on localhost where permissions behave differently.
Quick Recap and Next Steps
Synapse WebRTC pairs a proven decentralized signaling and identity layer with the browser's native real-time media stack. Synapse carries SDP and ICE events as Matrix room events, TURN handles NAT traversal, and media flows directly between peers, encrypted by default.
Next steps depend on your direction. To go deeper on the media side, study WebRTC ICE negotiation and STUN/TURN fundamentals. To run Synapse in production, the Synapse documentation covers federation, database tuning, and TURN configuration in detail. And if you want managed signaling, TURN infrastructure, and a full participant lifecycle without operating a homeserver, explore VideoSDK's video calling documentation or browse the code samples.
Definitions Glossary
Matrix Synapse: The reference open-source implementation of a Matrix homeserver, responsible for user identity, room state, event storage, and federation. In a synapse webrtc stack, it acts as the signaling and authentication backbone.
Homeserver: A server in the Matrix network that hosts user accounts and room history for a given domain, and federates with other homeservers to exchange events across the decentralized network.
ICE Negotiation: The WebRTC process where two peers exchange network address candidates, test connectivity pairwise, and select a working media route, either direct or through a TURN relay.
TURN Server: A relay server that forwards WebRTC media when direct peer-to-peer connectivity fails, typically behind strict NATs or firewalls. Synapse can automatically issue time-limited TURN credentials to clients.
SDP Offer/Answer: The session description messages exchanged during WebRTC signaling, describing each peer's media capabilities and transported in a synapse webrtc setup as ordinary Matrix room events.
Key Takeaways
- Synapse WebRTC combines Matrix Synapse signaling and identity with peer-to-peer WebRTC media, giving you decentralized video chat where the homeserver never touches a media packet.
- WebRTC signaling rides on ordinary Matrix room events, so Synapse needs no dedicated signaling API; SDP offers, answers, and ICE candidates are just events in the room timeline.
- A TURN server is mandatory for production, since a significant share of real-world sessions behind strict NATs and firewalls cannot connect without relay fallback.
- The most common failure modes are credential rotation, dropped ICE candidates during reconnection, and TURN relay ports left closed in the firewall.
- Teams that want decentralized-style architecture without operating a homeserver can get managed signaling, TURN infrastructure, and token authentication from VideoSDK's video calling SDK.
Conclusion
Synapse WebRTC is a genuinely compelling pattern for developers who need decentralized video chat: you get federated identity, persistent rooms, and reliable signaling from Synapse, while WebRTC delivers low-latency encrypted media directly between peers. The architecture is clean, the separation of concerns is principled, and the trade-off, operating a production homeserver and TURN infrastructure, is well understood.
If running that infrastructure yourself is more than your project needs, VideoSDK offers the same capability set as a managed service: token-based authentication, built-in TURN fallback, network-adaptive streaming, and SDKs for ten-plus platforms. You can start free at app.videosdk.live/login and have a working video call in minutes.
What are you building with synapse webrtc? Drop a comment, I'd love to hear whether you're running your own homeserver or weighing it against a managed SDK.
Free $20 Balance for AI Voice Agents & Video Calls
FAQ