@capgo/capacitor-android-sms-retriever

Read one-time codes from SMS on Android without the SMS permission, using Google Play services SMS Retriever, and let users pick their phone number with Phone Number Hint. Smoother sign-in and verification flows.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-android-sms-retriever in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-android-sms-retriever to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• SMS Retriever: startWatch() waits for one verification SMS and emits smsReceived, with smsRetrieverTimeout and smsRetrieverError events.
• No SMS permission: Google Play services delivers the matching message, so you do not request READ_SMS.
• App hash: getHashString() returns the 11-character hash your server adds to the SMS.
• Phone Number Hint: getPhoneNumber() shows the system picker and returns the selected SIM number.
• Stop anytime: stopWatch() cancels the active watch.
• Platforms: Android. Android only. iOS and web are not supported.

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}.

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('smsRetrieverTimeout', ...)

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

Listen for the five-minute SMS Retriever timeout.

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}.

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.

StopWatchResult

Result returned when SMS Retriever watching stops.

GetHashStringResult

Result returned by {@link AndroidSmsRetrieverPlugin.getHashString}.

GetPhoneNumberResult

Result returned by {@link AndroidSmsRetrieverPlugin.getPhoneNumber}.

PluginListenerHandle

SmsReceivedEvent

SMS Retriever message event payload.

SmsRetrieverErrorEvent

SMS Retriever error event payload.

PluginVersionResult

Plugin version payload.

Type Aliases

SmsRetrieverStartStatus

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

'SMS_RETRIEVER_STARTED' | 'SMS_RETRIEVER_ALREADY_STARTED'