capacitor-sms-inbox

A Capacitor plugin to read SMS inbox on Android devices.

Installation

1. Install the plugin:

npm i git+https://github.com/solimanware/capacitor-sms-reader.git

2. Sync your Capacitor project:

npx cap sync android

3. Add the following permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />

4. In your Capacitor config file (usually capacitor.config.json or capacitor.config.ts), add the following:

{
  "plugins": {
    "SMSInboxReader": {
      "android": {
        "name": "com.capacitor.sms.reader.SMSInboxReaderPlugin"
      }
    }
  }
}

5. Import and initialize the plugin in your TypeScript/JavaScript code:

import { Plugins } from '@capacitor/core';
import { SMSInboxReader } from 'capacitor-sms-reader';

// Use the plugin
const { SMSInboxReader } = Plugins;

// Check permissions
const permissionStatus = await SMSInboxReader.checkPermissions();
if (permissionStatus.sms !== 'granted') {
  await SMSInboxReader.requestPermissions();
}

// Now you can use other methods like getCount(), getSMSList(), etc.

Usage

After installation, you can use the plugin's methods to interact with the SMS inbox. Remember to always check and request permissions before accessing SMS data.

For detailed API documentation, see the API section below.

API

• getMessages(...)
• checkPermissions()
• requestPermissions()
• Interfaces
• Type Aliases

Plugin interface for reading messages from the device's inbox.

getMessages(...)

getMessages(filter: GetMessageFilterInput) => Promise<{ messages: MessageObject[]; }>

Retrieves messages based on the provided filter criteria.

| Param | Type | Description | | ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ | | filter | GetMessageFilterInput | - The filter criteria to apply when fetching messages. |

Returns: Promise<{ messages: MessageObject[]; }>

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Checks the current permission status for accessing messages.

Returns: Promise<PermissionStatus>

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Requests permissions to access messages on the device.

Returns: Promise<PermissionStatus>

Interfaces

MessageObject

Represents a message object with its properties.

| Prop | Type | Description | | ----------------- | --------------------------- | ----------------------------------------------------- | | id | string | Unique identifier of the message. | | date | number | Timestamp of the message in milliseconds since epoch. | | messageType | 'sms' | 'mms' | Type of the message, either 'sms' or 'mms'. | | sender | string | Phone number or address of the sender/recipient. | | body | string | Content of the message. |

GetMessageFilterInput

Input parameters for filtering messages.

| Prop | Type | Description | | --------------- | --------------------- | -------------------------------------------------------------- | | ids | string[] | Array of message IDs to filter by. | | body | string | Text to search for in the message body. | | sender | string | Phone number or address to filter by. | | minDate | number | Minimum date (in milliseconds since epoch) to filter messages. | | maxDate | number | Maximum date (in milliseconds since epoch) to filter messages. | | indexFrom | number | Starting index for pagination. | | indexTo | number | Ending index for pagination. | | limit | number | Maximum number of messages to return. |

PermissionStatus

Represents the permission status for accessing messages.

| Prop | Type | Description | | -------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | messages | PermissionState | The current permission state for accessing messages. |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'