telephony_sms_handler

Description:

telephony sms handler

Telephony #
Thank you for checking out the Telephony plugin. #



❗ This plugin currently only works on Android Platform



A Flutter plugin to use telephony features such as

Send SMS Messages
Query SMS Messages
Listen for incoming SMS
Retrieve various network parameters
Start phone calls

This plugin tries to replicate some of the functionality provided by Android's Telephony class.
Check the Features section to see the list of implemented and missing features.
Get Started #
💡 View the entire documentation here. #
Usage #
To use this plugin add telephony as a dependency in your pubspec.yaml file.
Versions 0.0.9 and lower are not null safe.
Versions 0.1.0 and above opt into null safety.
Setup #
Import the telephony package
import 'package:telephony/telephony.dart';
copied to clipboard
Retrieve the singleton instance of telephony by calling
final Telephony telephony = Telephony.instance;
copied to clipboard
Permissions #
Although this plugin will check and ask for permissions at runtime, it is advisable to manually ask for permissions before calling any other functions.
The plugin will only request those permission that are listed in the AndroidManifest.xml.
Manually request permission using
bool permissionsGranted = await telephony.requestPhoneAndSmsPermissions;
copied to clipboard
You can also request SMS or Phone permissions separately using requestSmsPermissions or requestPhonePermissions respectively.
Send SMS #
❗ Requires SEND_SMS permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.SEND_SMS"/>
copied to clipboard
SMS can either be sent directly or via the default SMS app.
Send SMS directly from your app:
telephony.sendSms(
to: "1234567890",
message: "May the force be with you!"
);
copied to clipboard
If you want to listen to the status of the message being sent, provide SmsSendStatusListener to the sendSms function.
final SmsSendStatusListener listener = (SendStatus status) {
// Handle the status
};

telephony.sendSms(
to: "1234567890",
message: "May the force be with you!",
statusListener: listener
);
copied to clipboard
If the body of the message is longer than the standard SMS length limit of 160 characters, you can send a multipart SMS by setting the isMultipart flag.
Send SMS via the default SMS app:
telephony.sendSmsByDefaultApp(to: "1234567890", message: "May the force be with you!");
copied to clipboard
Query SMS #
❗ Requires READ_SMS permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.READ_SMS"/>
copied to clipboard
Use one of getInboxSms(), getSentSms() or getDraftSms() functions to query the messages on device.
You can provide the list of SmsColumns that need to be returned by the query.
If not explicitly specified, defaults to [ SmsColumn.ID, SmsColumn.ADDRESS, SmsColumn.BODY, SmsColumn.DATE ]
Provide a SmsFilter to filter the results of the query. Functions like a SQL WHERE clause.
Provide a list of OrderBy objects to sort the results. The level of importance is determined by the position of OrderBy in the list.
All paramaters are optional.
List<SmsMessage> messages = await telephony.getInboxSms(
columns: [SmsColumn.ADDRESS, SmsColumn.BODY],
filter: SmsFilter.where(SmsColumn.ADDRESS)
.equals("1234567890")
.and(SmsColumn.BODY)
.like("starwars"),
sortOrder: [OrderBy(SmsColumn.ADDRESS, sort: Sort.ASC),
OrderBy(SmsColumn.BODY)]
);
copied to clipboard
Query Conversations #
❗ Requires READ_SMS permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.READ_SMS"/>
copied to clipboard
Works similar to SMS queries.
All columns are returned with every query. They are [ ConversationColumn.SNIPPET, ConversationColumn.THREAD_ID, ConversationColumn.MSG_COUNT ]
Uses ConversationFilter instead of SmsFilter.
List<SmsConversation> messages = await telephony.getConversations(
filter: ConversationFilter.where(ConversationColumn.MSG_COUNT)
.equals("4")
.and(ConversationColumn.THREAD_ID)
.greaterThan("12"),
sortOrder: [OrderBy(ConversationColumn.THREAD_ID, sort: Sort.ASC)]
);
copied to clipboard
Listen to incoming SMS #
❗ Requires RECEIVE_SMS permission.

