Skip to content
This repository has been archived by the owner on Nov 16, 2023. It is now read-only.


Folders and files

Last commit message
Last commit date

Latest commit



22 Commits

Repository files navigation

npm npm GitHub package.json version GitHub code size in bytes GitHub top language GitHub GitHub last commit


Cordova plugin to get received SMS contents in Android platform.


Add the plugin from NPM:

cordova plugin add cordova-plugin-sms-receive



Start listening for incoming SMS messages. This will request SMS permission to the user if not yet granted.

⚠️ Method moved from window to cordova.plugins object in version 2.0.0


  • Both success and error callbacks will react to SMS arrival events as well.
  • Android 5.1 grants permission by default because the individual permission request dialog was added in Android 6.

Success callback return values

  • SMS_RECEIVED: Second callback, triggered when a SMS was received.

Error callback return values

  • PERMISSION_DENIED: User declined the permission request.
  • SMS_EQUALS_NULL: Triggered after watching started OK but plugin failed to read the received SMS.
  • Any other error string for failed SMS retrieval whenever an SMS is received.


cordova.plugins.SMSReceive.startWatch(function(strSuccess) {
}, function(strError) {


Stops listening for incoming SMS. Always invoke this method after you have received the required SMS to prevent memory leaks.

⚠️ Method moved from window to cordova.plugins object in version 2.0.0

Success callback return values



cordova.plugins.SMSReceive.stopWatch(function(strSuccess) {
}, function(strError) {



Triggered when a new SMS has arrived. You need call startWatch first.

⚠️ JSON SMS payload moved from to message object in version 2.0.0


  • Success in reading incoming SMS will trigger the startWatch success callback.
  • Failure in reading incoming SMS will trigger the startWatch error callback.

Return values

JSON object with these properties:

  • address: Mobile number from sender
  • body: SMS message body limited to 154 chars.
  • date: SMS received timestamp.


document.addEventListener('onSMSArrive', function(message) {
	console.log('address:' + message.address);
	console.log('body:' + message.body);
	console.log('date' +

Plugin demo app

You can download the compiled SMS Receive plugin demo app and inspect the source code in my plugin demos repository.



Can the SMS be intercepted and deleted?

This plugin does not send SMS nor intercept incoming SMS: the intercepting feature has been removed in Android 5 or earlier for security concerns, so no plugin can do this anymore.

Does the plugin still work with the app minimized?

When the app is sent to the background, as long as Android has not unloaded it to recover memory, SMS watching will remain active and working correctly.

Android Permissions Request

The startWatch method will cause the Android 6.0 and higher permission dialog to show up with this message:

Allow [AppName] to send and view SMS messages?

This message is not exactly accurate, because the plugin only requests permission for receiving SMS as follows:

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

How this plugin has been tested?

This plugin has been successfully tested in devices and emulators ranging from Android 5.1 to Android 10.


If you find any bugs or want to improve the plugin, kindle subtmit a PR and it will be merged as soon as possible.

Even if you don't quite understand Java, you can investigate and locate issues with the plugin code by opening the file and browsing StackOverflow or the Android APIs documentation with the proper keywords.



  • ⚠️ Methods moved from the global window to the cordova.plugins object.
  • ⚠️ onSMSArrive no longer returns result in the object, use message directly
  • Fixed SMS message body, now returns the entire message without 154 chars limit.
  • Fixed error when trying to start SMS watching when already active.
  • Changed the onSMSArrive invoking method internally to use native PluginResult callback.
  • Removed the SMS service center number from the JSON payload.
  • Improved all methods return values to make them easier to parse.
  • Improved error handling.
  • Updated demo app, now available as pre-compiled APK.