@capgo/capacitor-android-sms-retriever
June 16, 2026 ยท View on GitHub
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
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'