Connect with other Zulip servers

Federation lets authenticated users on different Zulip servers exchange messages. In federated conversations, each user is identified by a unique username@domain. This identity is separate from their contact email address.

Federation is off by default. A server administrator must enable it, and an organization owner must activate an identity domain. Organizations choose separately whether to allow direct messages, private named groups, and authenticated public channels. Each channel must also be explicitly federated. These settings never allow access to channels without signing in.

Private named groups are invite-only. Their creator decides whether other participants may invite people. A name does not make a group publicly joinable.

Set up your federation identity and inbox

Go to Account & privacy.
Under Federation, enter a Federation username, and click Set federation username. Your username must be unique in your organization and cannot be changed after assignment.
Choose whether to Receive federated direct messages and Receive private federated group invitations and messages.
Click Save changes.

Your organization must also allow the corresponding type of conversation. If federation is unavailable, contact your organization owner.

Configure organization federation

Only organization owners can activate an identity domain or change the organization’s federation switches.

Go to Organization settings.
Under Federation, enter an Identity domain. Use your Zulip hostname, or a domain you control. For a different domain, ask your domain administrator to add the DNS TXT record shown in the form.
Click Verify and activate identity domain. The identity domain cannot be changed after activation.
Choose whether to allow federated direct messages, private named groups, and authenticated public channels.
Click Save changes.

When using a separate identity domain, your server administrator must publish the Public discovery document shown in these settings on that domain.

Block a server

Under Federation, enter a Server domain and click Block server. Click Unblock next to an existing block to remove it. Click Refresh to read the latest settings and block list.

Personal blocks reject private messages and invitations. Organization administrators can also manage server blocks in organization settings. These blocks reject private delivery and hide channel message bodies while keeping the sender’s identity and domain visible. Unblocking does not restore bodies that have already been discarded.

Start a private conversation

Click Federated conversations below Direct messages in the left sidebar, or under Federation in your account settings. Select New conversation, enter recipients as username@domain, write a message, and click Send. Separate multiple recipients with spaces, commas, or semicolons.

For a named group, enter a Private group name. Select Any group participant may invite others if you want participants to send invitations. Otherwise, only the creator can invite. An unnamed conversation has exactly two participants.

Select an existing conversation to read and reply. Under Group invitations, enter handles and click Update invitations. The creator can also change the invitation permission here. New participants do not receive earlier history. Unsent drafts are saved separately for each conversation on your device.

Federate a channel

Create an empty channel, open its settings, and find Federation under General. Choose Hosting and Participation, then click Configure federation. Hosting cannot be changed after configuration.

Single home: The home server hosts messages and publishes shared moderation.
Multiple homes: Each server hosts and moderates its own mirror.
Configured servers: An administrator enters domains configured by the server administrator. To mirror an existing channel, enter its origin domain and federation ID instead.
Authenticated users from other servers: Your organization must enable public channel federation, and the local channel must be public and require sign-in. Use Find a public channel to mirror to choose an existing channel.

Moderate a channel mirror

In the channel’s Federation settings, look up a Local federation username, choose read or write restrictions, and click Save restrictions. These controls restrict that user’s access on your server. Revoking read access also prevents sending messages.

To hide another server’s messages, enter a Source server domain and click Hide source. To target one user, also enter their source user UUID, available in the message’s federation metadata through the API. Hidden messages retain an identity placeholder. Click Remove block to allow future content from that source. Earlier discarded bodies are not restored.

On a single-homed channel’s home server, moderators may select Apply the home server’s policy to all mirrors. Other source blocks apply to the local mirror.