Zendesk Messaging for Flutter #

English | 繁體中文 | 简体中文 | Español | Português (Brasil) | 日本語 | 한국어

A Flutter plugin for integrating Zendesk Messaging SDK into your mobile applications. Provides in-app customer support messaging with multi-conversation support, real-time events, and JWT authentication.

Features #

• Initialize and display the Zendesk Messaging UI
• JWT user authentication
• Multi-conversation navigation
• Real-time event streaming (24 event types)
• Unread message count tracking
• Conversation tags and custom fields
• Connection status monitoring
• Push notifications support (FCM/APNs)

Requirements #

Installation #

Add zendesk_messaging to your pubspec.yaml:

dependencies:
  zendesk_messaging: ^3.1.0

Android Setup #

Add the Zendesk Maven repository to your project-level android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://zendesk.jfrog.io/artifactory/repo' }
    }
}

iOS Setup #

Update your ios/Podfile to target iOS 14.0:

platform :ios, '14.0'

Then run:

cd ios && pod install

Quick Start #

Getting Channel Keys #

Before initializing the SDK, you need to obtain your Android and iOS channel keys from the Zendesk Admin Center:

1. Go to Admin Center > Channels > Messaging and social > Messaging
2. Hover over the brand you want to configure and click the options icon
3. Click Edit and navigate to the Installation section
4. Under Channel ID, click Copy to copy the key to your clipboard
5. Use this key for both Android and iOS initialization

Note: The same Channel ID is used for both platforms. You can create separate channels for Android and iOS if needed.

Initialize #

import 'package:zendesk_messaging/zendesk_messaging.dart';

// Initialize the SDK (call once at app startup)
await ZendeskMessaging.initialize(
  androidChannelKey: '<YOUR_ANDROID_CHANNEL_KEY>',
  iosChannelKey: '<YOUR_IOS_CHANNEL_KEY>',
);

Show Messaging UI #

// Show the default messaging interface
await ZendeskMessaging.show();

// Show a specific conversation (requires multi-conversation enabled)
await ZendeskMessaging.showConversation('conversation_id');

// Show the conversation list
await ZendeskMessaging.showConversationList();

// Start a new conversation
await ZendeskMessaging.startNewConversation();

User Authentication #

// Login with JWT
try {
  final response = await ZendeskMessaging.loginUser(jwt: '<YOUR_JWT_TOKEN>');
  print('Logged in: ${response.id}');
} catch (e) {
  print('Login failed: $e');
}

// Check login status
final isLoggedIn = await ZendeskMessaging.isLoggedIn();

// Get current user
final user = await ZendeskMessaging.getCurrentUser();
if (user != null) {
  print('User ID: ${user.id}');
  print('External ID: ${user.externalId}');
  print('Auth type: ${user.authenticationType.name}');
}

// Logout
await ZendeskMessaging.logoutUser();

Event Handling #

The SDK provides a unified event stream for all Zendesk events. Use Dart 3 pattern matching to handle specific event types:

