@capgo/capacitor-android-sms-retriever

@capgo/capacitor-android-sms-retriever

Get instant updates for your app with Capgo

Missing a feature? We can build the plugin for you

Android-only Capacitor plugin for Google Play services SMS Retriever and Phone Number Hint APIs.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-android-sms-retriever` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-android-sms-retriever
bunx cap sync android

Android

This plugin does not request SMS permissions. SMS retrieval uses Google Play services and waits for one matching verification SMS for up to five minutes.

The verification SMS must include the app hash returned by getHashString().

Usage

import { AndroidSmsRetriever } from '@capgo/capacitor-android-sms-retriever';

const { hash } = await AndroidSmsRetriever.getHashString();
console.log('SMS hash:', hash);

const received = await AndroidSmsRetriever.addListener('smsReceived', ({ message }) => {
  console.log('Verification SMS:', message);
});

await AndroidSmsRetriever.addListener('smsRetrieverTimeout', () => {
  console.log('SMS Retriever timed out');
});

await AndroidSmsRetriever.startWatch();

// Later, if needed:
await AndroidSmsRetriever.stopWatch();
await received.remove();

const { phoneNumber } = await AndroidSmsRetriever.getPhoneNumber();
console.log(phoneNumber);

API

• startWatch()
• stopWatch()
• getHashString()
• getPhoneNumber()
• addListener('smsReceived', ...)
• addListener('smsRetrieverTimeout', ...)
• addListener('smsRetrieverError', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

Android-only Capacitor plugin for Google Play services SMS Retriever and Phone Number Hint APIs.

startWatch()

startWatch() => Promise<StartWatchResult>

Start listening for one verification SMS through Android's SMS Retriever API.

Android stops listening automatically when a matching message arrives or after the five-minute SMS Retriever timeout. No SMS permissions are required.

Returns: Promise<StartWatchResult>

Since: 8.0.0

stopWatch()

stopWatch() => Promise<StopWatchResult>

Stop the active SMS Retriever watch, if any.

Returns: Promise<StopWatchResult>

Since: 8.0.0

getHashString()

getHashString() => Promise<GetHashStringResult>

Get the 11-character app hash for the installed app signature.

Generate this once for the signing key used to distribute the app and append it to verification SMS messages.

Returns: Promise<GetHashStringResult>

Since: 8.0.0

getPhoneNumber()

getPhoneNumber() => Promise<GetPhoneNumberResult>

Show Android's Phone Number Hint UI and return the user-selected SIM-based phone number.

Returns: Promise<GetPhoneNumberResult>

Since: 8.0.0

addListener('smsReceived', ...)

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

Listen for a verification SMS received after {@link startWatch}.

Param	Type
eventName	'smsReceived'
listenerFunc	(event: SmsReceivedEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('smsRetrieverTimeout', ...)

addListener(eventName: 'smsRetrieverTimeout', listenerFunc: () => void) => Promise<PluginListenerHandle>

Listen for the five-minute SMS Retriever timeout.

Param	Type
eventName	'smsRetrieverTimeout'
listenerFunc	() => void

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('smsRetrieverError', ...)

addListener(eventName: 'smsRetrieverError', listenerFunc: (event: SmsRetrieverErrorEvent) => void) => Promise<PluginListenerHandle>

Listen for SMS Retriever runtime errors after {@link startWatch}.

Param	Type
eventName	'smsRetrieverError'
listenerFunc	(event: SmsRetrieverErrorEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin.

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Get the native Capacitor plugin version.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Interfaces

StartWatchResult

Result returned when SMS Retriever watching starts.

Prop	Type	Description	Since
status	SmsRetrieverStartStatus	Native status returned by Android.	8.0.0

StopWatchResult

Result returned when SMS Retriever watching stops.

Prop	Type	Description	Since
status	'SMS_RETRIEVER_DONE'	Native status returned by Android.	8.0.0

GetHashStringResult

Result returned by {@link AndroidSmsRetrieverPlugin.getHashString}.

Prop	Type	Description	Since
hash	string	The 11-character app hash that must be appended to verification SMS messages.	8.0.0

GetPhoneNumberResult

Result returned by {@link AndroidSmsRetrieverPlugin.getPhoneNumber}.

Prop	Type	Description	Since
phoneNumber	string	Phone number selected by the user from Android's Phone Number Hint UI.	8.0.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

SmsReceivedEvent

SMS Retriever message event payload.

Prop	Type	Description	Since
message	string	Full verification SMS message received by Android's SMS Retriever API.	8.0.0

SmsRetrieverErrorEvent

SMS Retriever error event payload.

Prop	Type	Description	Since
message	string	Error message returned by Android or Google Play services.	8.0.0

PluginVersionResult

Plugin version payload.

Prop	Type	Description	Since
version	string	Version identifier returned by the platform implementation.	8.0.0

Type Aliases

SmsRetrieverStartStatus

Status values returned by {@link AndroidSmsRetrieverPlugin.startWatch}.

'SMS_RETRIEVER_STARTED' | 'SMS_RETRIEVER_ALREADY_STARTED'