react-native-background-sms

Send SMS in the background on Android — no user interaction required. On iOS, opens a pre-filled compose UI (Apple restriction).

Why?

Most React Native SMS libraries only open the device's SMS app, requiring the user to manually tap "Send". This library sends SMS automatically in the background on Android using the native SmsManager API. Perfect for safety apps, alert systems, and emergency notifiers.

| Feature | Android | iOS | |---------|---------|-----| | Sends without UI | Yes | No (Apple restriction) | | User interaction needed | None | Must tap Send | | Multiple recipients | One SMS per recipient | Single compose UI | | Long message support | Auto-split (multipart) | Handled by compose UI | | Delivery tracking | BroadcastReceiver | Delegate callback |

Installation

npm install react-native-background-sms

iOS

cd ios && pod install

Android

Add the SMS permission to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.SEND_SMS" />

You must request this permission at runtime before calling sendSms(). Use a library like react-native-permissions or Android's built-in permission API.

API

canSendSms()

Check if the device can send SMS.

import { canSendSms } from 'react-native-background-sms';

const { available, reason } = await canSendSms();

if (!available) {
  console.log('Cannot send SMS:', reason);
}

Returns: Promise<CanSendSmsResult>

interface CanSendSmsResult {
  available: boolean;
  reason?: string;  // Only present when available is false
}

sendSms(options)

Send SMS to one or more recipients.

import { sendSms } from 'react-native-background-sms';

const result = await sendSms({
  phoneNumbers: ['+1234567890'],
  message: 'Hello from react-native-background-sms!',
});

if (result.status === 'sent') {
  console.log('SMS sent successfully');
} else if (result.status === 'failed') {
  console.log('SMS failed:', result.error);
} else if (result.status === 'cancelled') {
  // iOS only — user dismissed the compose UI
  console.log('User cancelled');
} else if (result.status === 'unavailable') {
  console.log('SMS not available:', result.reason);
}

Returns: Promise<SendSmsResult>

interface SendSmsOptions {
  phoneNumbers: string[];  // E.164 format recommended (e.g., '+1234567890')
  message: string;
}

interface SendSmsResult {
  status: 'sent' | 'failed' | 'cancelled' | 'unavailable';
  error?: string;   // Present when status is 'failed'
  reason?: string;  // Present when status is 'unavailable'
}

Platform Behavior

Android

• SMS is sent silently in the background using Android's SmsManager API
• Each recipient receives an individual SMS
• Long messages (>160 chars) are automatically split into multipart SMS
• A BroadcastReceiver tracks delivery with a 30-second timeout
• If sending to multiple recipients and one fails, sending stops — already-sent messages are not rolled back
• Requires SEND_SMS runtime permission

iOS

• Opens the native MFMessageComposeViewController with pre-filled recipients and message
• The user must tap Send — Apple does not allow programmatic SMS sending
• All recipients appear in a single compose view
• If the app is in the background when sendSms is called, the compose UI appears when the app returns to foreground

Error Codes

| Code | Platform | Meaning | |------|----------|---------| | SMS_UNAVAILABLE | Both | Device cannot send SMS (no telephony hardware) | | SMS_NO_SERVICE | Android | No cellular service | | SMS_RADIO_OFF | Android | Airplane mode or radio off | | SMS_TIMEOUT | Android | No delivery confirmation within 30 seconds | | SMS_FAILED | Both | General send failure | | SMS_ERROR | Both | Unexpected error |

Requirements

• React Native >= 0.70
• Android minSdk 24 (Android 7.0)
• iOS 13.0+

License

MIT