BWTalk #

BWTalk adds chat as well as audio and video calls to owncloud.online: one-to-one and group conversations, public rooms with a guest link, screen sharing, and files from the instance right in the chat. Calls run directly between the browsers without any extra service. For large calls and for participants behind strict firewalls, add a media server and a TURN server.

Requirements #

Installation #

1. Enter the API key, see the box above.
2. In the app menu, open Market, go to the app, and install it, or use the command line:

sudo -u www-data php8.4 occ market:install bwtalk

The app creates its tables when it is enabled. "BWTalk" then appears in the app menu, and the settings are under Settings → Admin → Additional in the "BWTalk" section. Chat and calls within the same network work without further setup.

Configuration #

STUN and TURN #

The default is a public STUN server run by Google. If you run coturn, enter it as the STUN server as well.

For coturn, set in /etc/turnserver.conf:

use-auth-secret
static-auth-secret=<long-random-secret>

Then enter the TURN address in BWTalk, for example turn:turn.example.org:3478, together with the same secret. From it, BWTalk creates credentials that are valid for six hours and are only handed to participants of a room. Fixed credentials with username and password work as well.

Media server (LiveKit) #

Without a media server, the browsers connect to each other directly. This works for about 4 to 6 participants. With the LiveKit media server, each person sends only one stream in three resolutions, and the server passes the right one to each receiver. LiveKit is open source (Apache 2.0) and runs on your own server.

1. Install LiveKit. It is a single program and is also available as the Docker image livekit/livekit-server.

2. Create /etc/livekit.yaml:

   yamlCopy

   port: 7880
   rtc:
     tcp_port: 7881
     port_range_start: 50000
     port_range_end: 60000
     use_external_ip: true
   keys:
     bwtalk: <long-random-secret>
   

3. Start it, for example as a systemd service or with livekit-server --config /etc/livekit.yaml.

4. Put a reverse proxy with TLS in front of it so that the server is reachable as wss://sfu.example.org. Open UDP 50000 to 60000 and TCP 7881.

5. In BWTalk, enter:

"API key" and "API secret" belong to LiveKit here, not to the Marketplace. BWTalk uses them on the server to create the access tokens for the rooms; the secret never leaves the server. If the media server cannot be reached, the call falls back to direct connections and shows a notice.

Recording #

Without egress, the moderator's browser records the call (WebM, 1280 × 720) and uploads the file to the conversation folder. With the LiveKit Egress service, the recording is made on the server as MP4 and stays in the output directory of the egress container. While a recording runs, all participants see a red notice.

More settings #

You can also set every value with occ:

sudo -u www-data php8.4 occ config:app:set bwtalk turn_server --value=turn:turn.example.org:3478
sudo -u www-data php8.4 occ config:app:set bwtalk share_expiry_days --value=30

Message retention #

Each conversation can have a retention period. The ExpireMessages background job deletes older messages once an hour; pinned messages stay. To run it by hand:

sudo -u www-data php8.4 occ bwtalk:expire

Usage #

• Start a conversation: "New conversation" lists all accounts of the instance. A click starts a one-to-one conversation. "Add person or group" turns it into a group conversation. If you add a group of the instance, new group members join automatically.
• Call: "Start audio call" or "Start video call". Before joining, you can check your camera and microphone. During the call, "Share screen", "Raise hand", reactions, and background effects are available. The browser computes the background effects; the image does not leave the device for this.
• Invite guests: "Publicly accessible (guest link)" makes a conversation public. Guests join through the link without an account, optionally with a password.
• Moderate: moderators turn on the waiting room, let people in, mute participants, remove them, and start recordings.
• Chat: replies, reactions, mentions with @, formatting such as **bold** and *italic*, threads, forwarding, pinned messages, polls, and voice messages. "Share file" posts a file from the instance into the conversation. Uploaded files and recordings are stored in the BWTalk/<room> folder of the person who shared them.
• Schedule meetings: appointments per conversation with an email invitation and an ICS file.
• Mobile: BWTalk can be installed on a phone as a web app and reports calls and messages with push notifications.

Limits and notes #

• Without a media server, a call works for about 4 to 6 participants.
• End-to-end encryption protects against the media server, not against the owncloud.online server, which creates and distributes the room key.
• Files in the chat are shared through public links with a random token. Whoever passes on the link passes on the file. The link disappears with the message or the conversation.
• Members of an added group see the existing history of the conversation. Groups with more than 200 members cannot be added to a conversation.
• Only accounts of the instance can upload files to the chat, up to 200 MiB per file. The PHP limits upload_max_filesize and post_max_size apply as well. Guests who joined through the guest link cannot upload files.
• Phone dial-in is prepared but does not work on its own. It needs a SIP provider with ongoing costs, requires a media server, and rules out end-to-end encryption.
• A public room accepts at most 200 guests. The app stores room passwords as a hash, and the server's brute-force protection slows down failed attempts.
• New messages arrive by long polling, without an extra service.
• Guest accounts of the Guests app can use BWTalk only if bwtalk is on the app whitelist for guests.