Voximplant Kit Chat SDK for Flutter #

The Voximplant Kit Chat SDK allows you to add in-app messaging to your Flutter application with a ready-to-use user experience. Explore our documentation and learn how to add an interface into your app, customize colors and strings so that the messaging user interface looks natural. Enhance your user experience with push notifications, customer data, and other features.

Supported languages: English, Spanish, Portuguese, Russian.

[./screenshots/chat_screen_android.png] [./screenshots/chat_screen_ios.png]

Supported platforms #

Requirements #

• Flutter >= 3.29.0
• Dart SDK ^3.7.0
• Android: JDK 17, Android Gradle Plugin and Kotlin versions that support compileSdk 35 (AGP 8.6+, Kotlin 2.x are recommended)
• iOS: Xcode 15+, Swift 5.9+

Getting started #

To get started, register a Voximplant Kit account and configure a mobile channel:

• Create and set up a mobile channel - guide.
• Upload push notification certificates - guide.

Installation #

Add the dependency to your application's pubspec.yaml:

dependencies:
  voximplant_kit_chat: ^1.0.0

Then run:

flutter pub get

iOS setup #

Info.plist

The chat lets users attach photos from the camera and save images to the gallery.

To enable these actions, add NSCameraUsageDescription and NSPhotoLibraryAddUsageDescription entries to your application's Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required to take photos and attach them in chat</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Photo library access is required to save chat images</string>

Root view controller

openChat() pushes the chat view controller onto the application navigation stack, so the Flutter view controller must be embedded in a UINavigationController. See example/ios/Runner/SceneDelegate.swift for a reference setup.

Usage #

Initialization #

VoximplantKitChat is the main SDK class that provides access to its functionality. You should initialize it with your mobile channel credentials and the unique customer identifier before opening the chat.

import 'package:voximplant_kit_chat/voximplant_kit_chat.dart';

final kitChat = VoximplantKitChat();

await kitChat.initialize(
  region: '<account-region>',
  channelUuid: '<channel-uuid>',
  token: '<channel-token>',
  clientId: '<client-id>',
);

Authorization errors

Subscribe to the authorizationErrors stream to be notified if the credentials supplied to the initialize API are rejected.

These errors are intended for debugging and logging — avoid surfacing them directly to the end user:

kitChat.authorizationErrors.listen((error) {
  debugPrint('KitChat authorization error: $error');
});

Open the chat #

Once the VoximplantKitChat instance is initialized, open the chat:

await kitChat.openChat();

The chat opens as the topmost screen on both platforms.

Set client data #

Use the setClientData API to update the customer profile in the agent's workspace:

await kitChat.setClientData(const KitChatClientData(
  displayName: 'Jane Doe',
  email: 'jane@example.com',
  phone: '+15551234567',
  avatarUrl: 'https://example.com/avatar.png',
  language: 'en',
));

Push notifications #

Push notifications notify users about new incoming messages.

A complete push notification flow (token registration, foreground / background / terminated handling, deep linking) is implemented in the example project.

Setup

iOS

Add the remote-notification background mode capability in Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

Get and register a push token

To receive the push notifications for the new messages, you should register a push token to Voximplant Kit using the registerPushToken API. A push notification token should be obtained on the application side using any 3rd party plugin (for example firebase_messaging or push) that exposes the following required token types to the flutter API:

• Android: Firebase Cloud Messaging (FCM) tokens.
• iOS: APNs token encoded as a hex string.

Once you have a token, register it with the SDK:

await kitChat.registerPushToken(token);

To stop receiving push notifications:

await kitChat.unregisterPushToken(token);

Receive and handle push notifications

Android

To display chat notifications on Android 13+, declare the POST_NOTIFICATIONS permission in your AndroidManifest.xml:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

The user must grant this runtime permission for chat notifications to be shown.

The SDK provides the handlePushAndroid API that processes the push payload data and shows a new message notification. The notification contains a pending intent that allows to open the chat on the notification tap.

When the user taps the notification, Android application receives the intent with the voximplant://kitchat URI. The application can use this data to navigate to the chat screen.

Declare the following intent filter in the application manifest:

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <data android:host="kitchat" android:scheme="voximplant"/>
    </intent-filter>
</activity>

iOS

Push notifications are displayed by the operating system. To customize foreground presentation, set up a custom UNUserNotificationCenterDelegate (see example/ios/Runner/AppDelegate.swift).

Push notifications are displayed automatically by the operating system upon being received. To customize the notifications, use the native UNUserNotificationCenterDelegate API. The SDK also provides the isChatVisibleIos API that allows to determine whether the application is in the foreground state with the chat screen opened. This API may be used to prevent the new message notifications to be shown while the user is on the chat screen.

if (await VoximplantKitChat.isChatVisibleIos()) {
  // Skip showing the in-app notification banner.
}

Customization #

The SDK provides the applyCustomization API to customize colors, icons, and strings.

Android strings and icons are not part of KitChatCustomization. Override them through the host application resources — see the Android strings and Android icons tables below.

iOS custom icons should be added to the Images.xcassets of the host application. Reference each asset by its name through KitChatIconsIos.

const colorScheme = KitChatColorScheme(
  brand: Color(0xFF662EFF),
  brandContainer: Color(0xFFF2EEFF),
  …
);

const stringsIos = KitChatStringsIos(
  chatTitle: 'Chat',
  messagePlaceholder: 'Type a message…',
  sender: KitChatSenderStringsIos(
    agentDisplayName: 'Agent',
    botDisplayName: 'Bot',
  ),
  …
);

const iconsIos = KitChatIconsIos(
  senders: KitChatSenderIconsIos(agent: 'myAgentIcon', bot: 'myBotIcon'),
  actions: KitChatActionIconsIos(send: 'mySendIcon'),
  …
);

const customization = KitChatCustomization(
  colorScheme: colorScheme,
  stringsIos: stringsIos,
  iconsIos: iconsIos,
);

await kitChat.applyCustomization(customization);

Android strings #

Android strings are overridden through the application resources. Place a strings.xml file with the keys listed below in ./<app>/android/app/src/main/res/values/ (and the localized variants in values-<locale>/).

Android icons #

Android icons are overridden through drawable resources. Place an XML / vector drawable with the same name listed below into ./<app>/android/app/src/main/res/drawable/ to override the SDK default at build time.

Error handling #

All asynchronous methods may throw exceptions based on KitChatException:

try {
  await kitChat.setClientData(const KitChatClientData(displayName: 'Jane'));
} on KitChatConnectionRequiredException {
  // Retry once the device is back online.
} on KitChatException catch (error) {
  debugPrint('KitChat error: $error');
}

Example #

A complete example that demonstrates initialization, customization, push notifications and deep linking is available in example/lib/main.dart. To run it:

cd example
flutter pub get
flutter run

License #

Licensed under the Apache License, Version 2.0.