Mattermost WebRTC is the real-time communication capability built into Mattermost that enables browser-based peer-to-peer video and audio calls between team members. It works through a plugin architecture that uses Mattermost's own HTTP and Server-Sent Events channels for signaling, with optional STUN/TURN services for network traversal. If you are evaluating embedded RTC for your product instead, VideoSDK provides production-grade video calling SDKs across ten platforms with sub-300ms latency, a Prebuilt UI Kit, and network-adaptive streaming out of the box.
Real-time voice and video has quietly become table stakes for team chat platforms. A 2025 industry survey by Wainhouse Research found that over 70 percent of distributed engineering teams now expect some form of native calling inside their primary collaboration tool rather than switching to a separate meeting app. For organizations that run Mattermost as their self-hosted communication hub, that expectation lands squarely on Mattermost WebRTC.
Mattermost occupies a specific niche: it is the open-source, self-hostable chat platform of choice for security-conscious enterprises, government teams, and DevOps organizations that want full data ownership. Its WebRTC calling capabilities, delivered through the built-in video call plugin and the separate voice channels plugin, let those teams keep real-time media inside their own infrastructure instead of routing it through a third-party SaaS provider.
In this guide, you will learn how Mattermost WebRTC actually works under the hood, how to enable it through the System Console, how to configure STUN/TURN services for reliable connections across firewalls, and how to troubleshoot the issues that most commonly break calls in production. By the end, you will have a complete mental model of Mattermost's real-time communication stack and a clear checklist for making it production-ready.
What is Mattermost WebRTC?
Mattermost WebRTC is defined as the set of real-time communication features that allow Mattermost users to start browser-based video and voice calls directly from the chat interface, powered by the WebRTC protocol suite rather than a proprietary media server. Mattermost provides this capability through its plugin ecosystem: a built-in video call plugin ships with the platform and handles one-to-one calls in direct message channels, while a separate community-maintained voice channels plugin adds persistent audio rooms.
Mattermost WebRTC works by letting two participants' browsers establish a direct peer-to-peer media connection, using Mattermost's existing server infrastructure only for signaling and initial connection setup. This design keeps media traffic off the Mattermost server entirely in the happy path, which matters a lot for self-hosted deployments where server resources are limited and media bandwidth is expensive.
The plugin architecture is the key concept here. Mattermost does not bundle a full media server. Instead, it exposes the plugin framework that third-party and first-party plugins use to add call buttons, handle signaling, and manage session state. This is a fundamentally different philosophy from platforms like VideoSDK, where a managed cloud SFU handles media routing, recording, and adaptive streaming as part of the core service.
Core Architecture of Mattermost WebRTC
The Mattermost WebRTC architecture keeps media in the browser and uses the Mattermost server purely as a signaling relay. Two participants exchange connection metadata through the server, then send audio and video directly to each other over an encrypted peer-to-peer channel. When direct connections fail due to network restrictions, a TURN relay service steps in as a fallback.
Here is the full flow visualized:
The important architectural insight is that the Mattermost server never touches media packets in the direct connection path. It only relays session descriptions and ICE candidates, which are small text payloads. This makes the server load nearly negligible for one-to-one calls, but it also means call quality depends entirely on the network path between the two browsers, which is where STUN and TURN become critical.
Browser Media Exchange
Each browser captures local audio and video through the standard browser media APIs, requesting camera and microphone access from the user. Once permission is granted, the captured media tracks are attached to a peer connection object, which negotiates codecs, encrypts all packets, and manages the direct media flow. Every packet in this exchange is encrypted end-to-end between the two peers by design, since WebRTC mandates SRTP encryption for all media.
Signaling Service
Mattermost's video call plugin uses the platform's existing HTTP API and a Server-Sent Events stream as its signaling channel. When a user starts a call, the plugin posts a call invitation message into the channel, and participants signal their connection metadata through plugin API endpoints. The SSE stream keeps both browsers updated in real time about who has joined, left, or declined. This is a pragmatic choice: it reuses Mattermost's proven infrastructure instead of requiring a separate WebSocket signaling server.
Network Traversal
STUN and TURN services solve the NAT traversal problem. Most corporate and home networks hide devices behind network address translation, so two browsers cannot simply find each other. A STUN server lets each browser discover its public network address. When direct connection is impossible, such as when both peers sit behind strict symmetric NATs or restrictive corporate firewalls, a TURN relay, typically the widely used Coturn server, receives and forwards media between them. Without a TURN fallback, a meaningful percentage of calls in enterprise environments will silently fail to connect.
Enabling WebRTC Calls in Mattermost
Enabling the built-in video call plugin is a System Console task, but getting it working reliably in production involves several supporting steps. Here is the complete path.
Step 1: Enable the plugin in the System Console. A system administrator opens the System Console, navigates to the plugin management section, and enables the video call plugin that ships with the platform. The plugin registers its call button in channel headers and direct message interfaces once activated. No server restart is typically required because Mattermost hot-loads plugins.
Step 2: Verify HTTPS is properly configured. Browsers only grant camera and microphone access to secure contexts, meaning your Mattermost instance must be served over valid HTTPS. If your deployment runs behind a reverse proxy such as Nginx or a load balancer, confirm the SSL certificate is trusted and correctly terminated. A self-signed certificate will cause browsers to block media access entirely, which is the single most common reason calls fail on freshly deployed instances.
Step 3: Configure STUN and TURN services. The plugin settings in the System Console include fields for STUN and TURN server addresses. A public STUN server works for simple networks, but production deployments should run their own Coturn instance with a shared secret for authentication. The TURN server must be reachable on its listening port and, critically, on its relay port range over UDP. Document the exact port range you allocate, because firewall misconfiguration here is the top cause of one-way audio and failed connections.
Step 4: Test across realistic networks. Test calls between a user on the office network and a user on a home connection or mobile hotspot. Same-network tests almost always succeed and tell you nothing about NAT traversal. Cross-network tests are where STUN and TURN configuration problems reveal themselves.
Step 5: Check plugin compatibility with your Mattermost version. The built-in plugin targets current Mattermost releases, and the voice channels plugin has its own compatibility matrix. Before upgrading your Mattermost server, verify that the plugin versions you depend on support the new release, since plugin API changes between major versions can break call functionality.
Common pitfalls worth calling out explicitly: missing HTTPS blocks all media permissions, blocked UDP relay ports cause calls that connect but transmit no audio or video, and TURN servers placed behind the same restrictive firewall they are meant to bypass will obviously fail. For teams that find this operational burden heavy, a managed alternative like VideoSDK's Prebuilt UI Kit embeds a full calling interface with TURN infrastructure and adaptive streaming already handled.
Using the Built-In Video Call Plugin
Once enabled, the built-in plugin gives users a call button in the channel header of any direct message conversation. Starting a call posts a call invitation message into the channel thread, and the other participant joins by clicking the join button in that post. This invitation-as-message design is elegant because it keeps call history visible in the channel and lets asynchronous teammates see that a call happened even if they missed it.
Users can also start a call from a teammate's profile card or from the direct message sidebar, depending on interface configuration. During a call, the plugin presents standard call controls: mute, camera toggle, screen sharing where supported, and hang up. Leaving a call simply closes the session, and the channel post updates to reflect the ended call.
The most important limitation to communicate to your users is that the built-in plugin is designed for one-to-one calls in direct message channels only. It does not support group calls, and it does not appear in team channels. For organizations that need multi-party calls, this means either deploying the voice channels plugin for group audio, integrating an external conferencing tool through Mattermost's rich integration framework, or evaluating a dedicated RTC platform. Teams building custom multi-party experiences often turn to SDKs like VideoSDK, which handles multi-participant rooms, grid layouts, and recording natively.
Voice Channels Plugin Overview
The voice channels plugin is a separate, community-maintained Mattermost plugin that adds persistent audio rooms to your workspace. Instead of one-to-one calls, it creates always-available voice channels that any team member can join or leave freely, closer to the Discord voice channel model than a traditional meeting.
Technically, the voice channels plugin builds a WebRTC audio mesh among participants. Each participant maintains direct audio connections to every other participant. This works well for small groups, typically up to around eight to ten participants, but mesh topology scales poorly beyond that because every browser must upload its audio to every other peer simultaneously, multiplying bandwidth consumption linearly with participant count.
Typical use cases fit this constraint well: daily stand-up rooms for distributed squads, quick huddles that spin up without scheduling, ops on-call channels where an engineer can drop in during an incident, and social rooms for remote-first companies. The plugin shows which channels are active and who is speaking directly in the Mattermost sidebar, which keeps presence lightweight and discoverable.
For larger persistent audio rooms, a mesh hits a ceiling. Platforms built on SFU media routing, like VideoSDK's audio calling SDKs, handle hundreds of participants in a single room because each participant uploads once to the server, which then distributes streams efficiently.
Deployment Options: Self-Hosted vs Cloud
Mattermost offers two deployment paths, and the WebRTC experience differs meaningfully between them.
Self-hosted deployment gives you full data ownership, which is usually the reason you chose Mattermost in the first place. But it also means you own the entire WebRTC operational surface: HTTPS certificate management, Coturn installation and maintenance, UDP port exposure through your firewall, and capacity planning for TURN relay bandwidth. TURN relays can consume significant bandwidth when many calls fall back to relayed media, so monitor relay usage and size your TURN infrastructure accordingly.
Mattermost Cloud, the managed offering, shifts infrastructure management to the vendor. Plugin management is handled through the cloud console, and the underlying HTTPS and network plumbing is maintained for you. The trade-off is reduced control over plugin versions and configuration depth, and your media traversal path depends on the provider's infrastructure choices.
Here is how the self-hosted deployment flow fits together:
Scaling considerations differ by path. Self-hosted deployments scale the Mattermost server for signaling load, which is light, but must scale TURN capacity for relayed media, which is heavy. Cloud deployments inherit the provider's scaling but should still verify TURN coverage for users in restrictive network regions. Either way, Mattermost's official documentation remains the authoritative reference for current deployment specifics.
Troubleshooting Common Issues
Most Mattermost WebRTC failures fall into four recognizable categories, and each has a distinct diagnostic signature.
Connection failures where the call never establishes usually point to NAT traversal problems. If both peers sit behind symmetric NATs and no functional TURN server is configured, the peer connection simply times out. Verify that the TURN server address, port, and shared secret configured in the plugin settings match your Coturn deployment exactly, and confirm the relay port range is open on UDP, not just TCP.
Camera and microphone permission problems manifest as a call that connects but shows a black video tile or transmits silence. Check that the Mattermost URL is served over valid HTTPS, that the browser has not previously blocked media access for the site, and that no enterprise policy or privacy setting is restricting device access. Users can reset permissions through the browser's site settings panel.
One-way audio or video is the classic symptom of a partially blocked firewall. The connection establishes through one candidate path but media flows only one direction. This almost always means the TURN relay port range is partially blocked, so audit the UDP port range end to end.
Diagnostics through logs and the SSE stream. The Mattermost server logs record plugin API activity and signaling errors, while browser developer tools expose the peer connection state, ICE candidate gathering results, and media track status. If ICE gathering returns only host candidates and no server-reflexive candidates, your STUN configuration is broken. If gathering succeeds but connectivity checks fail, TURN is your problem. The VideoSDK community Discord and Mattermost community forums are both good places to compare notes when a diagnosis stalls.
Best Practices for Production-Ready WebRTC
A few disciplined habits separate reliable deployments from frustrating ones.
Security first. WebRTC media is always encrypted in transit via SRTP, but your signaling path and TURN authentication deserve equal attention. Use TURN shared-secret authentication rather than open relays, restrict TURN access by IP allowlisting where feasible, and keep your Mattermost instance and plugins updated to receive security patches. Review plugin permissions in the System Console periodically.
Performance and adaptivity. Browser WebRTC adapts bitrate to network conditions automatically, but you can help it by ensuring TURN servers are geographically close to your users and by avoiding unnecessary VPN hairpins in the media path. For teams needing stronger guarantees, dedicated RTC platforms add network-adaptive streaming with automatic resolution scaling, such as VideoSDK's adaptive streaming.
Monitoring and maintenance. Track TURN relay bandwidth, call success rates, and plugin error logs as ongoing operational metrics. Schedule plugin compatibility checks before every Mattermost server upgrade, and maintain a known-good rollback path. Freshness matters here: verify current plugin versions against your Mattermost release before any production change.
Definitions Glossary
WebRTC: A free, open standard enabling real-time audio, video, and data exchange directly between browsers, with mandatory encryption of all media packets.
STUN server: A service that lets a browser behind NAT discover its public IP address and port so a peer connection can attempt direct media exchange.
TURN server: A relay service, commonly Coturn, that forwards media between peers when direct connection fails, requiring open UDP relay port ranges in firewalls.
Server-Sent Events (SSE): A one-way HTTP-based streaming mechanism Mattermost's call plugin uses to push real-time signaling updates to connected browsers.
Plugin architecture: Mattermost's extension framework that lets first-party and community plugins add features like video calls without modifying the core server.
ICE candidates: Network address proposals exchanged during WebRTC connection setup, gathered via the browser's local interfaces and STUN/TURN servers.
Key Takeaways
- Mattermost WebRTC delivers browser-based peer-to-peer video and voice calls through a plugin architecture, keeping media off the Mattermost server and using HTTP plus Server-Sent Events for signaling.
- The built-in video call plugin supports one-to-one calls in direct messages only, while the separate voice channels plugin adds persistent group audio rooms using a mesh topology that scales to roughly ten participants.
- Reliable production calls require valid HTTPS, a properly configured STUN service, and a TURN relay with its full UDP port range open through your firewall.
- Self-hosted deployments own the full WebRTC operational surface, including Coturn maintenance and TURN bandwidth planning, while Mattermost Cloud shifts that burden to the vendor.
- Teams needing multi-party video, recording, or large persistent rooms should evaluate dedicated RTC platforms like VideoSDK, which provides multi-platform SDKs, a Prebuilt UI Kit, and network-adaptive streaming built in.
Conclusion
Mattermost WebRTC gives self-hosted teams genuinely useful real-time calling without surrendering data ownership to a third-party meeting tool. The architecture is pragmatic: browsers handle media peer-to-peer, the Mattermost server handles lightweight signaling, and Coturn covers the hard network cases. Get HTTPS right, configure TURN properly, test across realistic networks, and the built-in plugin plus voice channels will cover the daily collaboration needs of most small teams. When your requirements grow past one-to-one calls and small audio meshes, dedicated RTC infrastructure is the natural next step. Explore VideoSDK's documentation and try the free tier at app.videosdk.live to see how quickly embedded video calling can ship. What are you building with Mattermost WebRTC? Drop a comment and share your deployment setup, I'd love to hear how your team handles real-time communication.
Free $20 Balance for AI Voice Agents & Video Calls
FAQ