Skip to content

README.md

Latest commit

 

History

History
122 lines (90 loc) · 4.33 KB

README.md

File metadata and controls

122 lines (90 loc) · 4.33 KB

NexusBridge

A complete SMS Bridge system that connects an Android phone to a web-based messaging UI via a WebSocket relay server.

Get Started

👉 Go to https://sms-bridge-jmtdi.devpush.app/ (Recommended)

The builder will walk you through three steps:

  1. Deploy your server — click the "Deploy to Railway" button to spin up a free server in one click
  2. Enter your server URL — paste the Railway URL you get after deploying
  3. Build your app — the builder generates and downloads a zip containing:
    • nexusbridge.apk — ready-to-install Android app
    • index.html — web messaging UI, pre-configured for your server

No coding required.

Self-Hosting the Builder

If you want to run the builder yourself instead of using the hosted version:

git clone https://github.com/JMTDI/nexussmsbridge
cd nexussmsbridge
pip install -r requirements.txt
python builder.py

Open http://localhost:8000 in your browser.

Architecture

Android App (phone) ──WebSocket──▶ server.py ──WebSocket──▶ index.html (browser)
                                       │
                                  REST API
                                  /new-session
                                  /session-status/{token}

Components

1. server.py — Python Bridge Server

Runs on port 8000 (HTTP + WebSocket on the same port).

Setup:

pip install -r requirements.txt
python server.py

Endpoints:

  • GET / → serves index.html
  • GET /new-session → creates a new session, returns { sessionToken, pin, qrData }
  • GET /session-status/{token} → returns phone connection status
  • GET /health → health check
  • wss://host/ws/{token}?role=phone|client → WebSocket bridge

2. index.html — Web Client

Single-file, no build step required. Open directly in a browser or via https://yourserver.com/.

Features:

  • Pairing screen with QR code + 6-digit PIN
  • Full conversation list + thread view
  • Real-time messaging via WebSocket
  • Dark theme, fully responsive
  • Session saved in localStorage for reconnection

3. Android App (android/)

Package: com.nexusbridge.smsbridge

Features:

  • D-pad navigable numpad for PIN entry
  • ZXing QR code scanner
  • Foreground service maintaining persistent WebSocket connection
  • Reads SMS/MMS via ContentProvider
  • Sends SMS via SmsManager
  • BroadcastReceiver for incoming SMS
  • Exponential backoff reconnection

Build: Open android/ folder in Android Studio and run on device.

Required Permissions: READ_SMS, SEND_SMS, RECEIVE_SMS, READ_CONTACTS, INTERNET, FOREGROUND_SERVICE, POST_NOTIFICATIONS, CAMERA

Message Protocol

All WebSocket messages are JSON:

{ "type": "...", "payload": { ... } }
Type Direction Description
sms_list phone → client Full conversation list
sms_thread client → phone, phone → client Request/response for thread messages
sms_send client → phone Send SMS { to, body }
sms_incoming phone → client New inbound SMS notification
read_receipt client → phone Mark thread as read
typing_indicator client → phone Typing notification
mms_attachment phone → client Base64 MMS attachment
contacts_list phone → client Contact directory
ping / pong both 30-second keepalive
phone_connected server → client Phone joined the session
phone_disconnected server → client Phone disconnected
connection_status server → client Current phone connection state

Session Flow

  1. Web client calls GET /new-session → gets sessionToken + pin + qrData
  2. Web client connects WebSocket as role=client
  3. Web client polls GET /session-status/{token} every 2 seconds
  4. Android app scans QR or enters PIN → connects WebSocket as role=phone
  5. Server links phone ↔ client, notifies client via phone_connected
  6. All messages relay bidirectionally in real time