Skip to main content

callwave_flutter 0.7.0 copy "callwave_flutter: ^0.7.0" to clipboard
callwave_flutter: ^0.7.0 copied to clipboard

Flutter plugin for WhatsApp, Google Meet, and Teams-style VoIP call UX. Incoming/outgoing notifications, accept/decline/timeout, CallKit and Android full-screen intents.

callwave_flutter #

Public Flutter API for Callwave VoIP/video call UX.

Installation #

dependencies:
  callwave_flutter: ^0.7.0

Requires Dart ^3.11.0, Flutter >=3.41.0, Android API 26+, and iOS 13+. iOS supports CocoaPods and Swift Package Manager.

Screenshots #

Incoming call Native plugin
Incoming call Native plugin
Missed call Video conference
Missed call Video conference
1-to-1 audio 1-to-1 video
1-to-1 audio 1-to-1 video

Why callwave_flutter? #

Plug-and-play call UI for WebRTC video and audio calls. Add WhatsApp-style incoming/outgoing call screens to your Flutter app in minutes—no reinventing the wheel.

  • Works with any WebRTC backend — LiveKit, Agora, Twilio, Daily, Video SDK, Cloudflare Calls (Real-time), or your own. Implement CallwaveEngine, wire your SDK in a few callbacks, and you're done.
  • Native UX out of the box — Full-screen incoming call UI on Android plus native ongoing-call notifications for active calls, and CallKit on iOS. Handles accept, decline, timeout, missed, and callback flows.
  • Cold-start ready — Event buffering and startup route resolution so calls work even when the app launches from a push notification.
  • Conference support — Built-in multi-participant UI with customizable tiles and controls.

If you're building video or voice calls with WebRTC, callwave_flutter gives you the call UX layer so you can focus on your media and signaling.

