Voice & Video Calls
Chatto uses LiveKit for voice and video calls. Deploy it as a separate service and configure Chatto to use its API and webhooks.
How It Works
Section titled “How It Works”Chatto checks room membership and permissions, then issues a short-lived LiveKit token and a key for the call. The member’s client connects directly to LiveKit. Current Chatto clients encrypt call media end to end. When the last participant leaves, the call ends and Chatto destroys its key.
LiveKit webhooks and periodic participant checks keep call state consistent after server restarts. Keep webhook delivery working as well as the media connection.
Call permissions
Section titled “Call permissions”Room membership is required for all calls. Configure these permissions at Server, Room group, Room, or Direct messages scope:
| Permission | Action |
|---|---|
call.start | Start a call. Also requires call.join. |
call.join | Join an active call, including as a listener. |
call.voice | Publish microphone audio. |
call.camera | Publish camera video. |
call.screenshare | Share a screen, window, tab, or native application, including captured audio. |
To create a listening audience, allow call.join and deny the three media
permissions. Allow call.start only for people who can start the conversation.
DM policy uses the shared Direct messages scope.
On upgrade, Chatto grants these new permissions to everyone only if that
permission has no previous server-level everyone decision. Restarting never
restores a permission that you cleared or denied. Bots require explicit grants
and sufficient authority from their owner.
The client stops revoked media when it receives updated room permissions. The
server also checks connected participants on its 30-second LiveKit reconciliation
cycle. It removes participants who lose call.join and updates allowed media
sources. Failed checks retry on later cycles. Revocation is not immediate:
an unexpired old token can reconnect until a subsequent check removes it again.
Browser tokens expire after five minutes; native publisher tokens after one
minute. Token expiry alone does not stop an established media connection.
Members without call.join can still see the active call. Leaving a call does
not require a call permission. Call management is not part of these permissions.
Requirements
Section titled “Requirements”- A running LiveKit server (self-hosted or cloud)
- An API key and secret configured on both the LiveKit server and Chatto
For a new local installation, generate both configuration files:
chatto init --with-livekitlivekit-server --config livekit.yamlRun chatto run in a separate terminal. The flag enables LiveKit in
chatto.toml and creates livekit.yaml in the same directory. Both files use
matching random credentials. LiveKit sends webhooks to
http://localhost:4000/webhooks/livekit. The command refuses to replace either
file. With -c /path/to/chatto.toml, it creates /path/to/livekit.yaml.
These settings are for local use. Before deployment, configure the public LiveKit URL, TLS, media network settings, and the Chatto webhook URL as described below. Browsers connect directly to LiveKit for calls, which exposes their IP addresses to that server.
For an existing installation, follow these steps:
-
Install and run LiveKit
For local development, the quickest option is the LiveKit CLI:
Terminal window # macOSbrew install livekit# Then run in dev modelivekit-server --devThis starts LiveKit on
ws://localhost:7880with a default API key ofdevkeyand secret ofsecret.For production, see the LiveKit self-hosting guide.
-
Configure Chatto
Add a
[livekit]section to yourchatto.toml:[livekit]enabled = trueurl = 'ws://localhost:7880'api_key = 'devkey'api_secret = 'secret'[livekit]enabled = trueurl = 'wss://livekit.example.com'api_key = 'your-api-key'api_secret = 'your-api-secret'Or use environment variables:
Terminal window CHATTO_LIVEKIT_ENABLED=trueCHATTO_LIVEKIT_URL=wss://livekit.example.comCHATTO_LIVEKIT_API_KEY=your-api-keyCHATTO_LIVEKIT_API_SECRET=your-api-secret -
Configure LiveKit webhooks
LiveKit must send webhook events to Chatto so it can track who’s in a call. Add the webhook URL to your LiveKit server config (
livekit.yaml):webhook:urls:- https://chatto.example.com/webhooks/livekitapi_key: your-api-keyFor local development with
livekit-server --dev, the--devflag disables webhooks. That is useful for testing local media connectivity, but active-call indicators and participant reconciliation require webhook delivery in normal deployments. -
Restart Chatto
Calls will be available immediately. Call controls appear in room headers when LiveKit is configured.
-
Check the setup
Open Manage Server → System and examine the Calls (LiveKit) panel. See Check the setup.
Check the setup
Section titled “Check the setup”Server owners can check the LiveKit setup without a test call. Open Manage Server → System. The Health panel shows a Calls check when LiveKit is configured. The Calls (LiveKit) panel shows the details. Chatto never shows the API secret or the webhook signing secret.
Each time you open or refresh the page, Chatto calls the LiveKit server API once with the configured API key and secret. The panel shows one of these results:
| Status | Meaning | What to do |
|---|---|---|
| Connected | LiveKit accepted the API key and secret. | Nothing. |
| Not configured | LiveKit is not enabled, or a required setting is empty. | Configure the [livekit] section. |
| Unreachable | Chatto cannot connect to the LiveKit URL. | Make sure that LiveKit runs and that the Chatto server can reach livekit.url. Check DNS, firewalls, and TLS certificates. |
| Credentials rejected | LiveKit rejected the API key or secret. | Make sure that api_key and api_secret match a key pair in livekit.yaml. |
| Error | The server at the URL sent an unexpected reply. | Make sure that livekit.url points to LiveKit, not to a different service or proxy page. |
The panel also shows these warnings:
- The LiveKit URL is not encrypted. The URL uses
ws://orhttp://, and the Chatto URL is notlocalhost, a.localhostname, or a loopback address. Browsers cannot connect to an unencrypted URL from an HTTPS page. Usewss://. - The last webhook had a signature that is not valid. LiveKit signs
webhooks with a key that Chatto does not accept. Set
webhook.api_keyinlivekit.yamlto the Chatto API key, or setlivekit.webhook_api_keyandlivekit.webhook_api_secretin Chatto. - No webhook since the server started. LiveKit sends webhooks only when
calls start or change, so this is normal after a restart. If calls ran and
this message stays, make sure that
webhook.urlsinlivekit.yamlcontains the Webhook URL that the panel shows.
Webhook times come from the server process that handled the page request. They reset when that process restarts. If you run more than one replica, each replica shows only the webhooks that it received.
Chatto cannot check TURN relays. If calls fail only on some networks, see TURN for Restrictive Networks.
Production Considerations
Section titled “Production Considerations”- Network: Users connect directly to the LiveKit server from their browsers. Make sure your LiveKit server is reachable from the public internet (or your private network, for internal deployments). HTTPS/WebSocket signaling and WebRTC media use different routes, as described below.
- TURN/STUN: LiveKit includes a built-in TURN server for NAT traversal. TURN/UDP on port 3478 helps many NAT traversal failures; networks that block UDP entirely need TURN/TLS, often on port 443.
- Scaling: A single LiveKit server handles hundreds of concurrent participants for typical small deployments. For larger deployments, LiveKit supports multi-node clustering with Redis.
- End-to-end encryption: Chatto enables LiveKit E2EE automatically for clients. No additional LiveKit server configuration is required.
- API Secret: Keep your API secret confidential. It’s used to sign JWT tokens and should never be exposed to clients.
Network Paths and Ports
Section titled “Network Paths and Ports”Put LiveKit’s API and WebSocket signaling endpoint behind a reverse proxy with
a publicly trusted certificate. Route wss://livekit.example.com on TCP 443 to
LiveKit port 7880. Media travels directly to LiveKit instead of through the HTTP
reverse proxy:
| Public port | Purpose |
|---|---|
| TCP 443 | Secure LiveKit API and WebSocket signaling, proxied to TCP 7880 |
| TCP 7881 | ICE/TCP media fallback when UDP is unavailable |
| UDP 3478 | Optional embedded TURN/STUN relay |
| UDP 7882 | Direct WebRTC media in the Compose example |
The Compose example sets rtc.udp_port to 7882 so LiveKit can multiplex
direct UDP media on one port. Do not route the TCP or UDP media ports through a
normal HTTP reverse proxy.
When rtc.use_external_ip is enabled, the LiveKit server also uses outbound
UDP STUN requests at startup to discover the public IP it advertises. Allow DNS
and outbound UDP to LiveKit’s default STUN services, or point
rtc.stun_servers at a self-hosted
coturn instance or another STUN service you
operate. If discovery fails, LiveKit logs could not resolve external IP and
cannot start.
These server-side discovery requests are separate from browser ICE. When the embedded TURN/UDP service is enabled, LiveKit advertises that service to browsers instead of falling back to public STUN servers.
For a LAN-only deployment whose host has no external IP address, disable external IP discovery in the LiveKit configuration:
rtc: use_external_ip: falseThe generated Docker Compose configuration enables this setting by default for
internet-facing deployments. If you use that example on a private LAN, change
use_external_ip to false in livekit.generated.yaml before starting or
restarting LiveKit.
For an internet-facing host with a stable public IP, you can avoid STUN-based discovery by configuring the address explicitly:
rtc: use_external_ip: false node_ip: 203.0.113.10TURN for Restrictive Networks
Section titled “TURN for Restrictive Networks”LiveKit can usually connect browsers directly over UDP. Users behind symmetric NATs, mobile networks, or browser/network combinations that fail direct ICE checks need a TURN relay.
For most self-hosted deployments, enable LiveKit’s built-in TURN/UDP server first:
turn: enabled: true udp_port: 3478Expose UDP 3478 on the LiveKit host, keep the direct UDP media port open, and enable ICE/TCP on port 7881 as a fallback when UDP is unavailable. Networks that also block this TCP fallback need TURN/TLS. If your users can only reach outbound TCP 443, LiveKit or TURN needs a dedicated IP address or host so it can listen on 443 without conflicting with your HTTPS reverse proxy, and the TURN TLS certificate must match the advertised TURN domain.
Use a dedicated TURN server such as coturn when you need tighter network separation, a shared TURN service for multiple LiveKit deployments, or TURN/TLS on port 443 without moving LiveKit itself. Configure static credentials on the TURN server and list it under LiveKit’s rtc.turn_servers configuration. The same coturn deployment can provide the private STUN endpoint listed in rtc.stun_servers, but these settings serve different paths: stun_servers discovers the LiveKit host’s public IP, while turn_servers gives browsers a media relay.
Device preferences and microphone test
Section titled “Device preferences and microphone test”Microphone processing, device selection, and participant volume are client preferences. They need no LiveKit server configuration. When you test a deployment, check media delivery from two devices before you investigate one client’s audio preferences. See Check the setup for server diagnostics.
Disabling Voice & Video Calls
Section titled “Disabling Voice & Video Calls”To disable voice and video calls, either remove the [livekit] section from chatto.toml or set:
[livekit]enabled = falseWhen disabled, call controls are hidden. Call APIs return their normal
not-configured results: lists are empty, join and leave report false, and a
singular active-call lookup returns NOT_FOUND.