
smshub
io.github.profullstack/smshub
Receive SMS on a dedicated US number for your AI agent: read texts and one-time codes. $5/month.
Documentation
SMSHub
A multi-platform, real-time SMS messaging platform with unified inbox, multi-provider support (Twilio + Telnyx), and an API-first architecture.
๐ Coming Soon: phonenumbers.bot โ Real SIM phone numbers with a developer-first API
Platforms
| Platform | Tech | Status |
|---|---|---|
| ๐ Web | Next.js 16 (App Router) | โ v1 |
| ๐ฒ PWA | Service Worker + Manifest | โ v1 |
| ๐ฑ iOS | React Native (Expo) | โ v1 |
| ๐ค Android | React Native (Expo) | โ v1 |
| ๐ฅ Desktop | Electron | โ v1 |
| โจ๏ธ CLI / TUI / MCP | smshub-cli (cli/) | โ v1 |
Install the CLI (rent numbers, read texts and codes from a terminal or an agent):
curl -fsSL https://smshub.dev/cli/install.sh | sh
https://smshub.dev/install.sh stays the desktop app installer.
Giving an AI agent its own number? examples/agent-inbox is a
dependency-free Node quickstart: wait for a one-time code over REST, verify and print signed
message.received webhooks, and MCP config for Claude Code and Cursor.
Features
- Unified Inbox โ Threaded conversations across all devices
- Real-time Messaging โ Sub-second updates via Supabase Realtime
- Multi-Provider โ Twilio + Telnyx with unified API (
sendSMS()) - Compose Flow โ New message modal with sender number picker
- Unread Tracking โ Badge counts, auto-mark read on open
- Search โ Filter conversations by name or phone number
- Contact Management โ Auto-create on inbound, inline name editing
- Delivery Receipts โ Live status updates (queued โ sent โ delivered โ failed)
- Keyboard Shortcuts โ Ctrl+N (compose), Ctrl+K (search), arrows, Escape
- Push Notifications โ Native on mobile (Expo), OS notifications on desktop (Electron)
- PWA โ Installable, offline support, background sync
- Dark Mode โ Default, developer-focused UI
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TailwindCSS |
| Mobile | React Native, Expo, expo-router |
| Desktop | Electron, electron-builder |
| Backend | Next.js API routes |
| Database | Supabase (Postgres + Realtime + Auth + RLS) |
| Providers | Twilio, Telnyx |
| Testing | Vitest (110 tests), Playwright e2e |
| CI | Husky pre-commit (tests + typecheck + lint) |
| Mobile Deploy | Expo EAS (expo.dev) |
| Desktop Build | electron-builder (AppImage, dmg, NSIS) |
Getting Started
Prerequisites
- Bun 1.4 (package manager and runtime for the web app)
- pnpm (for mobile/ and electron/ only)
- A Supabase project
- Twilio and/or Telnyx account(s)
Setup
# Install dependencies
bun install
# Copy env file and fill in your values
cp .env.example .env
# Run database migrations against your Supabase project
# (paste supabase/migrations/*.sql into the Supabase SQL editor)
# Start dev server
bun dev
Mobile (Expo)
cd mobile
pnpm install
npx expo start
# Build for iOS/Android via Expo EAS
eas build --profile production --platform all
Desktop (Electron)
cd electron
pnpm install
pnpm dev
# Package distributable
pnpm package
Environment Variables
| Variable | Description |
|---|---|
NEXT_PUBLIC_SUPABASE_URL | Supabase project URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabase anon/public key |
SUPABASE_SERVICE_ROLE_KEY | Supabase service role key (server-only) |
TWILIO_ACCOUNT_SID | Twilio Account SID |
TWILIO_AUTH_TOKEN | Twilio Auth Token |
TELNYX_API_KEY | Telnyx API Key |
TELNYX_PUBLIC_KEY | Telnyx Public Key (webhook verification) |
NEXT_PUBLIC_APP_URL | App URL (default: http://localhost:3000) |
Project Structure
src/ # Web app (Next.js)
โโโ app/
โ โโโ api/
โ โ โโโ contacts/ # GET, PATCH /api/contacts/[id]
โ โ โโโ conversations/ # GET, POST /api/conversations/[id]/read
โ โ โโโ messages/ # GET, POST /api/messages/send
โ โ โโโ providers/ # DELETE /api/providers/[id]
โ โ โโโ phone-numbers/ # DELETE /api/phone-numbers/[id]
โ โ โโโ webhooks/ # Twilio + Telnyx inbound & status callbacks
โ โโโ login/ # Login page
โ โโโ register/ # Register page
โ โโโ settings/ # Provider & phone number management
โ โโโ phonenumbers/ # phonenumbers.bot coming soon page
โ โโโ offline/ # PWA offline fallback
โโโ components/
โ โโโ inbox-client.tsx # Main inbox (sidebar + chat + realtime)
โ โโโ new-message-modal.tsx # Compose new conversation
โ โโโ contact-name-editor.tsx
โ โโโ toast-container.tsx # Toast notifications
โ โโโ sw-register.tsx # Service worker registration
โโโ contexts/
โ โโโ toast-context.tsx # Global toast state
โโโ lib/
โ โโโ providers/ # Twilio + Telnyx unified layer
โ โโโ supabase/ # Client/server/middleware helpers
โ โโโ types/ # TypeScript definitions
โโโ middleware.ts # Auth guard
mobile/ # React Native (Expo)
โโโ app/ # expo-router screens
โ โโโ (tabs)/ # Inbox + Settings tabs
โ โโโ chat/[id].tsx # Chat screen
โ โโโ auth.tsx # Login/register
โโโ lib/ # Supabase, API client, notifications
โโโ eas.json # Expo EAS build profiles
electron/ # Desktop app
โโโ main.ts # Window + tray + IPC
โโโ preload.ts # Renderer bridge
โโโ notifications.ts # Supabase Realtime โ OS notifications
โโโ updater.ts # Auto-updater
โโโ electron-builder.yml # Build config
supabase/
โโโ migrations/ # 001_initial_schema + 002_unread_tracking
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/messages/send | Send an SMS |
GET | /api/messages?conversation_id= | Get messages for a conversation |
GET | /api/conversations | List conversations |
POST | /api/conversations/[id]/read | Mark conversation as read |
GET | /api/contacts | List contacts |
PATCH | /api/contacts/[id] | Update contact name |
DELETE | /api/providers/[id] | Delete a provider |
DELETE | /api/phone-numbers/[id] | Delete a phone number |
POST | /api/webhooks/twilio | Twilio inbound webhook |
POST | /api/webhooks/telnyx | Telnyx messaging-profile webhook: inbound messages and delivery outcomes |
POST | /api/webhooks/twilio/status | Twilio delivery status callback |
POST | /api/webhooks/telnyx/status | Telnyx delivery status callback |
Outbound messages are stored as sent once the provider accepts them. Telnyx
reports the carrier outcome later in message.finalized; smshub records it as
delivered or failed with error_code / error_detail (for example 40010,
"Not 10DLC registered") and the inbox shows the reason. Each Telnyx send sets
webhook_url to /api/webhooks/telnyx, so this works even when the messaging
profile has no webhook configured. Rows sent before that can be re-checked with
bun scripts/telnyx-backfill-status.ts --dry-run (see the script header).
Scripts
pnpm dev # Start development server
pnpm build # Production build
pnpm start # Start production server
pnpm test # Run unit and contract tests
pnpm test:e2e # Run Playwright e2e tests
pnpm test:watch # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm lint # Lint source files
pnpm typecheck # TypeScript type checking
Pre-commit Hook
Every commit automatically runs:
- ๐งช Tests โ
vitest run - ๐ Type check โ
tsc --noEmit - โจ Lint โ
eslint --fixon staged.ts/.tsxfiles
Database Schema
Tables: providers, phone_numbers, contacts, conversations, messages
- Row Level Security (RLS) on all tables
- Realtime enabled on
messagesandconversations - Unread tracking via
last_read_at+ computed count
See supabase/migrations/ for the full schema.
Contributing
PRs welcome! Please ensure all checks pass before submitting:
pnpm test && pnpm test:e2e && pnpm typecheck && pnpm lint
License
MIT
@profullstack/smshubnpm install @profullstack/smshub