@capgo/capacitor-android-sms-retriever

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

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

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().

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);

• 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() => 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() => Promise<StopWatchResult>

Stop the active SMS Retriever watch, if any.

Returns: Promise<StopWatchResult>

Since: 8.0.0

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() => 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(eventName: 'smsReceived', listenerFunc: (event: SmsReceivedEvent) => void) => Promise<PluginListenerHandle>

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

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

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

Listen for the five-minute SMS Retriever timeout.

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

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

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

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin.

Since: 8.0.0

getPluginVersion() => Promise<PluginVersionResult>

Get the native Capacitor plugin version.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Result returned when SMS Retriever watching starts.

Result returned when SMS Retriever watching stops.

Result returned by {@link AndroidSmsRetrieverPlugin.getHashString}.

Result returned by {@link AndroidSmsRetrieverPlugin.getPhoneNumber}.

SMS Retriever message event payload.

SMS Retriever error event payload.

Plugin version payload.

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

'SMS_RETRIEVER_STARTED' | 'SMS_RETRIEVER_ALREADY_STARTED'