react-native-sms-gateway
Advanced tools
React Native Android SMS gateway: listen, receive, forward, and send SMS to server, Telegram, or your app. Background SMS listener, HTTP/Telegram forwarding, SMS filter, event emitter, OTP, Android-only.
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.
npm install react-native-sms-gateway
# or
yarn add react-native-sms-gateway
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:
Native Side (Android/Kotlin):
SmsReceiver listens for incoming SMS and applies sender/message filters.HttpHelperTelegramHelperConfigProvider and SmsNativeModule.JS Side (React Native):
SmsGateway class to configure, enable/disable, and listen for SMS events.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("+201234567890");
const subscription = SmsGateway.addEventListener((data) => {
// data: { msg, timestamp, phoneNumber, sender }
console.log("Received SMS:", data);
});
// Remove listener when done
subscription.remove();
const settings = await SmsGateway.getAllSettings();
console.log(settings);
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": "+201234567890",
"sender": "Vodafone"
}
POSTapplication/jsonsetHttpConfigs.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'));
node http-receiver.jsSmsGateway.setHttpConfigs([
{ url: "http://your-server-ip:3000/sms", headers: {} }
]);
Create a Telegram Bot:
/newbot to create a bot and get the bot token.your_bot then you will get the bot token copy and save it we will use it later./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.get_chat_id - display current chat id so it will be used later to get chat it now you are readyHandle 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)
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)
⚠️ 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)
yarn add node-telegram-bot-api then try next codeimport 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:
@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:
<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>
Contributions are welcome! Please open issues or pull requests for bugs, features, or documentation improvements.
MIT
Below are all available methods, their parameters, and usage examples.
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
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" } }
]);
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"]);
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"]);
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"]);
Set delivery type: 'http', 'telegram', or 'all'.
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | 'http', 'telegram', or 'all' |
Example:
SmsGateway.setDeliveryType("all");
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();
Get all current settings as an object.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) |
Example:
const settings = await SmsGateway.getAllSettings();
console.log(settings);
Get the current HTTP configuration.
const configs = await SmsGateway.getHttpConfigs();
Set only the Telegram bot token.
SmsGateway.setTelegramBotToken("YOUR_BOT_TOKEN");
Set only the Telegram chat IDs.
SmsGateway.setTelegramChatIds(["123456789", "-100987654321"]);
Get the current Telegram bot token.
const token = await SmsGateway.getTelegramBotToken();
Get the current Telegram chat IDs.
const chatIds = await SmsGateway.getTelegramChatIds();
Get the Telegram parse mode (currently always 'HTML').
const mode = await SmsGateway.getTelegramParseMode();
Get the current delivery type.
const type = await SmsGateway.getDeliveryType();
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();
Get the saved user phone number.
const phone = await SmsGateway.getUserPhoneNumber();
Set the user phone number for forwarding.
SmsGateway.setUserPhoneNumber("+201234567890");
Get the current sender filter list.
const senders = await SmsGateway.getSendersFilterList();
Get the current message keywords filter list.
const keywords = await SmsGateway.getMsgKeywordsFilterList();
Get the number of SMS event listeners currently added.
const count = await SmsGateway.getEventListenersCount();
Remove all SMS event listeners.
SmsGateway.removeAllSMSEventListeners();
FAQs
React Native Android SMS gateway: listen, receive, forward, and send SMS to server, Telegram, or your app. Background SMS listener, HTTP/Telegram forwarding, SMS filter, event emitter, OTP, Android-only.
The npm package react-native-sms-gateway receives a total of 54 weekly downloads. As such, react-native-sms-gateway popularity was classified as not popular.
We found that react-native-sms-gateway demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
MCP spec updated with structured tool output, stronger OAuth 2.1 security, resource indicators, and protocol cleanups for safer, more reliable AI workflows.
Security News
More than half of CISOs now manage 10+ security areas, often with few legal safeguards and short tenures, yet continue to secure budgets and higher pay.
Security News
Libxml2’s solo maintainer drops embargoed security fixes, highlighting the burden on unpaid volunteers who keep critical open source software secure.