Skip to main content

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.

Bitchat supports sharing images and voice notes directly over the Bluetooth mesh — no servers, no cloud uploads, no accounts. Media travels in the same BLE packet stream as text, fragmented into ~469-byte pieces that reassemble at each receiving node, with an explicit accept step before anything touches the recipient’s disk.

​
How Media Travels Over the Mesh

All media uses Bitchat’s BLE fragmentation layer:
  • Payloads that exceed the link MTU are split into ~469-byte fragments, each carrying an 8-byte fragment ID and an index/total header.
  • Fragments relay independently and reassemble at each receiving node (up to 128 concurrent assemblies, 30-second timeout).
  • The hard cap for any single media transfer is 1 MiB (1,048,576 bytes) — this applies to images, voice notes, and any other file type.
  • Images are additionally capped at 512 KiB after processing; voice notes are capped at 512 KiB.
  • Media is only available in the #mesh channel and in private DMs. It is not available in geohash location channels.
The courier system carries text only. Images and voice notes do not travel via the offline courier relay chain. If a recipient is out of Bluetooth range when you send media, the transfer will not complete via courier — it must be retried when both devices are in range.

​
Sending an Image

1

Tap the camera icon

Tap the camera button in the composer toolbar, or use the share extension from your photo library or another app.
2

Select your image

Choose an image from your photo library. On macOS, a file picker opens instead. Source images up to 10 MiB are accepted for processing.
3

Automatic processing

Before transmission, Bitchat processes the image:
  • Scales it down so the longest side is at most 448 pixels.
  • Re-encodes as JPEG at up to 0.82 quality, iterating down to 0.3 if needed to reach the ~45 KB target size.
  • Strips all EXIF, GPS, TIFF, IPTC, and XMP metadata from the output. The transmitted JPEG contains no location or device information.
4

Transfer begins

The processed image is fragmented and broadcast over the mesh (public channel) or sent directly to the recipient (private DM). A progress indicator appears in the chat bubble.

​
Sending a Voice Note

1

Press and hold the microphone icon

Tap and hold the microphone button in the composer toolbar to start recording. Release to send, or swipe away to cancel.
2

Recording

Audio is captured at 16 kHz, mono, AAC (MPEG-4 audio) at 16 kbps. The maximum recording duration is 120 seconds. A short padding delay of 0.5 seconds is applied on stop to avoid clipping the end of speech.
3

Send

Releasing the button stops recording and immediately begins the transfer. The voice note is sent as an .m4a file over the mesh.
Microphone permission is required to record voice notes. Grant it from the system permission prompt, or go to Settings → Privacy → Microphone → Bitchat.

​
Receiving Media — Explicit Accept Required

Bitchat never saves media to disk automatically. When a peer sends you an image or voice note, you see a transfer request in the chat. You must explicitly accept before anything is written to storage. This prevents an adversarial peer from silently filling your disk or delivering unexpected content. After accepting:
  • The file is saved to Application Support under files/images/incoming/ or files/voicenotes/incoming/.
  • A receipt acknowledgment is sent back to the sender.
  • The file is displayed inline in the chat.
If you decline, the transfer is cancelled and nothing is written to disk.

​
Storage Location and Quota

All accepted media is stored in the app’s Application Support directory (files/), organized by type and direction: 
files/
  images/
    incoming/
    outgoing/
  voicenotes/
    incoming/
    outgoing/
  files/
    incoming/
    outgoing/
The incoming media store enforces a 100 MB quota across all incoming files. When a new transfer would push usage over the quota, Bitchat evicts the oldest incoming files (by last-modified date) until there is room. Eviction only affects files in the incoming directories; your outgoing files are not evicted. In-flight live voice captures (voice_live_* prefix) are skipped by the eviction pass.

​
Automatic Expiry

All media — incoming and outgoing — is automatically deleted after 7 days (604,800 seconds). This age-based sweep runs across all media subdirectories and applies the same exclusions as quota eviction: in-flight captures and files reserved by an in-progress delivery or deletion are left alone regardless of age. The age limit exists on the same principle as courier envelope and gossip archive lifetimes: limiting how long sensitive content persists on a device that could be seized or lost.

​
Panic Wipe

A panic wipe (triple-tap the Bitchat logo) immediately deletes the entire files/ directory tree — all incoming and outgoing images, voice notes, and other files — then recreates the empty directory structure. The wipe also resets the media receipt index and all in-memory delivery reservations. The wipe is coordinated with a durable marker so that if the app is killed mid-wipe, the next launch detects the incomplete state and completes the deletion before loading any application data.

​
Media in Private vs. Public Chats

Media sent in a private DM is encrypted end-to-end by the Noise session before transmission. The file packet travels as noiseEncrypted ciphertext on the mesh — intermediate nodes cannot access the payload.Private media transfers use a receipt-based delivery confirmation system. If the session is interrupted during a transfer, Bitchat can retry on reconnect (up to 2 retries per message).

Build docs developers (and LLMs) love

Get started for freeTalk to us