react-native-sms-gateway

react-native-sms-gateway

Need to listen/forward incoming SMS to your server or even a Telegram chat, even if your app is completely closed or the phone is restarted? This package is designed to do just that. It can send SMS to a local or external service/third-party API or to a Telegram chat via bot token. It covers most SMS use cases, such as receiving urgent messages (like OTPs) when you are not home, or forwarding SMS to external tools.

⚠️ CAUTION: This package only works on Android. There is no public SMS API for iOS, so iOS is not supported due to platform restrictions (Apple does not provide public APIs for SMS access) and cannot receive or forward SMS using this library.

Features

• Background SMS Listener: Receives SMS even when the app is closed or after device reboot (Android only).
• Forward SMS to HTTP Server: Forwards SMS to one or more HTTP endpoints with optional custom headers.
• Forward SMS to Telegram: Forwards SMS to Telegram chats, groups, or channels using a bot.
• Flexible Filtering: Filter SMS by sender or message keywords (case-insensitive, partial match).
• Configurable Delivery: Choose to deliver via HTTP, Telegram, or both.
• React Native Event Emitter: Optionally receive SMS events in your JS app for custom handling.
• Persistent Configuration: All settings are stored in Android SharedPreferences.
• Boot Persistence: Listens after device reboot (requires permission).

Table of Contents

• react-native-sms-gateway
  • Features
  • Table of Contents
  • Installation
  • Platform Support
  • Android Setup
  • How it works
  • Usage
    • Basic Setup
    • Listen for SMS in JS
    • Get All Settings
  • HTTP Forwarding Details
    • Example: Node.js HTTP Receiver
  • Telegram Setup (Quick Start)
    • Telegram Message Template
  • Filtering
  • Tips & Issues
  • Future Features
  • Contributing
  • License
  • API Reference
    • enableSmsListener(enabled)
    • setHttpConfigs(configs)
    • setTelegramConfig(botToken, chatIds)
    • setSendersFilterList(list)
    • setMsgKeywordsFilterList(list)
    • setDeliveryType(type)
    • addEventListener(eventHandler)
    • getAllSettings()
    • getHttpConfigs()
    • setTelegramBotToken(bot_token)
    • setTelegramChatIds(chat_ids)
    • getTelegramBotToken()
    • getTelegramChatIds()
    • getTelegramParseMode()
    • getDeliveryType()
    • isSmsListenerEnabled()
    • getUserPhoneNumber()
    • setUserPhoneNumber(phoneNumber)
    • getSendersFilterList()
    • getMsgKeywordsFilterList()
    • getEventListenersCount()
    • removeAllSMSEventListeners()

Installation

npm install react-native-sms-gateway
# or
yarn add react-native-sms-gateway

Platform Support

• Android: Fully supported.
• iOS: Not supported (Apple does not provide public APIs for SMS access).

Android Setup

You must manually add the following permissions and receivers to your app's AndroidManifest.xml for the package to work correctly.

Add these permissions at the top of your manifest (inside <manifest> like next):

<manifest ...>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.READ_SMS" />
  <uses-permission android:name="android.permission.RECEIVE_SMS" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />
  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
  ...
</manifest>

Add these receivers inside your <application> tag: like next

 <application ....>
    ......
    <!-- SMS Receiver: required for receiving SMS in background -->
    <receiver 
      android:name="com.smsgateway.SmsGatewayReceiver"
      android:enabled="true" 
      android:exported="true"
      android:permission="android.permission.BROADCAST_SMS">
      <intent-filter android:priority="999">
        <action android:name="android.provider.Telephony.SMS_RECEIVED" />
      </intent-filter>
    </receiver>

    <!-- Boot Receiver: required for listening after device reboot -->
    <receiver 
      android:name="com.smsgateway.SmsGatewayBootReceiver" 
      android:enabled="true"
      android:exported="false">
      <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
      </intent-filter>
    </receiver>
    ....
  </application>

Note:

• These entries are required for the package to receive SMS in the background and after device reboot.
• You must also request SMS permissions at runtime

How it works

• Native Side (Android/Kotlin):

  • SmsReceiver listens for incoming SMS and applies sender/message filters.
  • If a match is found, it builds a payload and dispatches it to:
    • HTTP endpoints via HttpHelper
    • Telegram via TelegramHelper
    • JS event emitter (if enabled)
  • All configuration is managed via ConfigProvider and SmsNativeModule.

