Skip to content

Clients

rChat clients are native apps.

ClientStatus
iOS appiPhone and iPad, iOS 17 or later. Coming to the App Store.
Android appInstalled from the download page, with built-in updates. See Receiving messages on Android and Voice and video calls.
Mac appComing 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.

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.

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 refuse ws://, except to a test relay on the same device. The relay accepts TLS 1.3 only.
  • The path must match the relay’s websocket_path exactly. 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.

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.

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.

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.