Platform status: Android has custom native incoming call UI (FullScreenCallActivity) plus native ongoing-call notifications for active incoming-accepted and outgoing calls. iOS uses CallKit system UI for incoming and outgoing calls (Apple's native UI; no custom UI from the plugin). In-app call screen (CallScreen) is shared Flutter UI on both platforms.

iOS supports both CocoaPods and Swift Package Manager. Swift Package Manager support requires Flutter >=3.41.0, while CocoaPods remains supported. The iOS implementation bundles an Apple privacy manifest for its UserDefaults use, which stores plugin-owned call state such as buffered events and pending startup actions.

Missed-call notifications also show while the app is in the foreground: alert on iOS 13, banner and Notification Center on iOS 14+.

Native incoming-call ringtone behavior:

  • 30s timeout -> ringtone keeps playing from 0s to 30s, then stops and the call moves to timeout/missed.
  • accept at 10s -> ringtone stops immediately and the native UI transitions to the ongoing call state.
  • decline at 10s -> ringtone stops immediately and the incoming UI is dismissed.

Core Flow #

  1. Register your engine.
  2. Resolve startup route (home vs call) before runApp.
  3. Wrap your app with CallwaveScope.
class MyCallwaveEngine extends CallwaveEngine {
  @override
  Future<void> onAnswerCall(CallSession session) async {
    final roomToken = session.callData.extra?['roomToken'];
    await mySdk.join(roomToken);
    session.reportConnected();
  }

  @override
  Future<void> onStartCall(CallSession session) async {
    await mySdk.start(session.callId);
    session.reportConnected();
  }

  @override
  Future<void> onEndCall(CallSession session) async {
    await mySdk.leave();
  }

  @override
  Future<void> onDeclineCall(CallSession session) async {}

  @override
  Future<void> onMuteChanged(CallSession session, bool muted) async {}

  @override
  Future<void> onSpeakerChanged(CallSession session, bool speakerOn) async {}

  @override
  Future<void> onCameraChanged(CallSession session, bool enabled) async {}

  @override
  Future<void> onCameraSwitch(CallSession session) async {}

  @override
  Future<void> onDispose(CallSession session) async {}
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final navKey = GlobalKey<NavigatorState>();
  CallwaveFlutter.instance.configure(
    CallwaveConfiguration(
      engine: MyCallwaveEngine(),
      incomingCallHandling: const IncomingCallHandling.realtime(),
    ),
  );
  final startup = await CallwaveFlutter.instance.prepareStartupRouteDecision();

  runApp(
    MaterialApp(
      navigatorKey: navKey,
      initialRoute: startup.shouldOpenCall ? '/call' : '/home',
      routes: <String, WidgetBuilder>{
        '/home': (_) => const HomeScreen(),
        '/call': (_) => StartupCallRoute(callId: startup.callId),
      },
      builder: (_, child) => CallwaveScope(
        navigatorKey: navKey,
        preRoutedCallIds: startup.callId == null
            ? const <String>{}
            : <String>{startup.callId!},
        child: child!,
      ),
    ),
  );
}

setEngine(engine) still works and keeps the same realtime behavior for apps that do not need extra configuration.

Calling configure(...) or setEngine(...) again resets the singleton's tracked sessions. Treat it as startup/setup configuration, not something to switch while a call is already active.

Incoming Call Models #

callwave_flutter now supports two explicit incoming-call behaviors.

1. Realtime #

Use this for WhatsApp-style signaling where the caller can cancel the ring before answer and native accepted should immediately continue into the in-app call flow.

CallwaveFlutter.instance.configure(
  CallwaveConfiguration(
    engine: MyCallwaveEngine(),
    incomingCallHandling: const IncomingCallHandling.realtime(),
  ),
);

Flow:

  • Native accept arrives.
  • The package confirms the accepted call.
  • Session moves to connecting.
  • onAnswerCall() runs and CallwaveScope can open the call UI.

2. Validated #

Use this for push-driven ringing where the user may accept after the call is already cancelled, ended, or expired on the backend.

CallwaveFlutter.instance.configure(
  CallwaveConfiguration(
    engine: MyCallwaveEngine(),
    incomingCallHandling: IncomingCallHandling.validated(
      validator: (session) async {
        final isStillActive = await api.validateIncomingAccept(session.callId);
        if (isStillActive) {
          return const CallAcceptDecision.allow();
        }
        return const CallAcceptDecision.reject(
          reason: CallAcceptRejectReason.cancelled,
        );
      },
    ),
    backgroundIncomingCallDeclineValidator: (request) async {
      // api: your HTTP client (e.g. Dio, http)
      final response = await api.post('/voice-calls/decline/${request.callId}');
      final didReport = response.isSuccessful;
      if (didReport) {
        return const CallDeclineDecision.reported();
      }
      return const CallDeclineDecision.failed(
        reason: CallDeclineFailureReason.failed,
      );
    },
  ),
);

Flow:

  • Native accept arrives.
  • Session moves to validating and stays off the full call screen.
  • If validation allows, the package confirms the accepted call, moves the session to connecting, and runs onAnswerCall().
  • If validation rejects, the package emits missed-call handling with CallEventExtraKeys.outcomeReason and does not open the call screen.
  • On Android, background validated rejects stay off the foreground; terminated validated rejects run through a transient native bridge and can resolve directly to missed-call handling when a background validator is registered.
  • In the example app, the Validated Allow and Validated Reject modes are mainly demonstrated as terminated/cold-start scenarios because that is where their startup-handoff behavior is most visible.
  • When the user declines from native UI while Flutter is not alive, a registered backgroundIncomingCallDeclineValidator runs in a headless isolate.
  • If the decline validator returns CallDeclineDecision.reported(), the plugin closes the incoming call silently and does not show missed-call UI.
  • If the decline validator fails, throws, or times out, the plugin falls back to missed-call handling.
  • On iOS, pure-Dart background callbacks work out of the box. If your background callback uses Flutter plugins such as secure storage, register plugins for the background engine in AppDelegate:
import callwave_flutter_method_channel

@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    CallwaveFlutterPlugin.setBackgroundFlutterPluginRegistrant { registry in
      GeneratedPluginRegistrant.register(with: registry)
    }
    return super.application(
      application,
      didFinishLaunchingWithOptions: launchOptions
    )
  }
}

Cold Start #

prepareStartupRouteDecision() restores active sessions and returns a route decision:

  • Open call route when a session is connecting, connected, or reconnecting.
  • Open call route for ringing only when the native layer explicitly launched the app for that incoming call (for example, tapping the Android incoming call body or reopening a still-ringing CallKit call on iOS).
  • Stay on home route when sessions are only ordinary ringing, idle, validating, or none exist.

If your app does not use startup routing in main, CallwaveScope still auto-pushes CallScreen as fallback once a live session becomes routable. On startup hydration it keeps ordinary restored ringing sessions on home unless the native event explicitly requested the incoming call UI.

On Android, keep these intent actions on your host Activity so the plugin can reopen the correct screen:

<intent-filter>
    <action android:name="com.callwave.flutter.methodchannel.ACTION_ACCEPT_AND_OPEN" />
    <action android:name="com.callwave.flutter.methodchannel.ACTION_OPEN_INCOMING" />
    <action android:name="com.callwave.flutter.methodchannel.ACTION_OPEN_ONGOING" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

