npm package: @solimanware/capacitor-sms-reader
Description: A capacitor plugin to read SMS inbox
Author: Osama Soliman
Latest version: 5.0.3

# capacitor-sms-inbox

A Capacitor plugin to read SMS inbox on Android devices.

## Installation

1. Install the plugin:

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

2. Sync your Capacitor project:

```bash
npx cap sync android
```

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

```xml
<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:

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

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

```typescript
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](#api) below.

## API

<docgen-index>

* [`getMessages(...)`](#getmessages)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

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

### getMessages(...)

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

Retrieves messages based on the provided filter criteria.

| Param        | Type                                                                    | Description                                            |
| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| **`filter`** | <code><a href="#getmessagefilterinput">GetMessageFilterInput</a></code> | - The filter criteria to apply when fetching messages. |

**Returns:** <code>Promise&lt;{ messages: MessageObject[]; }&gt;</code>

--------------------


### checkPermissions()

```typescript
checkPermissions() => Promise<PermissionStatus>
```

Checks the current permission status for accessing messages.

**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>

--------------------


### requestPermissions()

```typescript
requestPermissions() => Promise<PermissionStatus>
```

Requests permissions to access messages on the device.

**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>

--------------------


### Interfaces


#### MessageObject

Represents a message object with its properties.

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


#### GetMessageFilterInput

Input parameters for filtering messages.

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


#### PermissionStatus

Represents the permission status for accessing messages.

| Prop           | Type                                                        | Description                                          |
| -------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
| **`messages`** | <code><a href="#permissionstate">PermissionState</a></code> | The current permission state for accessing messages. |


### Type Aliases


#### PermissionState

<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>

</docgen-api>