Flutter plugin for telephony features like query device sms directory, listen for incoming messages, retrieve various network parameters, etc.
:exclamation: This plugin currently only works on Android Platform |
---|
A Flutter plugin to use telephony features such as
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.
To use this plugin add telephony
as a dependency in your pubspec.yaml file.
Import the telephony
package
import 'package:telephony/telephony.dart';
Retrieve the singleton instance of telephony
by calling
final Telephony telephony = Telephony.instance;
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;
You can also request SMS or Phone permissions separately using requestSmsPermissions
or requestPhonePermissions
respectively.
:exclamation: Requires SEND_SMS
permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.SEND_SMS"/>
SMS can either be sent directly or via the default SMS app.
telephony.sendSms(
to: "1234567890",
message: "May the force be with you!"
);
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
);
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.
telephony.sendSmsByDefaultApp(to: "1234567890", message: "May the force be with you!");
:exclamation: Requires READ_SMS
permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.READ_SMS"/>
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)]
);
:exclamation: Requires READ_SMS
permission.
Add the following permission in your AndroidManifest.xml
<uses-permission android:name="android.permission.READ_SMS"/>
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)]
);
:exclamation: Requires RECEIVE_SMS
permission.
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>
Create a top-level static function to handle incoming messages when app is not is foreground.
:warning: 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());
}
listenIncomingSms
with a foreground MessageHandler
and pass in the static backgrounMessageHandler
.telephony.listenIncomingSms(
onNewMessage: (SmsMessage message) {
// Handle message
},
onBackgroundMessage: backgroundMessageHandler
);
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
);
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);
}
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;
Check out the detailed documentation to know all possible metrics and their values.
If you want to call the telephony
methods in background, you can do in the following ways.
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()
}
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()
}