cap-sms-transceiver

Android SMS send with delivery reports and real-time receive for Capacitor apps.

Built for offline-first apps that use SMS as a data transport (e.g. syncing field data to a shortcode): the plugin gives you sent/delivered confirmation per message part and fires an event the moment a reply lands — no inbox polling.

| Platform | Supported | | -------- | --------- | | Android | ✅ | | iOS | ❌ (iOS does not allow programmatic SMS) | | Web | stub (permissions report denied, send() rejects) |

Install

npm install git+https://github.com/ShekuMunu/sms-transceiver.git
npx cap sync android

That's the whole integration:

• The plugin auto-registers — no MainActivity changes.
• The SEND_SMS / RECEIVE_SMS / READ_SMS permissions ship in the plugin's own manifest and are merged into your app at build time — no app-manifest changes.
• Runtime permission prompts are handled by send() / requestPermissions().

Requires Capacitor 6 (@capacitor/core ^6.0.0), minSdkVersion 22.

Usage

import { SmsTransceiver } from 'cap-sms-transceiver';

// --- receive, in real time ---
await SmsTransceiver.addListener('smsReceived', event => {
  // event: { sender, body, timestamp } — multipart already reassembled
  if (event.sender.replace(/^\+/, '') !== '8640') return;
  handleReply(event.body);
});

// --- send, with per-part outcome events ---
await SmsTransceiver.addListener('smsSent', e => {
  // e: { messageId, part, parts, ok }
  console.log(`part ${e.part + 1}/${e.parts} sent: ${e.ok}`);
});
await SmsTransceiver.addListener('smsDelivered', e => {
  console.log(`part ${e.part + 1}/${e.parts} delivered: ${e.ok}`);
});

const { parts } = await SmsTransceiver.send({
  number: '8640',
  body: JSON.stringify(payload),
  messageId: crypto.randomUUID(), // echoed on every outcome event
});

send() resolves once the message is handed to the radio stack. Treat a message as sent when all parts have reported smsSent with ok: true. Delivery reports (smsDelivered) are carrier-dependent — do not build correctness on them.

Permissions

const { sms } = await SmsTransceiver.checkPermissions(); // 'granted' | 'denied' | 'prompt'
await SmsTransceiver.requestPermissions();

send() also requests the permission group automatically on first use.

API

See src/definitions.ts for the full typed API:

• send(options: { number, body, messageId }) => Promise<{ messageId, parts }>
• checkPermissions() => Promise<{ sms: PermissionState }>
• requestPermissions() => Promise<{ sms: PermissionState }>
• addListener('smsReceived', cb) — every incoming SMS while the app process is alive
• addListener('smsSent' | 'smsDelivered', cb) — per-part outcome, keyed by messageId
• removeAllListeners()

Behavior notes

• Multipart: incoming concatenated SMS arrive as one smsReceived event with the full reassembled body. Outgoing bodies are split natively; outcome events fire per part.
• App in background/killed: the receiver is registered while the app process is alive (load()), so events fire in foreground and background, but not when the app has been killed. For transport-grade reliability, pair the events with an inbox sweep on app resume (e.g. cap-read-sms) and a durable outbox.
• Dual SIM: uses the default SMS subscription. If you need to pin a SIM, open an issue — SmsManager.getSmsManagerForSubscriptionId support is a small addition.
• Google Play: SEND_SMS/RECEIVE_SMS/READ_SMS are restricted permissions. Direct APK distribution is unaffected; Play distribution requires a permissions declaration.

Testing on an emulator

# Simulate an incoming SMS from a shortcode
adb emu sms send 8640 '{"status":201,"nonce":"<uuid>"}'

Development

npm install
npm run build      # tsc + rollup -> dist/

To develop against a consuming app, install by path so the Java opens as a Gradle module in Android Studio and edits land in this repo (not node_modules):

npm install /path/to/sms-transceiver
npx cap sync android

Releasing

Tag releases and consume by tag for reproducible builds:

npm version 0.1.0 && git push --follow-tags

npm install git+https://github.com/ShekuMunu/sms-transceiver.git#v0.1.0

npm publish also works (package name: cap-sms-transceiver; prepublishOnly builds dist/).

License

MIT