SMS Forwarder

An Android application that automatically forwards incoming SMS messages to Telegram. Features spam detection, reliable background service with auto-restart, and a modern Material 3 UI.

Features

• Telegram Forwarding: Automatically forward SMS messages to a Telegram chat via bot API
• Spam Detection: Rule-based spam filtering with keywords, patterns, blacklists, and whitelists
• Reliable Background Service: Foreground service with wake lock and auto-restart on termination
• Boot Persistence: Automatically starts on device boot
• Health Monitoring: Periodic health checks with status notifications
• Message History: Local database storage of all received messages
• Notification System: Configurable notifications for forwarding success, errors, and spam detection
• Modern UI: Material 3 design with Jetpack Compose
• Dark Mode: System, light, and dark theme support

Screenshots

Home Screen	Settings	History	Spam Rules

Note: Add screenshots to a screenshots/ folder in the project root.

Architecture

flowchart TD
    subgraph Android_System [Android System]
        SMS[Incoming SMS]
        Boot[Boot Completed]
    end

    subgraph Receivers [Broadcast Receivers]
        SmsReceiver[SmsReceiver]
        BootReceiver[BootReceiver]
        RestartReceiver[RestartReceiver]
    end

    subgraph Service [Background Service]
        SmsForwarderService[SmsForwarderService]
        ForwarderManager[ForwarderManager]
        HealthChecker[HealthChecker]
    end

    subgraph Domain [Domain Layer]
        SpamDetector[SpamDetector]
        TelegramForwarder[TelegramBotForwarder]
    end

    subgraph Data [Data Layer]
        Repository[SmsRepository]
        Database[(Room Database)]
        Preferences[(DataStore)]
    end

    subgraph External [External Services]
        TelegramAPI[Telegram Bot API]
    end

    SMS --> SmsReceiver
    Boot --> BootReceiver
    BootReceiver --> SmsForwarderService
    RestartReceiver --> SmsForwarderService
    SmsReceiver --> ForwarderManager
    ForwarderManager --> SpamDetector
    SpamDetector --> Repository
    ForwarderManager --> TelegramForwarder
    TelegramForwarder --> TelegramAPI
    ForwarderManager --> Repository
    Repository --> Database
    SmsForwarderService --> HealthChecker
    HealthChecker --> Preferences

Loading

Data Flow

1. SMS Received: Android broadcasts SMS_RECEIVED intent
2. SmsReceiver: Captures the broadcast, extracts message data
3. ForwarderManager: Orchestrates the forwarding pipeline
4. SpamDetector: Checks message against spam rules
5. TelegramBotForwarder: Sends message to Telegram via Bot API
6. SmsRepository: Saves message history to Room database

Project Structure

app/src/main/java/com/example/sms_fwd_1/
├── data/
│   ├── local/
│   │   ├── entity/          # Room entities (LogEntity, SmsHistoryEntity, SpamRuleEntity)
│   │   ├── AppDatabase.kt   # Room database definition
│   │   └── *Dao.kt          # Data Access Objects
│   ├── preferences/
│   │   └── AppPreferences.kt # DataStore preferences manager
│   └── repository/
│       └── SmsRepository.kt  # Data repository
├── domain/
│   ├── forwarder/
│   │   ├── TelegramBotForwarder.kt  # Telegram implementation
│   │   ├── EmailForwarder.kt        # Email implementation (placeholder)
│   │   ├── WebhookForwarder.kt      # Webhook implementation (placeholder)
│   │   └── SmsForwarder.kt          # SMS forwarding (placeholder)
│   ├── model/
│   │   ├── SmsMessage.kt     # SMS domain model
│   │   └── ForwardResult.kt  # Forwarding result sealed class
│   └── spam/
│       ├── SpamDetector.kt   # Spam detection logic
│       └── SpamRule.kt       # Spam rule definitions
├── receiver/
│   ├── SmsReceiver.kt        # SMS broadcast receiver
│   ├── BootReceiver.kt       # Boot completed receiver
│   └── RestartReceiver.kt    # Service restart receiver
├── service/
│   ├── SmsForwarderService.kt # Main foreground service
│   ├── ForwarderManager.kt    # Forwarding orchestrator
│   ├── NotificationService.kt # Notification management
│   ├── HealthChecker.kt       # Service health monitoring
│   └── AppLogger.kt           # Logging utility
├── ui/
│   ├── components/           # Reusable Compose components
│   ├── navigation/           # Navigation setup
│   ├── screens/              # Screen composables and ViewModels
│   └── theme/                # Material 3 theme
├── worker/
│   └── HealthCheckWorker.kt  # WorkManager health check
├── MainActivity.kt           # Main activity
└── SmsForwarderApp.kt        # Application class

