Clients
rChat clients are native apps.
| Client | Status |
|---|---|
| iOS app | iPhone and iPad, iOS 17 or later. Coming to the App Store. |
| Android app | Installed from the download page, with built-in updates. See Receiving messages on Android and Voice and video calls. |
| Mac app | Coming later. |
All clients since rChat 2.0.0 speak protocol version 3. The relay refuses a client that does not, and that app can’t connect until you update it.
Joining a relay: the invite
Section titled “Joining a relay: the invite”The usual way to point the app at a relay is the relay’s invite: a link, shown as a QR code, that the relay’s operator prints with rchat-server --print-invite (see Inviting people to your relay). It looks like this:
rchat://relay?u=wss%3A%2F%2Fchat.example.com%2F<websocket_path>&pin=rk%3A1%3A…In either app, choose Scan relay invite on the server screen, or Paste invite if it was sent to you; opening the link also works. The app shows the relay’s host and asks you to confirm, then saves the address and pins the relay’s identity at once, so even your first connection is checked. Anyone already on the relay can pass the invite on from Settings → Connection → Invite someone to this relay.
An invite contains the relay’s secret path, so it lets the holder reach the relay. It never lets anyone read messages. Share it with the people you want on the relay, not publicly.
Prefer scanning an invite inside rChat to tapping the link elsewhere. Any app on your phone can claim rchat:// links, so a link you tap could open another app instead, which would then see the relay’s address and secret path. Scanning with Scan relay invite, or pasting with Paste invite, keeps the invite inside rChat. A link form that only rChat can open (universal links) is planned.
The server URL (entering it by hand)
Section titled “The server URL (entering it by hand)”If you have no invite, choose Enter manually. Clients connect with a WebSocket URL that includes the relay’s websocket_path:
wss://chat.example.com/<websocket_path>- Use
wss://. Release builds of the app refusews://, except to a test relay on the same device. The relay accepts TLS 1.3 only. - The path must match the relay’s
websocket_pathexactly. With the wrong path, the relay answers with its decoy website and the client never connects. - Leave out the port when the relay is on 443.
- Ask the relay’s operator for its pin (
rk:1:…). Entering it means the app does not have to trust the first connection; see Relay identity. An invite does this for you.
What “Encrypted” means
Section titled “What “Encrypted” means”When the app shows Encrypted, there is a live connection to the relay and an end-to-end session with that contact. Messages are encrypted on your phone and can be decrypted only with the session keys.
How much you can rely on the contact’s keys depends on where they came from, which Contact Info shows:
- Keys from their code: you scanned or pasted their code, so the keys are the ones they gave you.
- Keys from their first message: they reached you through a request, and rChat cannot tell who is behind the key. Scan their code in person, or compare safety numbers, to check.
The app never uses “verified” as a status. A compared safety number is shown as compared, and the mark is removed if the contact’s keys change. See Security model.
Delivery and recovery
Section titled “Delivery and recovery”The app shows whether each message was sent, delivered or read, and tells you when a contact’s phone could not read some of your messages. When their phone’s device key was pinned from their code (a scan in person, or the paste that first added them), rChat resends those messages automatically; otherwise you tap Resend. See Delivery and recovery.
More in 2.0.0
Section titled “More in 2.0.0”- Media and disappearing messages: photos without metadata, files, saving to the phone, and timers.
- Notifications: alerts while rChat is closed, and their limits.
- Steady traffic: the optional setting that makes the timing of your messages reveal less.
The shared core
Section titled “The shared core”The apps are built on one Rust core, shared/rchat-core, which does the cryptography, the protocol and the connection. Native apps call it through a C interface (rchat_* functions). Its source is in rchat-core. The iOS and Android apps both use it.
The core’s connection uses BoringSSL. It does not reproduce a web browser’s TLS behaviour, and rChat does not claim that its traffic looks like a browser’s.