• JS Side (React Native):

  • Use the SmsGateway class to configure, enable/disable, and listen for SMS events.
  • All settings are persisted natively and survive app restarts.

Usage

Basic Setup

import { SmsGateway } from "react-native-sms-gateway";

// Enable SMS listener (required)
SmsGateway.enableSmsListener(true);

// Set HTTP endpoints (optional)
SmsGateway.setHttpConfigs([
  { url: "https://your-server.com/sms", headers: { Authorization: "Bearer TOKEN" } }
]);

// Set Telegram config (optional)
SmsGateway.setTelegramConfig(
  "YOUR_TELEGRAM_BOT_TOKEN",
  ["123456789", "-100987654321"] // chat IDs (user, group, or channel)
);

// Set delivery type: "http", "telegram", or "all"
SmsGateway.setDeliveryType("all");

// Set sender filter (optional)
SmsGateway.setSendersFilterList(["Vodafone", "010"]);

// Set message keyword filter (optional)
SmsGateway.setMsgKeywordsFilterList(["OTP", "gift"]);

// Set user phone number (optional, for forwarding)
SmsGateway.setUserPhoneNumber("[phone]");

Listen for SMS in JS

const subscription = SmsGateway.addEventListener((data) => {
  // data: { msg, timestamp, phoneNumber, sender }
  console.log("Received SMS:", data);
});

// Remove listener when done
subscription.remove();

Get All Settings

const settings = await SmsGateway.getAllSettings();
console.log(settings);

HTTP Forwarding Details

When an SMS is received and forwarded to your HTTP endpoint, the package sends a POST request with the following JSON body:

{
  "msg": "Message content",
  "timestamp": 1717430000000,
  "phoneNumber": "[phone]",
  "sender": "Vodafone"
}

• HTTP Method: POST
• Content-Type: application/json
• Headers: Any custom headers you set via setHttpConfigs.

Example: Node.js HTTP Receiver

Here’s a minimal Node.js server to receive and log incoming SMS webhooks:

// example/http-receiver.js
const express = require('express');
const app = express();
app.use(express.json());

app.post('/sms', (req, res) => {
  console.log('Received SMS:', req.body);
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Listening on port 3000'));

• Start with: node http-receiver.js
• Set your endpoint in the package config:

  SmsGateway.setHttpConfigs([
    { url: "http://your-server-ip:3000/sms", headers: {} }
  ]);
  

Telegram Setup (Quick Start)

• Create a Telegram Bot:

  • Open @BotFather in Telegram.
  • Send /newbot to create a bot and get the bot token.
  • Enter bot name like your_bot then you will get the bot token copy and save it we will use it later.
  • Next stay at @BotFather and use /setcommands to set command to help get the chat id after enter /setcommands you will get message like Choose a bot to change the list of commands. so enter your bot name like in example above @your_bot.
  • Next you will prompted to enter commands enter the following command get_chat_id - display current chat id so it will be used later to get chat it now you are ready

• Handle Send Chat Id Via get_chat_id Command

• By default telegram provide 2 ways to receive message via webhook and long polling if you plan to deploy you bot to free server like vercel you can use webhook check the docs to understand how to use it. It's easy to do it then you can use the next examples to get started check telegram docs for get updates

• Long polling (recommended for test)

  • the easiest way to get chat id specially when you are testing the pkg is long polling

• Start a chat with your bot (search for your bot username in Telegram and press "Start").

• Send the command /get_chat_id to your bot.

• If you use a simple bot script (see below), it will reply with your chat ID. install node-telegram-bot-api then try next

Sample Node.js Bot for Testing:

// Save as get_chat_id_bot.js and run: node get_chat_id_bot.js
const TelegramBot = require('node-telegram-bot-api');
const TOKEN = 'YOUR_BOT_TOKEN_HERE';
const bot = new TelegramBot(TOKEN, { polling: true });

bot.onText(/\/get_chat_id/, (msg) => {
 const user_id = msg.from.id;
 const sender_username = msg.from.username;
 const chat_id = msg.chat.id;  
 bot.sendMessage(
   chat_id,
   `Your id is: \`${user_id}\`\nUsername is: \`${sender_username}\`\nCurrent chat id is: \`${chat_id}\``,
   {
     parse_mode: "Markdown",
   }
 );
}); 
console.log('waiting for "get_chat_id" command ...');

• Nodejs (recommended for production)

  • Set webhook url create any js file copy next code and update to add bot token, webhook url then run it to set webhook url

  ⚠️ CAUTION: since you set webhook url you couldn't use long polling

  const BOT_TOKEN = '123456789:ABCDEF_your_bot_token_here';
  const WEBHOOK_URL = 'https://your-domain.com/your-webhook-path';
  
  const TELEGRAM_API_URL = `https://api.telegram.org/bot${BOT_TOKEN}/setWebhook`;
  fetch(TELEGRAM_API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: WEBHOOK_URL })
  })
  .then(res => res.json())
  .then(console.log)
  .catch(console.error)
  

  • node app example to send chat id via webhook first install yarn add node-telegram-bot-api then try next code

  import TelegramBot from 'node-telegram-bot-api';
  import cors from 'cors';
  import express from 'express';
  
  const app = express();
  const TELEGRAM_BOT_TOKEN = 'TELEGRAM_BOT_TOKEN'; /** your telegram bot token */
  const bot = new TelegramBot(TELEGRAM_BOT_TOKEN);
  
  app.use(cors({ origin: true, credentials: true, preflightContinue: true }));
  app.use(express.json({ limit: '50mb' }));
  app.use(express.urlencoded({ extended: false }));
  
  const telegramWebhooksController = async (req: express.Request, res: express.Response) => {
    const { message } = req.body;
    const chatId = message.chat?.id;
    // console.log('Received update:', chatId, JSON.stringify(message, null, 2));
  
    if (chatId) {
      let responseMsg = '';
  
      switch (message.text) {
        case '/get_chat_id':
          responseMsg = `Chat Id is: \`${chatId}\``;
          break;
        default:
          responseMsg = `You said: ${message.text}`;
          break;
      }
  
  
      await bot.sendMessage(chatId, responseMsg);
    }
  
    res.sendStatus(200);
  };
  
  app.post('/telegram/webhooks', telegramWebhooksController);
  app.listen(3000, () => console.log('Server ready on port 3000.'));
  