Setup & Installation

Prerequisites

• Android device running Android 8.0 (API 26) or higher
• Telegram account with a bot created via BotFather

Installation

1. Download the APK from Releases
2. Enable "Install from unknown sources" in device settings
3. Install the APK
4. Grant required permissions when prompted

Building from Source

# Clone the repository
git clone https://github.com/yourusername/sms-forwarder.git
cd sms-forwarder

# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

Configuration

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the prompts to set bot name and username
4. Copy the Bot Token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your Chat ID

Option A: Using @userinfobot (Recommended)

1. Search for @userinfobot on Telegram
2. Start the bot - it will reply with your Chat ID

Option B: Using @getidsbot

1. Search for @getidsbot on Telegram
2. Start the bot or forward a message to get the Chat ID

Option C: For Groups

1. Add your bot to the group
2. Send a message in the group
3. Visit: https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
4. Find the chat.id in the response (negative number for groups)

3. Start the SMS Forwarder Bot

IMPORTANT: You must complete this step before the bot can send you messages!

1. Open Telegram and search for @smsfwd1bot
2. Tap Start or send any message to the bot
3. The bot will confirm it can now send you messages

Note: Telegram bots cannot initiate conversations due to privacy restrictions. You must message the bot first to allow it to send you forwarded SMS messages.

4. Configure the App

1. Open SMS Forwarder app
2. Go to Settings > Telegram Configuration
3. Enter your Bot Token
4. Enter your Chat ID
5. Tap Test Connection to verify
6. Enable Telegram Forwarding
7. Return to Home and enable SMS Forwarding

Permissions

Permission	Purpose
RECEIVE_SMS	Intercept incoming SMS messages
READ_SMS	Access SMS content for forwarding
INTERNET	Send messages to Telegram API
POST_NOTIFICATIONS	Show status and error notifications
WAKE_LOCK	Keep CPU active during SMS processing
RECEIVE_BOOT_COMPLETED	Auto-start service on device boot
FOREGROUND_SERVICE	Run persistent background service
SCHEDULE_EXACT_ALARM	Schedule service restart if terminated

Technical Details

Service Lifecycle

The app uses a foreground service to ensure reliable SMS forwarding:

1. Startup: Service starts via Application.onCreate() or boot receiver
2. Foreground Mode: Displays persistent notification (required for Android 8.0+)
3. Wake Lock: Partial wake lock prevents CPU sleep during processing
4. Watchdog: Internal timer checks health every 5 minutes
5. Auto-Restart: If killed unexpectedly, AlarmManager reschedules restart

Auto-Restart Mechanism

Service Termination (unexpected)
        │
        ▼
   onDestroy()
        │
        ▼
  Schedule AlarmManager
  (5 second delay)
        │
        ▼
  RestartReceiver
        │
        ▼
  SmsForwarderService.startService()

Spam Detection

The spam detector supports multiple rule types:

• Keywords: Block messages containing specific words/phrases
• Patterns: Regex patterns for flexible matching
• Blacklist: Block specific phone numbers
• Whitelist: Always allow specific numbers (overrides other rules)

Message Format

Forwarded messages use HTML formatting:

📨 New SMS Received

📱 From: +1234567890
🕐 Time: 2024-01-15 10:30:45

💬 Message:
Your SMS content here...

Troubleshooting

Service Stops Unexpectedly

1. Disable battery optimization for the app
2. Enable "Allow background activity" in app settings
3. Add app to device-specific "protected apps" list (Xiaomi, Huawei, etc.)

Messages Not Forwarding

1. Check if forwarding is enabled on Home screen
2. Verify Telegram configuration in Settings
3. Test connection using the "Test" button
4. Check if message was blocked by spam filter (History > Spam tab)

Notifications Not Showing

1. Ensure notification permission is granted
2. Check notification channels are enabled in Android settings
3. Verify notification settings in app Settings

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Ktor - HTTP client for Telegram API
• Jetpack Compose - Modern Android UI toolkit
• Room - SQLite abstraction layer
• DataStore - Preferences storage