telephony_kit 0.12.0
telephony_kit: ^0.12.0 copied to clipboard
Phone calls, dialer role, in-call control, SIM, network and call log APIs for Flutter on Android, using JNI bindings generated by jnigen. No method channels.
0.12.0 #
Call waiting (a call ringing while you are on another call)
TelephonyKit.waitingCallandisCallWaiting. Android has no separate state: the new call isCallState.ringingwhile another call is live.PhoneCall.answerAndEndActive()("End & answer") ends the active call and answers.PhoneCall.answer()("Hold & answer") holds it, as before.- The incoming call notification says "Call waiting" and adds an "End & answer" button.
Example
- The call screen shows "Call waiting", who you are talking to, and Decline, Hold & answer and End & answer buttons.
0.11.0 #
Default SMS app
- The package now ships the components Android requires of a default SMS
app, so an app only declares them in its manifest (see the README):
TelephonyKitSmsDeliverReceiver(stores incoming SMS in the inbox and shows a notification),TelephonyKitMmsReceiver(MMS notification) andTelephonyKitRespondViaMessageService(quick replies when a call is rejected with a message). With them,requestDefaultSmsApp()is offered by the system. - As the default SMS app,
sendSmssaves the message (outbox, then sent or failed), as Android requires. takeSmsRequest()returns anSmsRequest(recipients,body,fromNotification) forsms:/smsto:/mms:/mmsto:links from other apps and for taps on a new message notification.smsNotificationsEnabled(saved),clearSmsNotification(address)andclearSmsNotifications().- Fixed: role checks in Java now use
RoleManageron Android 10+, becauseTelephony.Sms.getDefaultSmsPackagereturns null on some devices. - Not supported: downloading or sending MMS. Incoming MMS show a notification only.
Example
- Messages shows conversations, opens a conversation with bubbles and a reply box (marks it read and clears its notification), has a "Set default" banner, and handles sms: links and notification taps.
0.10.0 #
Answer and end calls without being the default dialer
answerRingingCall({video})(Android 8+) andendCurrentCall()(Android 9+) for apps withANSWER_PHONE_CALLS, for example car, headset or accessibility apps. They return false without the permission.
Per-contact ringtone and send to voicemail
getContactCallSettings(id)returnsContactCallSettings(ringtoneUri,ringtoneTitle,sendToVoicemail).setContactRingtone(id, uri)(null for the default) andsetContactSendToVoicemail(id, bool). Android applies them itself, also while the app is the default dialer.- Ringtones:
getRingtones()(RingtoneInfotitle and uri),defaultRingtone,getRingtoneTitle(uri),playRingtonePreview(uri)andstopRingtonePreview().
SIM changes
simChangesstreamsSimInserted,SimRemovedandSimChanged(a different SIM in the same slot), also for eSIM profiles. NeedsREAD_PHONE_STATE. NewSimMonitorJava helper, since Android's subscription listener is a class.- Pure Dart
diffSimCards(before, after).
Example
- Contact details have a ringtone picker with preview and a send to voicemail switch. More tools can answer and end calls without the dialer role and logs SIM changes.
0.9.0 #
Silence the ringer
silenceRinger()stops the ringtone and vibration of the ringing call without rejecting it (default dialer only). The call keeps ringing on screen and can still be answered or declined.
Phone number formatting (Android's PhoneNumberUtils, no extra dependency)
formatPhoneNumber(number): national format for local numbers (010 01234567), international for others (+44 20 7946 0000).formatPhoneNumberAsYouType(input)and thePhoneNumberInputFormattertext input formatter: format while typing like the system dialer, keeping the cursor in place (deleting a space deletes the digit before it).phoneNumberToE164(number),normalizePhoneNumber(number)(letters to digits),isSamePhoneNumber(a, b)(areSamePhoneNumberon Android 12+) andisGlobalPhoneNumber(number).- Country detection:
defaultCountryIso(network, then SIM, then locale) is used when nocountryIsois passed;phoneNumberCountry(number)returns aPhoneNumberCountry(isoCode,callingCode,nationalNumber,flag). - Pure Dart
callingCodeOf,countryOfNumber(North American and +7 numbers told apart by area code),regionsForCallingCode,callingCodeForRegion,formattedCursorOffsetandisDialableChar.
Example
- The keypad formats the number as you type and shows its country. The incoming call screen has a Silence button. More tools has a phone number section with an as-you-type field, formatting and comparing.
0.8.0 #
Call details and history
getCallLogEntry(id): one call with every detail. NewCallLogEntryfieldsformattedNumber,numberLabel,postDialDigits,viaNumber,presentation(NumberPresentation),lookupUri,voicemailUri,transcription,blockReason,screeningAppName,lastModified, and the gettersdisplayName,displayNumber,endTime,wasConnected.getCallHistory(number)andgetContactCallHistory(contactId)return aCallHistorywith every call with that number (in any format) or with all of a contact's numbers, plus counts, talk time, first, last and longest call.CallHistory.frombuilds one from entries you have.searchCallLog(details: true)reads the detail fields too.- Pure Dart
callLogEntryFromRow.
Dates, times and time zones
CallTimeFormatter: call times as phone apps show them (14:05,Yesterday,Monday,12 Nov,5 min ago), full date with the UTC offset, stopwatch and worded durations, 12/24-hour, fixedutcOffset, andCallTimeLabelsfor translations.groupByDayfor section headers.TelephonyKit.timeZone(DeviceTimeZone: IANA id, names, current and standard offset, daylight saving),uses24HourFormatandtimeFormatter.
Call screen
- Answering from the call notification now opens the app on the call
screen, also on Android 12+ where a notification button may not open an
app from a broadcast receiver. Tapping the incoming or ongoing call
notification does the same. New invisible
CallActionActivityin the library manifest (nothing to add to the app). - New
CallScreenRequestedcall event andtakeCallScreenRequest()so apps with a call screen route can open it.
Floating call bubble
TelephonyKit.callBubble: a draggable bubble over other apps while a call is live and the app is in the background, with mute, speaker, end, answer, decline and Open (back to the call screen).enabled(saved),hasPermission,requestPermission()(opens the "display over other apps" setting),isShowing,hide(),labels(CallBubbleLabels). NeedsSYSTEM_ALERT_WINDOWin the app manifest.
Example
- Recents grouped by day with relative times; tapping a call opens a details screen with the full history of the number or contact. Contact details show recent calls and link to the full history. The Device tab shows the time zone and a call bubble switch with the permission flow. The in-call screen opens when answering from the notification.
0.7.0 #
- Contact paging:
getContactsPage(query:, offset:, pageSize:)returns aContactPagewithcontacts,totalCount,nextOffsetandhasMore. The matching ids are collected natively once per search (newContactPagerJava helper), and each page loads only its own contacts, so lists of thousands of contacts scroll smoothly and use little memory. Search matches the name, an email or a phone number in any format, with no cap on the number of matches.clearContactPages()drops the cached ids. - Example: the Contacts tab is now an infinite-scroll list that loads 50 contacts at a time, shows the total, debounces the search, supports pull to refresh and keeps its place after editing a contact. Before, it showed only the first 300 contacts and re-queried on every keystroke.
0.6.0 #
Contacts
- Photos:
getContactPhoto,setContactPhoto. - Groups:
getContactGroups,addContactGroup,renameContactGroup,deleteContactGroup,getContactGroupIds,getGroupMembers,addContactToGroup,removeContactFromGroup;getContactAccounts. - Duplicates:
findDuplicateContacts,mergeContacts,splitContact. - vCard:
exportContactsAsVCard,importVCard, and the pure DartexportVCardandparseVCard. - New contact fields
ContactDetails.ims,relationsandsipAddresses(ContactIm,ContactRelation), saved byaddContactandupdateContact. - System screens:
showContact,openContactEditor,openNewContactScreen. contactChangesstream.
Call log
CallLogEntrygainsgeocodedLocation,subscriptionId,features(hasVideo,isWifi,isHd,isRtt),isReadandcountryIso.addCallLogEntry,getCallLogStats,getGroupedCallLog, and the pure DartcallLogStatsandgroupCallLog.callLogChangesstream.
SMS
getSmsThreads(andgroupSmsThreads),getMmsMessages(read only),incomingSmsandsmsChangesstreams.- Default SMS app:
isDefaultSmsApp,defaultSmsPackage,requestDefaultSmsApp; thendeleteSmsMessages,deleteSmsThread,markSmsRead,markSmsThreadRead. The package does not ship the receivers a default SMS app needs; see the README.
Calls
- Video:
placeCall(video: true),PhoneCall.videoState,isVideo,answerWithVideo. Frames are not rendered. PhoneCall.numberVerification(STIR/SHAKEN, Android 11+),isWifiCall,isHdAudio.- Real-time text:
isRttActive,requestRtt,stopRtt,pendingRttRequestId,respondToRtt,sendRttText,readRttText. - Call forwarding and call waiting through GSM codes:
setCallForwarding,cancelCallForwarding,queryCallForwarding,setCallWaiting,queryCallWaiting.
Device and network
getPhoneNumbers,getCellInfo,signalDbm,isMobileDataEnabled,isDataRoamingAllowed,dataConnectionState,getEsimInfo.- New permission names
TelephonyPermission.accessFineLocation.
Other
- Java helpers
ChangeMonitor,ContactTools,DeviceTools, and moreCallManagerandSmsHelpermethods; bindings regenerated. - The example app has a "More tools" page and richer contact and in-call screens.
- Android does not expose these to third-party apps, so they are not included: reading whether Wi-Fi calling is enabled, a public call waiting query, and sending MMS.
0.5.0 #
- Full contact management:
getContactsandgetContactreturnContactDetailswith name parts, phones, emails, addresses, company, job title, nickname, websites, note, birthday, photo and favorite (contacts without a phone number are included).addContact,updateContact,deleteContact,deleteContactsandsetContactStarredchange the address book. New modelsContactDetails,ContactEmail,ContactAddressand permission nameTelephonyPermission.writeContacts(WRITE_CONTACTS). No new bindings were needed. The example Contacts tab can now open a contact, add, edit, favorite and delete. - Agent skill and docs updated with the new contacts API.
0.4.0 #
-
Agent support:
AGENTS.mdfor contributors and an agent skill inskills/telephony-kit/for apps that use the package. -
Which SIM a call uses:
PhoneCall.phoneAccount(id, carrier label, slot;displayNamesuch asSIM 2 · Vodafone).PhoneAccount.slotIndexis filled on Android 11+. The example shows it on the in-call screen and uses slots on the keypad SIM selector. -
Reject with a message:
PhoneCall.reject(message: ...)texts the caller (Telecom sends it, no SMS permission needed);reject()still works.PhoneCall.cannedTextResponses(the user's replies from the phone settings) andTelephonyKit.quickReplies(defaults, changeable). Example: Reply button on the incoming screen. -
Emergency numbers:
isEmergencyNumber(number). Call screening never blocks or silences emergency numbers (reasonemergency). The example keypad labels them. -
Post-dial digits: a wait (
;) in the dialed number sends aPostDialWaitevent; answer withPhoneCall.continuePostDial(proceed).PhoneCall.postDialRemaining. Pauses (,) need nothing. Example: a "Send remaining digits?" dialog; long press*for,and#for;. -
Disconnect cause:
PhoneCall.disconnectCause(DisconnectCausewithcode,label,description,reason,displayText,isFailure), still readable for the last 20 calls after removal, and a newCallDisconnectedevent sent just beforeCallRemoved. Breaking: an exhaustiveswitchoverCallEventneeds aCallDisconnectedcase. The example shows failures such as "Busy" or "Radio off". -
Proximity sensor: the screen turns off near the ear while a call is active or dialing on the earpiece or a wired headset (not while ringing, on speaker or Bluetooth).
proximitySensorEnabled(default true),isProximityLockHeld. The package now declaresWAKE_LOCK. -
Missed call notifications: declare
TelephonyKitMissedCallReceiverforandroid.telecom.action.SHOW_MISSED_CALLS_NOTIFICATION(exported, withandroid:permission="android.permission.MODIFY_PHONE_STATE"so only Telecom can send it; see the example manifest). As the default dialer the app then shows the missed call notification (count, last caller, Call back button) instead of the system.missedCallNotificationsEnabled,clearMissedCallNotification();markMissedCallsRead()clears it too. -
SIM choice for outgoing calls: while a call is in
CallState.selectPhoneAccount(multi SIM, no default SIM), readPhoneCall.selectablePhoneAccountsand callPhoneCall.selectPhoneAccount(id, setDefault: ...). NewPhoneAccountmodel (id, label, slot) andgetPhoneAccountDetails(). The example shows a SIM picker. -
takeDialNumber()reads the number of the dial intent (tel:link) that opened the app. The example shows it on the keypad instead of crashing on an unknown Flutter route. -
searchCallLogfillsCallLogEntry.idandisNew(deleting single entries works). -
searchContactsfinds partial numbers anywhere in a number (650finds+1 650-555-6789). -
canBlockNumbersis only true for the default dialer or SMS app. -
sendUssdfails after a timeout (30 seconds by default) when the network does not reply. -
Conference changes are reported on
callEvents;swapCallsonly resumes the held call and lets Telecom hold the active one. -
Bindings regenerated; overload suffixes changed in the private bindings.
-
Example: in-call screen shows over pushed pages, conferences show as "Conference (n)", Messages shows an empty state.
0.3.0 #
- Incoming call notification with answer and decline buttons that shows full
screen on the lock screen, and an ongoing call notification with hang up.
showCallNotificationsturns them off. - Call screening:
TelephonyKitCallScreeningServiceapplies block rules (numbers, prefixes, callers not in contacts, hidden numbers) even when the app is closed. Configure throughTelephonyKit.screening; watchscreenedCalls.requestCallScreeningRolefor non-dialer apps. - System block list:
getBlockedNumbers,blockNumber,unblockNumber,isNumberBlocked,canBlockNumbers. - Multi-call and conference:
swapCalls, and onPhoneCallmerge,conferenceWith,swap,splitFromConference,children,parent. - Audio routes:
supportedAudioRoutes,setAudioRoute,bluetoothDevices,selectBluetoothDevice. networkEventsstream (signal level, service state, 2G to 5G, device call state), plussignalLevelandnetworkGeneration.- Call log changes:
deleteCallLogEntries,deleteCallLogForNumber,markMissedCallsRead.CallLogEntryhasidandisNew. voicemailNumber,callVoicemail, andsendUssdfor codes like*100#.- SMS:
sendSmsandsearchSms. - Example: blocking page, messages page, live network, USSD, audio route and keypad sheets, swap and merge, and long press actions on recent calls.
- The example manifest now lets the system play the ringtone
(
IN_CALL_SERVICE_RINGINGfalse).
0.2.0 #
searchCallLog: filter the call log by name or number, call type and date range. Number search ignores formatting and matches local and international forms.searchContacts: search contacts by name or number, with all their numbers, photo and favorite flag.lookupNumber: find the contact saved for a number, for caller names.TelephonyPermission.readContacts.- Example: search on Recents, a missed calls filter, a Contacts tab, and caller names on the in-call screen.
0.1.0 #
- Initial release, Android only.
- Place calls (with SIM choice) and open the system dialer.
- Check and request the default dialer role.
- In-call control through
TelephonyKitInCallService: call events stream, answer, reject, hang up, hold, DTMF, mute and speaker. - Network, SIM and phone details.
- Read the call log.
- All Android access goes through JNI bindings generated by jnigen.