ZendeskMessaging.eventStream.listen((event) {
  switch (event) {
    case UnreadMessageCountChanged(:final totalUnreadCount, :final conversationId):
      print('Unread: $totalUnreadCount${conversationId != null ? ' (conversation: $conversationId)' : ''}');

    case AuthenticationFailed(:final errorMessage, :final isJwtExpired):
      print('Auth failed: $errorMessage (JWT expired: $isJwtExpired)');
      if (isJwtExpired) {
        // Refresh JWT token
      }

    case ConnectionStatusChanged(:final status):
      print('Connection: ${status.name}');

    case ConversationAdded(:final conversationId):
      print('Conversation added: $conversationId');

    case ConversationStarted(:final conversationId):
      print('Conversation started: $conversationId');

    case ConversationOpened(:final conversationId):
      print('Conversation opened: ${conversationId ?? 'default'}');

    case MessagesShown(:final conversationId, :final messages):
      print('Messages shown: ${messages.length} in $conversationId');

    case SendMessageFailed(:final errorMessage):
      print('Send failed: $errorMessage');

    case FieldValidationFailed(:final errors):
      print('Field validation failed: ${errors.join(', ')}');

    case MessagingOpened():
      print('Messaging UI opened');

    case MessagingClosed():
      print('Messaging UI closed');

    case ProactiveMessageDisplayed(:final proactiveMessageId):
      print('Proactive message displayed: $proactiveMessageId');

    case ProactiveMessageClicked(:final proactiveMessageId):
      print('Proactive message clicked: $proactiveMessageId');

    case ConversationWithAgentRequested(:final conversationId):
      print('Agent requested: $conversationId');

    case ConversationWithAgentAssigned(:final conversationId):
      print('Agent assigned: $conversationId');

    case ConversationServedByAgent(:final conversationId, :final agentId):
      print('Agent serving: $agentId in $conversationId');

    case NewConversationButtonClicked():
      print('New conversation button clicked');

    case PostbackButtonClicked(:final actionName):
      print('Postback clicked: $actionName');

    case ArticleClicked(:final articleUrl):
      print('Article clicked: $articleUrl');

    case ArticleBrowserClicked(:final articleUrl):
      print('Article opened in browser: $articleUrl');

    case ConversationExtensionOpened(:final extensionUrl):
      print('Extension opened: $extensionUrl');

    case ConversationExtensionDisplayed(:final extensionUrl):
      print('Extension displayed: $extensionUrl');

    case NotificationDisplayed(:final conversationId):
      print('Notification displayed: $conversationId');

    case NotificationOpened(:final conversationId):
      print('Notification opened: $conversationId');
  }
});

// Start listening for events
await ZendeskMessaging.listenUnreadMessages();

Available Events #

Unread Message Count #

// Get current count
final count = await ZendeskMessaging.getUnreadMessageCount();

// Get count for specific conversation
final convCount = await ZendeskMessaging.getUnreadMessageCountForConversation('conv_id');

// Listen to count changes (legacy API)
ZendeskMessaging.unreadMessagesCountStream.listen((count) {
  print('Unread: $count');
});

Conversation Tags & Fields #

// Set tags (applied when user sends a message)
await ZendeskMessaging.setConversationTags(['vip', 'mobile', 'flutter']);

// Clear tags
await ZendeskMessaging.clearConversationTags();

// Set custom fields
await ZendeskMessaging.setConversationFields({
  'app_version': '3.0.0',
  'platform': 'flutter',
  'user_tier': 'premium',
});

// Clear fields
await ZendeskMessaging.clearConversationFields();

Connection Status #

final status = await ZendeskMessaging.getConnectionStatus();

// Handle different connection states
final color = switch (status) {
  ZendeskConnectionStatus.connected ||
  ZendeskConnectionStatus.connectedRealtime => Colors.green,
  ZendeskConnectionStatus.connectingRealtime => Colors.orange,
  ZendeskConnectionStatus.disconnected => Colors.red,
  ZendeskConnectionStatus.unknown => Colors.grey,
};

Push Notifications #

Enable push notifications to notify users of new messages when the app is in the background or closed.

Requirements #

Setup #

Android

1. Add Firebase to your Android app (Firebase setup guide)
2. Add firebase_messaging to your pubspec.yaml:

   dependencies:
     firebase_messaging: ^15.0.0
   

3. Get your FCM Server Key from Firebase Console
4. Upload the key to Zendesk Admin Center > Channels > Messaging > Android > Notifications

iOS

1. Create an APNs certificate in Apple Developer Portal
2. Export as .p12 file from Keychain Access
3. Upload to Zendesk Admin Center > Channels > Messaging > iOS > Notifications
4. Add Push Notifications capability in Xcode

Usage #

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:zendesk_messaging/zendesk_messaging.dart';