• Get Your Chat ID:

  • Start a chat with your bot or add it to a group/channel anyway the easiest way to get started is to navigate into your bot by name so in telegram search enter @your_bot then after open bot chat press start then /get_chat_id it will show you the message from above.

• Configure in JS:

  SmsGateway.setTelegramConfig("YOUR_BOT_TOKEN", ["YOUR_CHAT_ID"]);
  

Note:

• For groups/channels, add your bot as an admin and use the group/channel ID.
• The package uses HTML parse mode for Telegram messages.

Telegram Message Template

• Currently the telegram HTML template is const and couldn't be modified at the current time in future update may i provide a way to customize it but for now it looks like next

<b>Date</b>: <code>{{date}}</code>
<b>From:</b> <u><code>{{sender}}</code></u>
<b>TO:</b> <u><code>{{phoneNumber}}</code></u>
<b>Message:</b> 
<pre>{{msg}}</pre>

Filtering

• Sender Filter: Only SMS from senders containing any of the specified strings (case-insensitive) will be forwarded.
• Message Keyword Filter: Only SMS containing any of the specified keywords (case-insensitive) will be forwarded.
• If both filters are empty, all SMS are forwarded. If both are set, a message is forwarded if it matches either filter.

Tips & Issues

• Permissions: You must request SMS permissions at runtime on Android 6.0+.
• Background/Boot: The module works in the background and after reboot, but some OEMs may restrict background receivers.
• Telegram: Your bot must be an admin in groups/channels to send messages.
• HTTP: You can set multiple endpoints and custom headers for each.
• JS Listener: Works only when the app is running; use HTTP/Telegram for background delivery.

Future Features

• Custom notification support
• More flexible message templates
  • Allow users to define custom Telegram message templates
• SMS Backup / Logging
  • Optional local database or file log for all received messages
  • Useful for debugging or offline sync
• Webhook verification and retry logic
  • Retry sending if HTTP request or Telegram fails
  • Optionally queue messages until internet is available
• Rate Limiting / Throttling
  • Prevent sending too many requests per second (e.g., for spam protection)
• Use DataStore instead of SharedPreferences
  • Migrate to Jetpack DataStore for improved reliability and performance

Contributing

Contributions are welcome! Please open issues or pull requests for bugs, features, or documentation improvements.

License

MIT

API Reference

Below are all available methods, their parameters, and usage examples.