CallScreen #

CallScreen is session-driven: pass a CallSession, not raw CallData.

CallScreen(session: session, onCallEnded: () => navigator.pop());

For standalone usage outside CallwaveScope, you can pass theme directly:

CallScreen(
  session: session,
  theme: const CallwaveThemeData(),
)

Sessions come from CallwaveFlutter.sessions or CallwaveFlutter.getSession. CallwaveScope pushes CallScreen automatically when sessions are created.

Conference UI (Current Style) #

CallScreen automatically switches to conference mode when session.participantCount > 1.

  • Keeps the current Callwave visual style (same gradient/action-button language).
  • Uses a plain bottom control row in SafeArea (no rounded dock container).
  • Default video conference controls: Mic, Speaker, Cam, End.
  • Default audio conference controls: Mic, Speaker, End.
  • One-to-one audio keeps the classic avatar layout; connected one-to-one video uses square split/PiP surfaces with conference-style controls.

Conference State API #

Use CallSession.updateConferenceState to provide participants and speaker data.

session.updateConferenceState(
  ConferenceState(
    participants: const [
      CallParticipant(participantId: 'p-1', displayName: 'Ava'),
      CallParticipant(participantId: 'p-2', displayName: 'Milo'),
      CallParticipant(participantId: 'local', displayName: 'You', isLocal: true),
    ],
    activeSpeakerId: 'p-1',
    updatedAtMs: DateTime.now().millisecondsSinceEpoch,
  ),
);

Race-safety rules:

  • Older updatedAtMs snapshots are ignored.
  • Updates are ignored once the session is ended/failed.
  • Duplicate participantId entries are deduped (latest entry wins).

Optional Builders #

CallwaveScope provides conference customization hooks:

CallwaveScope(
  navigatorKey: navKey,
  participantTileBuilder: (context, session, participant, isPrimary) {
    // Inject your RTC view for this participant.
    return ColoredBox(
      color: isPrimary ? const Color(0xFF0D4F4F) : const Color(0xFF1A6B6B),
      child: Center(child: Text(participant.displayName)),
    );
  },
  conferenceControlsBuilder: (context, session) {
    // Optional: override the default Mic/Speaker/Cam/End row.
    return const SizedBox.shrink();
  },
  child: child!,
)

You can also replace the entire conference surface with conferenceScreenBuilder.

Missed Call Notifications #

Missed-call notifications appear after timeout, decline fallback, or markMissed(). On iOS they also show while the app is in the foreground: alert on iOS 13, banner and Notification Center on iOS 14+.

Set [CallData.extra] with [CallDataExtraKeys.androidMissedCallNotificationText] to customize the Android missed-call notification body.

final call = CallData(
  callId: 'call-42',
  callerName: 'Dan',
  handle: '+1 555 0101',
  extra: const <String, dynamic>{
    CallDataExtraKeys.androidMissedCallNotificationText:
        'You missed a call from Dan.',
  },
);

If you do not provide it, Android falls back to the default callerName (handle) text. iOS ignores this key.

One-to-One Split-to-PiP Builders #

For one-to-one connected video, you can inject remote/local RTC widgets:

CallwaveScope(
  navigatorKey: navKey,
  oneToOneRemoteVideoBuilder: (context, session) {
    return rtcRemoteView(session.callId);
  },
  oneToOneLocalVideoBuilder: (context, session) {
    return rtcLocalView(session.callId);
  },
  child: child!,
)

Behavior:

  • Connected one-to-one starts in a centered 50/50 split with square tiles (remote top, local bottom).
  • Tap a tile to enter large-square + square PiP mode.
  • Tap PiP to swap; tap primary to return to split.
  • Built-in framing is BoxFit.cover-style (crop allowed, no stretch) with a matte stage background.
  • If builders are omitted, fallback remote/local surfaces are shown.

To preserve remote/local camera geometry for custom RTC widgets, wrap them in VideoViewport:

oneToOneLocalVideoBuilder: (context, session) {
  return VideoViewport(
    aspectRatio: 9 / 16,
    fit: BoxFit.cover,
    child: rtcLocalView(session.callId),
  );
},

Notes #

  • Native accept/decline/end remains authoritative.
  • CallSession is the single source of truth for UI state.
  • Accepted events may include CallEventExtraKeys.acceptanceState with pendingValidation or confirmed.
  • Missed/rejected validation flows surface CallEventExtraKeys.outcomeReason.
  • CallwaveScope auto-pushes one call screen per callId and does not auto-pop.
  • CallwaveScope.navigatorKey must be the same key used by your app's MaterialApp.
  • CallwaveEngine must be set before session operations (including restoreActiveSessions).

