Join a federated room

Federation lets you have a room with people on another ScaiWave server — another tenant in the same instance, or a self-hosted server entirely. Everyone in the room sees the same messages, reactions, and presence.

Prerequisites#

The other server needs to:

• Be reachable on the internet (or your private network).
• Publish a valid /.well-known/scaiwave/server descriptor.
• Have your server's tenant on its accepted-peer list (or run an open peering policy).

Most ScaiLabs-hosted tenants federate openly with each other; for private hosts your admin coordinates peering with theirs.

Invite a federated participant#

Via the UI#

In an existing room → + Invite → toggle Federated. Type the full FQID:

1

@alice:acme.scaiwave.com

Click Invite. Your server signs the invite with its Ed25519 key and POSTs it to acme.scaiwave.com. The foreign user gets the invite in their notification panel; when they accept, they appear in your member list as @alice:acme.scaiwave.com.

Via the API#

1
2
3
4

POST /v1/rooms/{room_id}/invitations
Content-Type: application/json

{ "fqid": "@alice:acme.scaiwave.com" }

As a fresh DM#

For 1:1 conversations across servers, use the federated-DM endpoint:

1
2
3
4

POST /v1/me/federated-dms
Content-Type: application/json

{ "fqid": "@alice:acme.scaiwave.com" }

Creates a DM room with you and the foreign user, federated to their server.

How it shows up#

• Member list: foreign participants appear with their full FQID.
• Chat header: 🌐 badge indicating "federated room".
• Messages: indistinguishable from local — same bubbles, same reactions, same threading.
• Presence: their server publishes; you see online/idle/etc.
• Calls: work normally; the LiveKit token gets minted by your server but the foreign user joins it like any other call.

What's different#

• Search: foreign messages are stored locally and indexed — you'll find them in search. But you can't search the foreign side's full corpus from your end.
• Notifications: yours are governed by your settings; theirs by theirs.
• Plugins: each side's AI uses its own server's plugins. An AI on your side asking the AI on their side for a search is two separate plugin calls.

What doesn't work#

• Incognito rooms can't federate. The protocol refuses.
• Bridge rooms can't federate. They're already proxying for another platform.
• Federation invites time out after 7 days if the foreign user doesn't accept.
• End-to-end encryption: not yet. Messages are signed server-to-server, but the server can read them.

Removing a federation link#

A federated participant who leaves (or is kicked) is removed like any other member. To stop all federation traffic with a peer: admin → Federation → Peers → Remove. This severs every shared room — anyone on either side is removed.

When peering breaks#

Federation is per-room and per-event. A peer being temporarily unreachable doesn't lose messages — your server retries with exponential backoff up to 24 hours. After that, the event is marked failed in your audit log and won't be delivered.

If you suspect a peer is broken, admin → Federation → Peers → the peer's row shows last_seen and last_error columns.

Where to go next#

• Tutorial: Enable federation with a peer — admin setup.
• Concepts: Federation.
• API: Federation.