Capacitor SMS Retriever

Android-only plugin for Capacitor 7 that retrieves SMS messages without requiring runtime permissions. Suitable for OTP (One-Time Password) use cases using the Google Play Services SMS Retriever API.

Installation

npm install @michaelkhabarov/capacitor-sms-retriever

Platform Support

• Android: Fully supported
• iOS: Not supported
• Web: Not supported

Usage

import { Capacitor } from '@capacitor/core'
import { CapacitorSmsRetriever } from "@michaelkhabarov/capacitor-sms-retriever";

if (Capacitor.getPlatform() === 'android') {
  // Start listening for SMS
  CapacitorSmsRetriever.startListening()
    .then((res) => console.log("SMS Content", res.body))
    .catch((err) => console.log("Failed", err));

  // Stop listening
  CapacitorSmsRetriever.stopListening();

  // Get signature
  CapacitorSmsRetriever.getAppSignature()
    .then((res) => { console.log("App signature", res.signature) });
}

API

startListening()

Starts listening for incoming SMS messages.

Returns: Promise<{ body: string }>

stopListening()

Stops listening for SMS messages.

getAppSignature()

This is a helper method to generate your message hash to be included in your SMS message. Without the correct hash, your app won't receive the message callback. This only needs to be generated once per app and stored.

Note: Do not use hash strings dynamically computed on the client in your verification messages.

Returns: Promise<{ signature: string }>

Requirements

• Capacitor 7.0.0 or higher
• Android SDK 23 (Android 6.0) or higher
• Android Gradle Plugin 8.7.2
• Google Play Services (play-services-auth-api-phone 18.1.0)

How It Works

This plugin uses the Google Play Services SMS Retriever API, which allows your app to automatically retrieve verification codes from SMS messages without requiring the READ_SMS permission. The SMS message must be formatted according to Google's requirements (max 140 bytes, contains a hash string identifying your app).

For more information, see the SMS Retriever API documentation.

Credits

This package is based on:

• https://github.com/skmd87/capacitor-sms-retriever
• https://www.npmjs.com/package/capacitor-sms-retriever#appsignature