Skip to main content

​
Prerequisites

​
Portal setup

Flutter apps are cross-platform, so you need credentials for each platform you target:
  • Android: Follow the Android portal setup to create an Android push credential using your Firebase service account JSON.
  • iOS: Follow the iOS portal setup to create an iOS push credential using your VoIP certificate PEM files.
Attach both credentials to your SIP Connection under the WebRTC tab in the Telnyx Portal.

​
App setup

​
Android — Firebase Cloud Messaging

​
1. Listen for background push notifications

Register a background message handler in your main method: 
@pragma('vm:entry-point')
Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();

    if (defaultTargetPlatform == TargetPlatform.android) {
        await Firebase.initializeApp();
        FirebaseMessaging.onBackgroundMessage(
            _firebaseMessagingBackgroundHandler,
        );
        await FirebaseMessaging.instance
            .setForegroundNotificationPresentationOptions(
                alert: true,
                badge: true,
                sound: true,
            );
    }
    runApp(const MyApp());
}

​
2. Handle the push notification

Process the incoming message and show a call notification using a plugin like FlutterCallkitIncoming: 
Future<void> _firebaseMessagingBackgroundHandler(
    RemoteMessage message,
) async {
    // Show incoming call notification
    CallKitParams callKitParams = CallKitParams(
        android: ...,
        ios: ...,
        extra: message.data,
    );
    await FlutterCallkitIncoming.showCallkitIncoming(callKitParams);

    // Listen for user action
    FlutterCallkitIncoming.onEvent.listen((CallEvent? event) async {
        switch (event!.event) {
            case Event.actionCallAccept:
                TelnyxClient.setPushMetaData(
                    message.data, isAnswer: true, isDecline: false,
                );
                break;
            case Event.actionCallDecline:
                TelnyxClient.setPushMetaData(
                    message.data, isAnswer: false, isDecline: true,
                );
                break;
        }
    });
}

​
3. Create a high-importance notification channel (Android 8.0+)

For Android 8.0 and higher, create a dedicated notification channel so incoming call notifications display as heads-up alerts. Use the flutter_local_notifications package to configure the channel with maximum importance.

​
iOS — Apple Push Notification Service

For iOS, the Flutter SDK uses APNS through the native PushKit integration. Configure your iOS project following the standard iOS app setup, which includes:
  1. Enabling Push Notifications and Background Modes (VoIP) capabilities in Xcode.
  2. Configuring PushKit to register for VoIP pushes.
  3. Reporting incoming calls to CallKit (required on iOS 13+).
The Flutter SDK handles the bridge between native push events and your Dart code.

​
Troubleshooting

​
Android-specific issues

  • FCM token not received: Ensure Firebase.initializeApp() is called before requesting the token and that google-services.json is correctly placed.
  • Notifications not showing in background: Verify your background handler is annotated with @pragma('vm:entry-point') and registered via FirebaseMessaging.onBackgroundMessage.
  • Low-priority notifications: Create a notification channel with Importance.max for incoming call alerts.

​
iOS-specific issues

  • No push notifications: Confirm the VoIP push certificate matches your Bundle ID and is uploaded to the Telnyx Portal.
  • App terminated on push: On iOS 13+, you must report every VoIP push to CallKit or the system kills your app.
  • Environment mismatch: Use sandbox for debug builds and production for release/TestFlight builds.

​
General

  • Push works but no call invitation: The push notification only signals that a call is incoming. Your app must reconnect to the TelnyxClient socket after receiving the push so the actual invitation can be delivered.
  • Multidevice: A user can register up to 5 push tokens. If a 6th is added, the oldest is removed.

​
Next steps