Bitchat organizes communication into four distinct channel types, each suited to a different context and range. The mesh channel (Documentation Index
Fetch the complete documentation index at: https://mintlify.com/permissionlesstech/bitchat/llms.txt
Use this file to discover all available pages before exploring further.
#bluetooth) is a local public space for everyone in Bluetooth reach — no internet needed. Private groups are invite-only, end-to-end encrypted rooms that work over the mesh. Location channels use geohash coordinates over Nostr to connect people across a city, province, or country. Direct messages are one-on-one private conversations that automatically choose the best available transport. Understanding which channel to use helps you communicate effectively whether you’re offline at a protest, chatting with nearby strangers, or coordinating across a city.
Mesh Channel (#bluetooth)
The mesh channel is the default public space in Bitchat. It requires no internet connection, no accounts, and no prior relationship with other participants.
Transport: Bluetooth LE mesh network — every nearby device acts as both sender and relay. Messages can travel up to 7 hops through intermediate devices to reach the edges of the local mesh.
Scope: All devices within multi-hop Bluetooth range. Coverage depends on device density; in a crowd with many Bitchat users, the effective range is much larger than a single Bluetooth link.
Message signing and history. Every public message on the mesh carries an Ed25519 signature from the sender. A 6-hour sliding cache of up to 1,000 recent packets is maintained on each device and reconciled with peers using gossip sync (compact GCS filters exchanged every ~15 seconds). When you join a mesh that has been active, you receive recent history automatically. This cache persists to disk, so a device that re-enters a partition serves history it carried from elsewhere.
Use cases: Offline communication in areas without internet, protests, disaster zones, remote areas, or any situation where local group coordination matters.
The mesh channel is entirely local. Messages in
#bluetooth are not forwarded to Nostr and cannot be read by anyone outside Bluetooth relay range.Private Groups
Private groups are end-to-end encrypted, invite-only rooms that run over the Bluetooth mesh. Group membership and keys are managed locally — there is no server tracking group state. Creating and managing groups. Use the/group IRC-style command to create a group, invite members, and manage membership. Group state (name, roster, creator public key, and key epoch) is stored on each participating device. Group keys are held in the iOS or macOS Keychain.
Encryption. Group messages are encrypted under a shared group key and broadcast over the mesh as opaque ciphertext (packet type 0x25). Intermediate relay nodes cannot read the content. Only devices with the current group key can decrypt the messages.
Key rotation. Each group has a key epoch counter. When a member is removed or the group key is rotated, a new key is distributed to remaining members over authenticated one-to-one Noise sessions. The transport delivers group invites and key updates via sendGroupInvite and sendGroupKeyUpdate, both of which are sent as directed packets to specific peers.
Scope. Group messages propagate over the Bluetooth mesh like any other broadcast, but only members with the current key can read them. Non-members relay the encrypted packets without being able to inspect them.
Location Channels
Location channels let you talk to people in a specific geographic area over the internet, using the Nostr relay network. Each channel is defined by a geohash — a short string that encodes a rectangular region on Earth at a given precision. Transport: Nostr protocol over internet relays (290+ relays worldwide). Internet access is required to send and receive location channel messages. Geohash precision levels. The length of the geohash string controls the channel’s geographic scope:| Level | Geohash length | Approximate scope | Example |
|---|---|---|---|
building | 8 characters | Single building | #dr5rsj7e |
block | 7 characters | City block | #dr5rsj7 |
neighborhood | 6 characters | District / neighborhood | #dr5rs |
city | 5 characters | City level | #dr5r |
province | 4 characters | State / province | #dr5 |
region | 2 characters | Country / large region | #dr |
#dr5rs is visible to anyone subscribed to that neighborhood cell, regardless of where they physically are — the channel is geographic in intent, but Nostr delivery is internet-wide.
Ephemeral keys. Each geohash area uses fresh cryptographic keys rather than the device’s long-term Nostr identity. This limits cross-channel correlation: observers cannot trivially link your activity in #dr5rsj7 to activity in a different cell.
Presence. Bitchat publishes kind-20001 geohash presence heartbeats to signal that you are in a location channel. Presence events carry only the geohash tag and empty content — no nickname, no message.
Use cases: Community discussion for a local area, event coordination, neighborhood announcements, or any context where geographic proximity matters more than Bluetooth range.
Location channels require an internet connection to Nostr relays. They are not bridged to the Bluetooth mesh
#bluetooth channel; they are separate rooms.Direct Messages
Direct messages (DMs) are private one-to-one conversations. They are always end-to-end encrypted and use theMessageRouter’s intelligent transport selection to reach the recipient by the best available path.
Encryption over Bluetooth. When a live Noise XX session exists with the recipient, DMs ride inside that authenticated, forward-secret session as typed ciphertext. Intermediate relay nodes see only opaque noiseEncrypted packets.
Encryption over Nostr. When Bluetooth is unavailable, DMs to mutual favorites use Bitchat’s proprietary private-envelope protocol: an unsigned rumor (kind 14) is encrypted and placed inside a sender-signed seal (kind 13), then wrapped in a gift-wrap envelope (kind 1059) signed with a one-time key.
Delivery and read receipts. DMs include delivery acknowledgements and read receipts that travel over the same transport path as the message. The sender outbox retains unacknowledged messages (up to 100 per peer, 24-hour TTL) and re-sends on reconnect.
For the full routing logic, see the Architecture page.
Channel Comparison
| Channel | Transport | Scope | Internet Required | Encryption |
|---|---|---|---|---|
#bluetooth | Bluetooth LE mesh | Local multi-hop range | No | Signed, not encrypted |
| Private groups | Bluetooth LE mesh | Local multi-hop range | No | End-to-end (group key) |
| Location channels | Nostr relays | Geographic area (geohash) | Yes | Signed, not encrypted |
| Direct messages | BLE mesh → Nostr → courier | Peer-to-peer | Preferred, not required | End-to-end (Noise XX or private envelope) |
Using Channels
Step-by-step guide to sending messages in each channel type, using IRC-style commands, and managing your conversations.
Location Channels
How to join and post in geohash-based location channels, select the right precision level, and understand the geographic scope of each cell.