elizaos--eliza/plugins/plugin-native-messages/README.md

@elizaos/capacitor-messages

Android SMS/MMS bridge for elizaOS — a Capacitor plugin that lets an Eliza agent send outbound SMS messages and read the device SMS inbox via the Android Telephony API.

What it does

• Send SMS — dispatches single or multipart text messages using SmsManager, waits for radio-layer delivery confirmation, and writes the sent message to the Android sent folder.
• Read SMS — queries the system content://sms provider and returns messages sorted newest-first, with optional filtering by conversation thread.

The web/browser fallback reports messaging unavailable (sendSms throws; listMessages returns an empty list). This plugin is meaningful only on Android.

Installation

npm install @elizaos/capacitor-messages
npx cap sync android

Android permissions

Declare in your app's AndroidManifest.xml (already present in the plugin manifest, but the host app must request at runtime):

Permission	Required by
android.permission.SEND_SMS	sendSms
android.permission.READ_SMS	listMessages
android.permission.RECEIVE_SMS	Declared in plugin manifest
android.permission.RECEIVE_MMS	Declared in plugin manifest
android.permission.RECEIVE_WAP_PUSH	Declared in plugin manifest

Request the permissions your methods need before calling them. Calls made without the required permission are rejected immediately.

API

Messages.sendSms(options)

import { Messages } from "@elizaos/capacitor-messages";

const result = await Messages.sendSms({
  address: "+15550001234",  // E.164 or local format accepted by SmsManager
  body: "Hello from Eliza",
});
// result: { messageId: string, messageUri: string }

Long messages are automatically split into multipart SMS by SmsManager.divideMessage. The call resolves only after every part has been confirmed by the radio layer.

Messages.listMessages(options?)

const { messages } = await Messages.listMessages({
  limit: 50,       // 1–500, default 100
  threadId: "42",  // optional — filter to one conversation
});
// messages: SmsMessageSummary[]

Each SmsMessageSummary contains: id, threadId, address, body, date (Unix ms), type (Telephony.Sms constants), read.

Types

interface SendSmsOptions   { address: string; body: string }
interface SendSmsResult    { messageId: string; messageUri: string }
interface ListMessagesOptions { limit?: number; threadId?: string }
interface SmsMessageSummary {
  id: string; threadId: string; address: string;
  body: string; date: number; type: number; read: boolean;
}

Building from source

bun run --cwd plugins/plugin-native-messages build

Runs with bun; typescript (tsc) and rollup are dev dependencies.