@capgo/capacitor-android-sms-retriever

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

Install

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'