To listen to incoming SMS add the RECEIVE_SMS permission to your AndroidManifest.xml file and register the BroadcastReceiver.

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

<application>
...
...

<receiver android:name="com.shounakmulay.telephony.sms.IncomingSmsReceiver"
android:permission="android.permission.BROADCAST_SMS" android:exported="true">
<intent-filter>
<action android:name="android.provider.Telephony.SMS_RECEIVED"/>
</intent-filter>
</receiver>

</application>
</manifest>
copied to clipboard


Create a top-level static function to handle incoming messages when app is not is foreground.
⚠️ Avoid heavy computations in the background handler as Android system may kill long running operations in the background.


backgrounMessageHandler(SmsMessage message) async {
//Handle background message
}

void main() {
runApp(MyApp());
}
copied to clipboard

Call listenIncomingSms with a foreground MessageHandler and pass in the static backgrounMessageHandler.

telephony.listenIncomingSms(
onNewMessage: (SmsMessage message) {
// Handle message
},
onBackgroundMessage: backgroundMessageHandler
);
copied to clipboard
Preferably should be called early in app lifecycle.


If you do not wish to receive incoming SMS when the app is in background, just do not pass the onBackgroundMessage paramater.
Alternatively if you prefer to expecility disable background execution, set the listenInBackground flag to false.


telephony.listenIncomingSms(
onNewMessage: (SmsMessage message) {
// Handle message
},
listenInBackground: false
);
copied to clipboard

As of the 1.12 release of Flutter, plugins are automatically registered. This will allow you to use plugins as you normally do even in the background execution context.

backgrounMessageHandler(SmsMessage message) async {
// Handle background message

// Use plugins
Vibration.vibrate(duration: 500);
}
copied to clipboard
Network data and metrics #
Fetch various metrics such as network type, sim state, etc.

// Check if a device is capable of sending SMS
bool canSendSms = await telephony.isSmsCapable;

// Get sim state
SimState simState = await telephony.simState;
copied to clipboard
Check out the detailed documentation to know all possible metrics and their values.
Executing in background #
If you want to call the telephony methods in background, you can do in the following ways.
1. Using only Telephony.instance
If you want to continue using Telephony.instance in the background, you will need to make sure that once the app comes back to the front, it again calls Telephony.instance.
backgrounMessageHandler(SmsMessage message) async {
// Handle background message
Telephony.instance.sendSms(to: "123456789", message: "Message from background")
}

void main() {
runApp(MyApp());
}

class _MyAppState extends State<MyApp> {
String _message;
// This will not work as the instance will be replaced by
// the one in background.
final telephony = Telephony.instance;

@override
void initState() {
super.initState();
// You should make sure call to instance is made every time
// app comes to foreground
final inbox = Telephony.instance.getInboxSms()
}

copied to clipboard
2. Use backgroundInstance
If you cannot make sure that the call to instance would be made every time app comes to foreground, or if you would prefer to maintain a separate background instance,
you can use Telephony.backgroundInstance in the background execution context.
backgrounMessageHandler(SmsMessage message) async {
// Handle background message
Telephony.backgroundInstance.sendSms(to: "123456789", message: "Message from background")
}

void main() {
runApp(MyApp());
}

class _MyAppState extends State<MyApp> {
String _message;
final telephony = Telephony.instance;

@override
void initState() {
super.initState();
final inbox = telephony.getInboxSms()
}

copied to clipboard
Features #

✅ Send SMS
✅ Query SMS

✅ Inbox
✅ Sent
✅ Draft


✅ Query Conversations
✅ Listen to incoming SMS

✅ When app is in foreground
✅ When app is in background


✅ Network data and metrics

✅ Cellular data state
✅ Call state
✅ Data activity
✅ Network operator
✅ Network operator name
✅ Data network type
✅ Phone type
✅ Sim operator
✅ Sim operator name
✅ Sim state
✅ Network roaming
✅ Signal strength
✅ Service state


✅ Start Phone Call
❌ Schedule a SMS
❌ SMS Retriever API