Outgoing calls and ringback #

Automatic playback #

await CallwaveFlutter.instance.showOutgoingCall(
  const CallData(
    callId: 'call-456',
    callerName: 'Bob',
    handle: 'bob@example.com',
  ),
);

RingbackStartMode.automatic is the default. Playback starts when the platform is ready:

Mode Android iOS
automatic Call screen is visible after its entrance finishes CallKit activates the audio session
appControlled Screen is visible and host grants permission Screen is visible, host grants permission, and CallKit activates audio

Signaling continues independently of ringback. Set playRingback: false if your media SDK supplies its own tone. maxRingbackDuration defaults to 120 seconds, counts from playback, and stops only sound. It is sent in whole seconds with a minimum of one second. CallData.timeout applies to incoming calls.

Host-controlled playback #

Choose appControlled when your app must prepare its audio route before sound starts. Configure your CallwaveEngine before creating the session:

final session = CallwaveFlutter.instance.createSession(
  callData: const CallData(
    callId: 'call-456',
    callerName: 'Bob',
    handle: 'bob@example.com',
    ringbackStartMode: RingbackStartMode.appControlled,
  ),
  isOutgoing: true,
);
await session.start();

// Call after your app or media SDK has prepared its audio route.
await session.allowOutgoingRingback();

Permission can be granted before the screen or native setup is ready. It is remembered for that attempt. The method returns after recording permission locally; it does not wait for visibility, CallKit activation, or playback. Without permission, ringback stays silent. playRingback: false disables sound in either mode. Choose the mode when creating the attempt; live switching is unsupported.

Sessions created automatically by showOutgoingCall() receive the native ringback settings. Existing sessions keep their attempt settings.

Custom screens and navigation #

CallwaveScope, its callScreenBuilder, and standalone CallScreen report readiness automatically. Wrap other call screens, including custom routers and startup routes, with:

CallwaveCallScreenReady(
  session: session,
  child: MyCallScreen(session: session),
)

The wrapper waits until the route is current, the app is resumed, the content has painted, and entrance animations have completed. Hidden or fully transparent content cannot report readiness. Pass entranceAnimation for a custom content transition. Mount the wrapper when loading has finished and the screen is ready. Nested wrappers use the innermost screen and also wait for ancestor animations.

Without a ModalRoute, report visibility directly:

session.setCallScreenVisible(true); // After the screen entrance renders.
session.setCallScreenVisible(false); // When hidden or disposed.

Upgrading from 0.6.x: Android no longer plays ringback immediately. Custom navigation must report readiness; otherwise the call continues silently. iOS automatic mode still uses CallKit activation.

In app-controlled mode, hiding before playback prevents startup until the screen is visible again and retains permission. Hiding after playback does not pause sound. Cached screens can become ready again without repainting.

Raw-event integrations #

Capture CallEventExtraKeys.outgoingRingbackRequestId from the attempt's started event. Pass that same request ID to these CallwaveFlutter.instance methods:

Method When to call
reportOutgoingCallScreenVisible(callId, requestId: token) After the screen entrance has rendered
allowOutgoingRingback(callId, requestId: token) When the host is ready for sound in app-controlled mode
reportOutgoingCallScreenHidden(callId, requestId: token) When a pending app-controlled screen is hidden or disposed

Keep the token with its attempt, even when reusing a call ID. Native permission completion acknowledges the signal without waiting for playback.

Playback lifecycle and audio routing #

Connection, termination, failure, cleanup, and engine teardown invalidate pending playback. Duplicate or stale signals cannot restart sound or affect a replacement attempt. Process restoration does not restart ringback. Repeated outgoing setup updates the active call without emitting another start event. iOS audio reactivation does not extend the original playback duration cap.

The host owns audio routing. Permission does not select an earpiece or Bluetooth device. Android uses the voice-call stream without changing audio mode or route. iOS keeps its CallKit behavior: when ringback is enabled and the category is not already .playAndRecord, the plugin selects .playAndRecord / .voiceChat.

6
likes
150
points
1.49k
downloads

Documentation

API reference

Publisher

verified publishereffdel.com

Weekly Downloads

Flutter plugin for WhatsApp, Google Meet, and Teams-style VoIP call UX. Incoming/outgoing notifications, accept/decline/timeout, CallKit and Android full-screen intents.

Repository (GitHub)
View/report issues

License

BSD-3-Clause (license)

Dependencies

callwave_flutter_method_channel, callwave_flutter_platform_interface, flutter

More

Packages that depend on callwave_flutter

Packages that implement callwave_flutter