Getting Started

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/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-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:

npm install @capgo/capacitor-android-sms-retriever
npx cap sync android

Quick start

Listen for the one-time SMS, extract the OTP, then start the retriever before the user requests a code.

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

const smsListener = await AndroidSmsRetriever.addListener('smsReceived', ({ message }) => {
  const code = message.match(/\b\d{4,8}\b/)?.[0];
  if (code) submitCode(code);
  // The SMS also ends with your 11-character app hash; validate it separately from the OTP.
});

await AndroidSmsRetriever.startWatch();

// When the flow completes:
await smsListener.remove();
await AndroidSmsRetriever.stopWatch();

Common pitfalls

• Hash: SMS templates must include the app retriever hash.
• Timeout: restart watch when users request a new code.
• Play services: required on device.

Import

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

Android Requirements

SMS Retriever requires Google Play services on the Android device. The plugin does not request READ_SMS or RECEIVE_SMS permissions.

Your verification SMS must include the app hash returned by getHashString(). Generate the hash for the signing key used to distribute the app. Debug, release, and Play App Signing builds can have different hashes.

Listen For A Verification SMS

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

const received = await AndroidSmsRetriever.addListener('smsReceived', ({ message }) => {
  const code = message.match(/\b\d{6}\b/)?.[0];
  console.log('Verification code:', code);
});

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

const errors = await AndroidSmsRetriever.addListener('smsRetrieverError', ({ message }) => {
  console.error('SMS Retriever error:', message);
});

await AndroidSmsRetriever.startWatch();

// Remove listeners when the verification flow is done.
await received.remove();
await timeout.remove();
await errors.remove();

Stop Watching

await AndroidSmsRetriever.stopWatch();

Get The App Hash

const { hash } = await AndroidSmsRetriever.getHashString();
console.log(hash);

Use this hash at the end of the verification SMS sent by your backend.

Request A Phone Number Hint

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

Android shows the native Phone Number Hint UI and returns the phone number selected by the user.

Example SMS

<#> 123456 is your verification code.
FA+9qCX9VSu

Replace the final line with the hash for your app signing key.

Keep going from Getting Started

If you are using Getting Started to plan native plugin work, connect it with Using @capgo/capacitor-android-sms-retriever for the native capability in Using @capgo/capacitor-android-sms-retriever, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.