Skip to content
Chatto v0.5.0

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.

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.

Room membership is required for all calls. Configure these permissions at Server, Room group, Room, or Direct messages scope:

PermissionAction
call.startStart a call. Also requires call.join.
call.joinJoin an active call, including as a listener.
call.voicePublish microphone audio.
call.cameraPublish camera video.
call.screenshareShare 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.

  • 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:

Terminal window
chatto init --with-livekit
livekit-server --config livekit.yaml

Run 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:

  1. Install and run LiveKit

    For local development, the quickest option is the LiveKit CLI:

    Terminal window
    # macOS
    brew install livekit
    # Then run in dev mode
    livekit-server --dev

    This starts LiveKit on ws://localhost:7880 with a default API key of devkey and secret of secret.

    For production, see the LiveKit self-hosting guide.

  2. Configure Chatto

    Add a [livekit] section to your chatto.toml:

    [livekit]
    enabled = true
    url = 'ws://localhost:7880'
    api_key = 'devkey'
    api_secret = 'secret'

    Or use environment variables:

    Terminal window
    CHATTO_LIVEKIT_ENABLED=true
    CHATTO_LIVEKIT_URL=wss://livekit.example.com
    CHATTO_LIVEKIT_API_KEY=your-api-key
    CHATTO_LIVEKIT_API_SECRET=your-api-secret
  3. 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/livekit
    api_key: your-api-key

    For local development with livekit-server --dev, the --dev flag disables webhooks. That is useful for testing local media connectivity, but active-call indicators and participant reconciliation require webhook delivery in normal deployments.

  4. Restart Chatto

    Calls will be available immediately. Call controls appear in room headers when LiveKit is configured.

  5. Check the setup

    Open Manage Server → System and examine the Calls (LiveKit) panel. See 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:

StatusMeaningWhat to do
ConnectedLiveKit accepted the API key and secret.Nothing.
Not configuredLiveKit is not enabled, or a required setting is empty.Configure the [livekit] section.
UnreachableChatto 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 rejectedLiveKit rejected the API key or secret.Make sure that api_key and api_secret match a key pair in livekit.yaml.
ErrorThe 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:// or http://, and the Chatto URL is not localhost, a .localhost name, or a loopback address. Browsers cannot connect to an unencrypted URL from an HTTPS page. Use wss://.
  • The last webhook had a signature that is not valid. LiveKit signs webhooks with a key that Chatto does not accept. Set webhook.api_key in livekit.yaml to the Chatto API key, or set livekit.webhook_api_key and livekit.webhook_api_secret in 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.urls in livekit.yaml contains 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.

  • 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.

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 portPurpose
TCP 443Secure LiveKit API and WebSocket signaling, proxied to TCP 7880
TCP 7881ICE/TCP media fallback when UDP is unavailable
UDP 3478Optional embedded TURN/STUN relay
UDP 7882Direct 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: false

The 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.10

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: 3478

Expose 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.

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.

To disable voice and video calls, either remove the [livekit] section from chatto.toml or set:

[livekit]
enabled = false

When 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.