Starting a phone call from a Flutter app is easy: open a tel: link and the system dialer does the rest. Being the dialer is a different job. On Android, the app the user picks as the default Phone app is the only one that sees live calls and can answer, hold or merge them. It shows the incoming-call screen, it can screen unwanted callers, and it reads and edits the call log.
android_telecom is a Flutter plugin for that job. It uses the official APIs Android gives the default Phone app: RoleManager.ROLE_DIALER, InCallService, CallScreeningService and the CallLog provider.
What it does
The role. isDefaultDialer() and requestDefaultDialer() check and ask for the role. The request uses RoleManager on API 29 and later, and TelecomManager.ACTION_CHANGE_DEFAULT_DIALER on older versions. isCallScreeningRoleHeld() and requestCallScreeningRole() do the same for the screening role.
Live calls. calls is a Stream<List<CallSnapshot>> fed by the plugin's InCallService. Each snapshot has an id, number, state, direction, connect time, capabilities (hold, mute, merge, swap), conference info and disconnect cause. audioState streams the audio route and the mute state.
Controls. answer, reject(message:), disconnect, hold, unhold, mute, setSpeaker, setAudioRoute (earpiece, speaker, Bluetooth, wired headset, streaming), playDtmf, merge, swap, and placeCall(number, phoneAccount:) through TelecomManager.placeCall.
Screening. A blocklist with rules for unknown and private callers, and the choice to block a call or only silence it. A blocked call can also skip the call log and the notification. The rules are stored natively as JSON in SharedPreferences. The CallScreeningService decides from the cached rules and answers straight away, without waiting for Dart, so screening works even when Flutter is not running.
Number matching. Numbers are compared by country code plus national significant number. 0555123456, +213555123456 and 00213555123456 match. 0775123456 does not, even though its last 7 digits are the same.
Call log. callLog.query(since:, type:, limit:, offset:) and callLog.delete(ids).
In-call UI. When a call rings, the plugin posts an incoming-call notification with a full-screen intent. It uses Notification.CallStyle on API 31 and later. setShowOverLockScreen shows the Flutter activity over the lock screen.
Typed errors. Every method returns a plain Future. On failure it throws a subclass of TelecomException, such as TelecomPermissionException, CallNotFoundException or InCallServiceUnavailableException.
How to use it
Add it from GitHub:
dependencies:
android_telecom:
git: https://github.com/AbdeldjalilChougui/android_telecom
It needs minSdk 24. RoleManager requests, ROLE_CALL_SCREENING, the silence action and the platform-reported call direction need API 29, and Notification.CallStyle needs API 31.
The manifest comes first
Android binds the InCallService only for the default Phone app, and it offers your app in the role prompt only if the manifest has all of these:
- an
InCallServicewithBIND_INCALL_SERVICEand theIN_CALL_SERVICE_UImetadata; - an activity that handles
ACTION_DIAL, both without data and with thetel:scheme.
The plugin ships the services (TelecomInCallService and TelecomCallScreeningService); your app declares them, together with the permissions it uses (CALL_PHONE, READ_PHONE_STATE, READ_CALL_LOG, WRITE_CALL_LOG, POST_NOTIFICATIONS, USE_FULL_SCREEN_INTENT). The README has the full manifest and the example app uses it. Both services are open classes, so you can subclass them and point the manifest at your subclass, as long as you call super from every override.
Without the role, the calls stream stays empty and the controls throw InCallServiceUnavailableException or CallNotFoundException.
Dart
import 'package:android_telecom/android_telecom.dart';
final telecom = AndroidTelecom();
Future<void> setUp() async {
if (!await telecom.isDefaultDialer()) {
final granted = await telecom.requestDefaultDialer();
if (!granted) return; // the user said no
}
// Screening runs natively, even when Flutter is not running.
await telecom.screening.setRules(const ScreeningRules(
matcher: PhoneNumberMatcher(defaultCountryCode: '213'),
blockedNumbers: ['0555123456'],
blockPrivate: true,
action: ScreeningAction.block,
skipNotification: true,
));
}
void listen() {
telecom.calls.listen((calls) {
for (final call in calls) {
print('${call.id} ${call.number} ${call.state.name} ${call.direction.name}');
}
});
}
Future<void> controls(String callId) async {
try {
await telecom.answer(callId);
await telecom.setAudioRoute(AudioRoute.speaker);
await telecom.hold(callId);
await telecom.disconnect(callId);
} on CallNotFoundException {
// The call already ended.
} on TelecomException catch (e) {
print('telecom error ${e.code}: ${e.message}');
}
}
Your app requests the runtime permissions itself, for example with a permissions plugin. When one is missing, the plugin throws TelecomPermissionException.
To keep the call screen visible over the keyguard while a call exists:
telecom.state.listen((s) {
telecom.setShowOverLockScreen(s.calls.isNotEmpty);
});
The notification texts can be changed with configureCallNotifications, and CallNotificationConfig(enabled: false) lets you post your own notification instead.
Number matching in detail
const m = PhoneNumberMatcher(defaultCountryCode: '213'); // trunk '0', intl '00'
m.sameNumber('0555123456', '+213555123456'); // true
m.sameNumber('0555123456', '0775123456'); // false, only the last 7 digits agree
m.canonicalize('+213 (0)555 12 34 56'); // '+213555123456'
The trunk prefix and the international prefixes are configurable, so the same matcher can be set up for other countries. The Dart class and the Kotlin screening service implement the same rules and share the same test cases.
Things to know
- Android only. iOS does not let third-party apps replace the Phone app.
-
Google Play policy. Play restricts the Call Log permission group to the user's default Phone handler and a short list of exceptions, and it asks for the Permissions Declaration Form. A dialer built with this plugin qualifies once the user chooses it, but you still have to declare it.
USE_FULL_SCREEN_INTENTis also restricted on Android 14 and later to calling and alarm apps. The README's section is a summary, not legal advice; read Google's current policy before you publish. -
No numbering-plan data. A number stored in international form without its
+or00(for example213555123456) is read as a national number.suffixMatchLengthis an opt-in fallback for such data. - "Unknown caller" is about presentation. It means the number is hidden, unavailable or empty. It does not mean "not in contacts", because the plugin does not read contacts.
-
Screening details.
skipCallLogandskipNotificationapply only to the block action, and the platform may still log blocked calls with the blocked type. The silence action needs API 29; on older versions the call rings normally. -
Audio routing uses
InCallService.setAudioRoute, which is deprecated on API 34 in favour of call endpoints. It still works there. Selecting a specific Bluetooth device is not exposed. - No video calls. Calls are answered audio-only.
- Losing the role revokes the permissions the role granted, and Android kills the process when it revokes them.
-
What was tested. The Dart API is unit-tested with mocked channels, and the pure Kotlin logic (number matcher, screening engine, call table, audio routes, phone accounts, manifests) with JUnit. The example app has an emulator integration test that takes the dialer role, drives calls with
adb emu gsm call, and checks ringing,answer,hold,mute,setSpeaker, DTMF,disconnect,reject, screening,placeCall,phoneAccountsand the call log againstdumpsys telecom. -
What was not tested. The role request dialog, the call notification and its buttons, conference calls (
merge,swap), switching from the speaker to the earpiece, and Bluetooth routing were not tested on a device. Everything was run on the Android emulator (Pixel 10 image, API 37), not on a physical phone.
Why I built it
A dialer app in Flutter needs several Android pieces that only work together: the role, an InCallService declared the right way, a screening service, a call notification that can wake a locked phone, and call log access. Miss one manifest entry and the system never offers your app in the prompt.
Two parts needed extra care. Screening has to answer quickly, and it cannot depend on a Flutter engine that may not be running, so the rules live on the native side. And comparing phone numbers by their last digits blocks the wrong people, so the matcher works with the country code and the national number, with the same rules and test cases in Dart and Kotlin. I wanted those pieces in one plugin, with typed errors and a clear list of what was and was not tested.
Get the code
The source, the README with the full manifest, the example app and the tests are on GitHub: https://github.com/AbdeldjalilChougui/android_telecom. It's MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)