Future<void> setupPushNotifications() async {
  final messaging = FirebaseMessaging.instance;

  // Request permission
  await messaging.requestPermission();

  // Get and register token
  final token = await messaging.getToken();
  if (token != null) {
    await ZendeskMessaging.updatePushNotificationToken(token);
  }

  // Listen for token refresh
  messaging.onTokenRefresh.listen((token) {
    ZendeskMessaging.updatePushNotificationToken(token);
  });

  // Handle foreground notifications
  FirebaseMessaging.onMessage.listen((message) async {
    final responsibility = await ZendeskMessaging.shouldBeDisplayed(message.data);
    switch (responsibility) {
      case ZendeskPushResponsibility.messagingShouldDisplay:
        await ZendeskMessaging.handleNotification(message.data);
      case ZendeskPushResponsibility.notFromMessaging:
        // Handle your own notification
        break;
      default:
        break;
    }
  });

  // Handle notification tap (app in background)
  FirebaseMessaging.onMessageOpenedApp.listen((message) async {
    await ZendeskMessaging.handleNotificationTap(message.data);
  });
}

Push Notification API #

ZendeskPushResponsibility #

SDK Lifecycle #

// Check if SDK is initialized
final isInit = await ZendeskMessaging.isInitialized();

// Invalidate SDK instance (cleanup)
await ZendeskMessaging.invalidate();
// After invalidate, you must call initialize() again to use the SDK

API Reference #

ZendeskMessaging #

Streams #

Models #

ZendeskUser

class ZendeskUser {
  String? id;
  String? externalId;
  ZendeskAuthenticationType authenticationType;
}

ZendeskLoginResponse

class ZendeskLoginResponse {
  String? id;
  String? externalId;
}

ZendeskMessage

class ZendeskMessage {
  String id;
  String conversationId;
  String? authorId;
  String? content;
  DateTime? timestamp;
}

Enums #

ZendeskAuthenticationType

• anonymous
• jwt

ZendeskConnectionStatus

• connected
• connectedRealtime
• connectingRealtime
• disconnected
• unknown

ZendeskPushResponsibility

• messagingShouldDisplay
• messagingShouldNotDisplay
• notFromMessaging
• unknown

Migration from 2.x #

Breaking Changes in 3.0.0 #

1. iOS 14.0 minimum - Apps targeting iOS 12/13 must upgrade
2. Dart 3.6+ required - Update your SDK constraint
3. Flutter 3.24+ required - Update your Flutter SDK
4. New event API - Use sealed class pattern for type-safe event handling

Migration Steps #

1. Update pubspec.yaml:

environment:
  sdk: ^3.6.0
  flutter: ">=3.27.0"

2. Update iOS Podfile:

platform :ios, '14.0'

3. Update event handling (optional but recommended):

// Old way (still works)
ZendeskMessaging.unreadMessagesCountStream.listen((count) {
  print('Unread: $count');
});

// New way (recommended)
ZendeskMessaging.eventStream.listen((event) {
  if (event is UnreadMessageCountChanged) {
    print('Unread: ${event.totalUnreadCount}');
  }
});

Troubleshooting #

iOS Build Fails #

Ensure your Podfile has the correct platform version:

platform :ios, '14.0'

Then run:

cd ios && pod install --repo-update

Android Build Fails #

Ensure the Zendesk Maven repository is added:

maven { url 'https://zendesk.jfrog.io/artifactory/repo' }

Events Not Received #

Make sure to call listenUnreadMessages() after initialization:

await ZendeskMessaging.initialize(...);
await ZendeskMessaging.listenUnreadMessages();

SDK Versions #

License #

MIT License - see LICENSE for details.

Contributing #

Contributions are welcome! Please read the contributing guidelines before submitting a pull request.

Links #

• GitHub Repository
• Zendesk Android SDK Docs
• Zendesk iOS SDK Docs
• Working with Messaging for Mobile Channels