Skip to content

SMS Campaigns

Text message outreach via a Termux Android bridge. Enable with ENABLE_SMS=true.

How It Works

  1. Configure the bridge — set TERMUX_API_URL and TERMUX_API_KEY to connect to an Android device running Termux with the SMS plugin
  2. Create contact lists — import contacts or build lists from existing supporters
  3. Write a campaign — compose a message template with variable substitution (name, location, etc.)
  4. Launch the campaign — messages are queued via BullMQ and sent serially through the device
  5. Monitor responses — incoming replies are synced and classified by keyword

Key Features

  • Contact lists — import, tag, and segment contacts for targeted outreach
  • Message templates — reusable templates with variable placeholders
  • BullMQ queue — serial delivery with configurable delays between messages (SMS_DELAY_BETWEEN_MS)
  • Response sync — incoming SMS replies synced and classified automatically (SMS_RESPONSE_SYNC_INTERVAL_MS)
  • Device monitoring — health checks and status reporting for the connected Android device (SMS_DEVICE_MONITOR_INTERVAL_MS)
  • Conversation view — threaded message history per contact
  • Retry logic — configurable retry attempts for failed deliveries (SMS_MAX_RETRIES)

Setup Wizard

The SMS Setup page (/app/sms/setup) provides a guided three-step wizard for connecting your Android phone:

Step 1: Prepare Phone

Install Termux and Termux:API from F-Droid on the Android device, then generate a shared API key from the admin panel. The key is used for mutual authentication between the server and the phone.

Step 2: Connect

Choose one of two connection methods:

  • Tailscale Auto-Discovery (recommended) -- enter your Tailscale API key and the wizard automatically discovers devices on your tailnet, highlights Android devices, and pre-fills the stable IP address
  • Manual URL Entry -- enter the Termux API server URL directly (typically http://100.x.x.x:5001 when using Tailscale)

Step 3: Test and Save

Run a live connection test against the phone to verify the URL and API key are correct. The test displays device health info (uptime, messages sent). Once the test passes, save the configuration to enable SMS features platform-wide.

The wizard stores credentials encrypted in the database and updates the enableSms feature flag automatically.

Admin Routes

  • /app/sms/setup -- guided setup wizard with Tailscale auto-discovery
  • /app/sms -- SMS dashboard with campaign overview and device status
  • /app/sms/contacts -- manage contact lists and entries
  • /app/sms/campaigns -- create and monitor SMS campaigns
  • /app/sms/conversations -- view threaded conversations with contacts