Voice & Video Calls

Chatto supports real-time voice calls inside rooms using LiveKit, an open-source WebRTC media server. When enabled, any room member can start or join a voice call directly from the room header.

How It Works

LiveKit runs as a separate service alongside Chatto. Chatto handles authentication and signaling, while LiveKit handles the actual audio transport:

1. A user clicks the phone icon in a room header to join a call.
2. Chatto verifies the user’s room membership and generates a short-lived LiveKit JWT token.
3. The user’s browser connects directly to the LiveKit server using the token.
4. Other room members see a real-time notification that someone joined a call.

Calls are implicit — there’s no “start call” action. The first person to join creates the call; when the last person leaves, it ends.

Requirements

• A running LiveKit server (self-hosted or cloud)
• An API key and secret configured on both the LiveKit server and Chatto

Setup

1. Install and run LiveKit

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

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

   Development

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

   Production

   [livekit]
   enabled = true
   url = 'wss://livekit.example.com'
   api_key = 'your-api-key'
   api_secret = 'your-api-secret'
   # webhook_url = 'https://chatto.example.com/webhooks/livekit'  # defaults to {webserver.url}/webhooks/livekit

   Or use environment variables:

   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
   # CHATTO_LIVEKIT_WEBHOOK_URL=https://chatto.example.com/webhooks/livekit  # defaults to {webserver.url}/webhooks/livekit

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. You can use Chatto’s test webhook endpoints for development testing instead.

4. Restart Chatto

   Voice calls will be available immediately. A phone icon appears in every room header when LiveKit is configured.

Production Considerations

Note

Use wss:// (WebSocket Secure) URLs in production. Plain ws:// should only be used for local development.

• Network: Users connect directly to the LiveKit server from their browsers. Make sure your LiveKit instance is reachable from the public internet (or your private network, for internal deployments).
• TURN/STUN: LiveKit includes a built-in TURN server for NAT traversal. For restrictive networks, you may need to configure it to listen on port 443.
• Scaling: A single LiveKit server handles hundreds of concurrent audio-only participants. For larger deployments, LiveKit supports multi-node clustering with Redis.
• API Secret: Keep your API secret confidential. It’s used to sign JWT tokens and should never be exposed to clients.

Features

• Mute/unmute — Toggle your microphone during a call
• Audio device selection — Switch between microphones without leaving the call
• Active call indicators — Rooms with active calls show a phone icon in the room list
• Audio level visualization — Participant avatars pulse with accent-colored rings based on speaking volume
• Real-time join/leave notifications — Room members see when others join or leave a call

Disabling Voice Calls

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

[livekit]
enabled = false

When disabled, the phone icon is hidden and all voice call API endpoints return null.