Repository avatar
AI Tools
v1.11.1
active

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

SMSHub logo

Next.js React TypeScript Supabase Expo Electron Tests License: MIT PRs Welcome

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

PlatformTechStatus
๐ŸŒ WebNext.js 16 (App Router)โœ… v1
๐Ÿ“ฒ PWAService Worker + Manifestโœ… v1
๐Ÿ“ฑ iOSReact Native (Expo)โœ… v1
๐Ÿค– AndroidReact Native (Expo)โœ… v1
๐Ÿ–ฅ DesktopElectronโœ… v1
โŒจ๏ธ CLI / TUI / MCPsmshub-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

LayerTechnology
FrontendNext.js 16, React 19, TailwindCSS
MobileReact Native, Expo, expo-router
DesktopElectron, electron-builder
BackendNext.js API routes
DatabaseSupabase (Postgres + Realtime + Auth + RLS)
ProvidersTwilio, Telnyx
TestingVitest (110 tests), Playwright e2e
CIHusky pre-commit (tests + typecheck + lint)
Mobile DeployExpo EAS (expo.dev)
Desktop Buildelectron-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

VariableDescription
NEXT_PUBLIC_SUPABASE_URLSupabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEYSupabase anon/public key
SUPABASE_SERVICE_ROLE_KEYSupabase service role key (server-only)
TWILIO_ACCOUNT_SIDTwilio Account SID
TWILIO_AUTH_TOKENTwilio Auth Token
TELNYX_API_KEYTelnyx API Key
TELNYX_PUBLIC_KEYTelnyx Public Key (webhook verification)
NEXT_PUBLIC_APP_URLApp 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

MethodEndpointDescription
POST/api/messages/sendSend an SMS
GET/api/messages?conversation_id=Get messages for a conversation
GET/api/conversationsList conversations
POST/api/conversations/[id]/readMark conversation as read
GET/api/contactsList 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/twilioTwilio inbound webhook
POST/api/webhooks/telnyxTelnyx messaging-profile webhook: inbound messages and delivery outcomes
POST/api/webhooks/twilio/statusTwilio delivery status callback
POST/api/webhooks/telnyx/statusTelnyx 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:

  1. ๐Ÿงช Tests โ€” vitest run
  2. ๐Ÿ” Type check โ€” tsc --noEmit
  3. โœจ Lint โ€” eslint --fix on staged .ts/.tsx files

Database Schema

Tables: providers, phone_numbers, contacts, conversations, messages

  • Row Level Security (RLS) on all tables
  • Realtime enabled on messages and conversations
  • 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

NPM
@profullstack/smshub
Install Command
npm install @profullstack/smshub

Remote