sms-read-plugin-android

A plugin used to read sms for android apps

Install

To use npm

npm install sms-read-plugin-android

To use yarn

yarn add sms-read-plugin-android

Sync native files

npx cap sync

API

• startListening(...)
• stopListening()
• addListener('smsReceived', ...)
• addListener('smsError', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

startListening(...)

startListening(options?: StartListeningOptions | undefined) => Promise<SmsReceivedResult>

Start the SMS User Consent flow.

Registers with Google Play Services (SmsRetrieverClient.startSmsUserConsent) and waits for a single incoming SMS. When a matching message arrives the system shows a one-tap consent dialog; if the user allows it, the promise resolves with the full message body and (best-effort) the extracted OTP.

This is a one-shot operation: it resolves/rejects exactly once and then stops listening. Call it again to listen for the next message. Internally it times out after ~5 minutes (enforced by Play Services).

Requires NO SMS permissions and NO app hash.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | StartListeningOptions |

Returns: Promise<SmsReceivedResult>

stopListening()

stopListening() => Promise<void>

Stop an in-progress startListening call early.

Unregisters the broadcast receiver and rejects any pending startListening promise with code CANCELLED.

addListener('smsReceived', ...)

addListener(eventName: 'smsReceived', listenerFunc: (event: SmsReceivedResult) => void) => Promise<PluginListenerHandle>

Listen for a received SMS. Fires in addition to the startListening promise resolving, for consumers that prefer an event-based API.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------- | | eventName | 'smsReceived' | | listenerFunc | (event: SmsReceivedResult) => void |

Returns: Promise<PluginListenerHandle>

addListener('smsError', ...)

addListener(eventName: 'smsError', listenerFunc: (event: SmsErrorEvent) => void) => Promise<PluginListenerHandle>

Listen for errors during the consent flow (timeout, denied consent, etc.).

| Param | Type | | ------------------ | --------------------------------------------------------------------------- | | eventName | 'smsError' | | listenerFunc | (event: SmsErrorEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin.

Interfaces

SmsReceivedResult

| Prop | Type | Description | | ------------- | ------------------- | ---------------------------------------------------------------------- | | message | string | The full text of the SMS the user consented to share. | | otp | string | The OTP extracted from message using otpPattern, if one was found. |

StartListeningOptions

| Prop | Type | Description | | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | senderPhoneNumber | string | If set, only messages originating from this phone number trigger the consent prompt. Leave undefined to accept a message from any sender. | | otpPattern | string | Custom regular expression (as a string) used to extract the OTP from the message body. The first capturing group is preferred; otherwise the whole match is used. Defaults to \d{4,8} (a 4–8 digit run). |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

SmsErrorEvent

| Prop | Type | Description | | ------------- | ----------------------------------------------------- | ---------------------------------------------- | | code | SmsErrorCode | Stable machine-readable error code. | | message | string | Human-readable description of what went wrong. |

Type Aliases

SmsErrorCode

'TIMEOUT' | 'CONSENT_DENIED' | 'NO_MESSAGE' | 'CANCELLED' | 'API_ERROR'