Package selection guidance compiled from public package information, community data, and project usage.
The phone_state package provides a simple way to detect incoming calls and monitor call status on Android and iOS devices. It enables apps to respond dynamically when a call is received, such as pausing media playback or adjusting app behavior. The plugin leverages native device APIs to deliver real-time call state updates with minimal setup. It's ideal for applications requiring awareness of telephony events, like music players, messaging apps, or productivity tools that need to adapt during calls.
Use cases
Detecting incoming calls
Pausing media during calls
Adjusting app behavior during calls
Monitoring call status in real time
Integrating with telephony-aware features
Key features
Real-time call state detection
Cross-platform support (Android & iOS)
Minimal configuration
Native API integration
Lightweight and efficient
Suitable for
Media playback apps
Productivity tools
Messaging applications
Telephony-integrated services
Apps needing call event awareness
Considerations
Requires appropriate permissions on both platforms
Limited to call state, not full telephony control
May require background execution handling
Behavior varies slightly between Android and iOS
Not suitable for making or managing calls
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
DESCRIPTION
This plugin allows you to know quickly and easily if your Android or iOS device is receiving a call and to know the status of the call.
The caller phone number is only available on Android, not iOS
This plugin reports phone call state only. It does not answer, reject, end, or record calls, and it does not change whether other packages can capture call audio.
Android detects system telephony call state only. Third-party VoIP calls from apps such as Telegram or WhatsApp are not supported. iOS CallKit behavior can differ by app.
The iOS implementation uses CallKit. For apps distributed in regions where CallKit is restricted, including China App Store review contexts, confirm availability and territory rules with Apple before submission.
PhoneState.stream requires the app process to be running with an active Flutter engine and listener. It does not send callbacks after the app is terminated.
On Android, if PhoneState.stream does not emit, confirm READ_PHONE_STATE is declared and granted at runtime. Some OEM battery or background restrictions, including MIUI settings on Xiaomi devices, can also delay or block callbacks.
HOW TO INSTALL
Flutter
Note: This version requires Flutter >= 3.44.0 and Dart >= 3.12.2.
Add phone_state to your app's pubspec.yaml, not to this package's pubspec.yaml. Your app/package name must be different from phone_state.
If phone_state stops receiving updates after adding another package:
Confirm the required Android runtime permissions are granted before listening. READ_PHONE_STATE is required, and READ_CALL_LOG is only needed for caller phone numbers.
Keep a single active PhoneState.stream listener for each app flow. Cancel the previous subscription before starting another one when screens, services, or background handlers change.
When reporting a conflict, include the other package names, platform versions, a minimal reproduction, and the relevant Flutter, Logcat, or Xcode logs.
SCREENSHOT
Write me in the GitHub issues the new features you need and, if they are approved of course, I will implement them as soon as I can.