enableSmsListener(enabled)

Enable or disable the SMS listener (background service).

Parameter	Type	Required	Description
enabled	boolean	Yes	Enable (true) or disable (false) the SMS listener

Example:

SmsGateway.enableSmsListener(true); // Enable
SmsGateway.enableSmsListener(false); // Disable

setHttpConfigs(configs)

Set HTTP endpoints and optional headers for forwarding SMS.

Parameter	Type	Required	Description
configs	Array<{ url: string, headers?: object }>	Yes	List of HTTP endpoints and optional headers

Example:

SmsGateway.setHttpConfigs([
  { url: "https://your-server.com/sms", headers: { Authorization: "Bearer TOKEN" } }
]);

setTelegramConfig(botToken, chatIds)

Set Telegram bot token and chat IDs at once.

Parameter	Type	Required	Description
botToken	string	Yes	Telegram bot token
chatIds	string[]	Yes	Array of chat IDs (user, group, or channel)

Example:

SmsGateway.setTelegramConfig("YOUR_BOT_TOKEN", ["YOUR_CHAT_ID"]);

setSendersFilterList(list)

Set sender filter list (array of strings).

Parameter	Type	Required	Description
list	string[]	Yes	List of sender names/numbers to filter

Example:

SmsGateway.setSendersFilterList(["Vodafone", "010"]);

setMsgKeywordsFilterList(list)

Set message keywords filter list (array of strings).

Parameter	Type	Required	Description
list	string[]	Yes	List of keywords to filter messages

Example:

SmsGateway.setMsgKeywordsFilterList(["OTP", "gift"]);

setDeliveryType(type)

Set delivery type: 'http', 'telegram', or 'all'.

Parameter	Type	Required	Description
type	string	Yes	'http', 'telegram', or 'all'

Example:

SmsGateway.setDeliveryType("all");

addEventListener(eventHandler)

Add a JS event listener for incoming SMS (works only when app is running).

Parameter	Type	Required	Description
eventHandler	function	Yes	Callback function to handle SMS events

Example:

const subscription = SmsGateway.addEventListener((data) => {
  // data: { msg, timestamp, phoneNumber, sender }
  console.log("Received SMS:", data);
});
// Remove listener when done
subscription.remove();

getAllSettings()

Get all current settings as an object.

Parameter	Type	Required	Description
(none)

Example:

const settings = await SmsGateway.getAllSettings();
console.log(settings);

getHttpConfigs()

Get the current HTTP configuration.

const configs = await SmsGateway.getHttpConfigs();

setTelegramBotToken(bot_token)

Set only the Telegram bot token.

SmsGateway.setTelegramBotToken("YOUR_BOT_TOKEN");

setTelegramChatIds(chat_ids)

Set only the Telegram chat IDs.

SmsGateway.setTelegramChatIds(["123456789", "-100987654321"]);

getTelegramBotToken()

Get the current Telegram bot token.

const token = await SmsGateway.getTelegramBotToken();

getTelegramChatIds()

Get the current Telegram chat IDs.

const chatIds = await SmsGateway.getTelegramChatIds();

getTelegramParseMode()

Get the Telegram parse mode (currently always 'HTML').

const mode = await SmsGateway.getTelegramParseMode();

getDeliveryType()

Get the current delivery type.

const type = await SmsGateway.getDeliveryType();

isSmsListenerEnabled()

Check if the SMS listener is enabled. It's not checking if you are set an SMS listener into you app but it checks if the SMS listen service running in background it helpful to indicate whether you are enabled / disabled the service via enableSmsListener(enabled)

const enabled = await SmsGateway.isSmsListenerEnabled();

getUserPhoneNumber()

Get the saved user phone number.

const phone = await SmsGateway.getUserPhoneNumber();

setUserPhoneNumber(phoneNumber)

Set the user phone number for forwarding.

SmsGateway.setUserPhoneNumber("[phone]");

getSendersFilterList()

Get the current sender filter list.

const senders = await SmsGateway.getSendersFilterList();

getMsgKeywordsFilterList()

Get the current message keywords filter list.

const keywords = await SmsGateway.getMsgKeywordsFilterList();

getEventListenersCount()

Get the number of SMS event listeners currently added.

const count = await SmsGateway.getEventListenersCount();

removeAllSMSEventListeners()

Remove all SMS event listeners.

SmsGateway.removeAllSMSEventListeners();