Photo by Artur Shamsutdinov on Unsplash

The Telephony package is a flutter plugin that provides APIs for various things like querying the messages on device, retrieving various network details, etc.

In this article, let’s take a look at one specific capability of the telephony package: Listening to incoming SMS.

Due to the restrictions on access of messages on iOS, this plugin only works on Android.

Initial Setup

First we need to add the telephony dependency in the pubspec.yaml file.

dependencies:  
  telephony: #latest_version

Next we need to register a broadcast receiver in the android project’s AndroidManifest.xml file. It should be located under android/app/src/main

While we are here, let’s also add the RECEIVE_SMS permission that is required so that android will notify our receiver when there is a new incoming SMS.

<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>

Requesting permission from the user

Just registering the permission in the manifest file is not enough. We also need to ask for the permission from the user.

Telephony plugin can handle asking for SMS and phone permissions. To ask user for SMS permissions listed in the manifest we can use requestSmsPermissions . To learn how to ask for permission using the telephony package itself you can refer this documentation.

Although Telephony can ask for permissions in runtime, it is recommended to handle permission separately.

Listening for SMS

With the initial setup done and permissions taken care of, we can now get to actually listening for incoming SMS.

To listen for SMS first let’s get an instance of telephony

import 'package:telephony/telephony.dart';

final Telephony telephony = Telephony.instance;

With this instance of telephony we can call listenIncomingSms and provide it with a callback that will be invoked whenever we get a new SMS when the app is open. We will see how to listen for SMS when the app is in background later in this article.

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

To listen for incoming SMS when the app is in background or not running, we can either set listenInBackground to true and provide a onBackgroundMessage callback. We can skip setting listenInBackground to true if we are setting the background callback.

The onBackgroundMessage callback needs to be top level static function.

backgrounMessageHandler(SmsMessage message) async {
    // Handle background message    
    // You can also call other plugin in here
}

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

Now we pass this callback to the listenIncomingSms function.

telephony.listenIncomingSms(
     onNewMessage: (SmsMessage message) {
         // Handle message
     },
     onBackgroundMessage: backgroundMessageHandler
 );

That’s it! We are set to listen to incoming messages.

Checkout the Telephony plugin on GitHub and pub.dev

You can read the entire documentation to learn about all capabilities of telephony.