Flutter SDK

Kindly Chat SDK for Flutter — customer support chat widget for iOS and Android applications. Thin Flutter facade over the public Kindly iOS and Android SDKs.

The published package ships the native iOS xcframework and Android AAR inline, so consumer apps don't need to wire up Swift Package Manager or JitPack themselves.

Features

Customisable themes and colours

Authentication via JWT (callback-based)

Multi-language support

Real-time chat

Push notifications (APNS + FCM)

Trigger specific dialogues / deep-link URLs

Programmatic message send

Context attached to next message or button click

Native iOS and Android implementations bundled — no extra setup

Requirements

Flutter >= 3.0 (Dart >= 2.17)

iOS >= 17.2 (matches the bundled xcframework — older targets fail at launch with missing dyld symbols)

Android minSdk >= 21, plugin builds with compileSdk 35 (matches android-source)

Installation

Add kindly to your pubspec.yaml:

dependencies:
  kindly: ^3.0.26

Then flutter pub get.

Migrating from kindly_sdk? This package is the renamed successor to kindly_sdk. The public API is identical — only the package name changed. To migrate: bump the dep from kindly_sdk to kindly: ^3.0.26, and replace import 'package:kindly_sdk/kindly_sdk.dart' with import 'package:kindly/kindly.dart'. Nothing else needs to change.

iOS Setup

No additional setup required. The package vendors a signed KindlySDK.xcframework and CocoaPods links it automatically when Flutter runs pod install. (The framework is named KindlySDK rather than Kindly so it doesn't case-collide with the kindly pod on macOS's case-insensitive filesystem.) The podspec pulls in Sentry as its one external dependency, matching what the bundled binary imports.

Android Setup

No additional setup required. The package ships a kindlysdk.aar that Gradle picks up directly via implementation files("libs/kindlysdk.aar").

Note on manifest merger. The bundled AAR declares android:label="@string/app_name" on its <application> element. If your app's AndroidManifest.xml also sets android:label, Android's manifest merger fails with "Attribute application@label is also present at [kindlysdk.aar]". To resolve, add tools:replace="android:label" to your <application> tag (and declare xmlns:tools="http://schemas.android.com/tools" on the root <manifest> if not already):

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application
        android:label="My App"
        …
        tools:replace="android:label">
        …
    </application>
</manifest>

Usage

Basic Setup

import 'package:kindly/kindly.dart';

await KindlySDK.start(
  botKey: 'YOUR_BOT_KEY',
  market: 'general', // required — your market slug (Settings → General → Details & markets)
);

await KindlySDK.displayChat();

Authentication

await KindlySDK.start(
  botKey: 'YOUR_BOT_KEY',
  market: 'general',
  authTokenCallback: (chatId) async {
    // chatId is the backend-generated identifier for this chat session
    // (from /connect). Include it when calling your auth backend so the
    // JWT is scoped to this chat. Matches the Web / iOS / Android contract.
    final token = await yourAuthService.getToken(chatId: chatId);
    return token;
  },
);

Use authCredentialsCallback instead when your identity provider issues more than a single JWT: a companion access token, an issuer, or an opaque token whose expiry only you know.

await KindlySDK.start(
  botKey: 'YOUR_BOT_KEY',
  market: 'general',
  authCredentialsCallback: (chatId) async {
    final tokens = await yourAuthService.getTokens(chatId: chatId);
    return KindlyAuthCredentials(
      idToken: tokens.idToken,                // optional
      accessToken: tokens.accessToken,        // optional
      issuer: 'https://idp.example.com/',     // optional
      expiresAt: tokens.expiresAtUnixSeconds, // optional, Unix seconds
    );
  },
);

Every field is optional, but set at least one of idToken / accessToken. Either token alone is a valid credential: a provider that issues only an access token is normal and supported, and that access token becomes the bearer. Credentials carrying neither are refused and the chat stays anonymous. KindlyAuthCredentials.bearerToken tells you which token will be sent as Authorization: Bearer, idToken first.

An opaque token that nobody can decode goes in idToken with issuer set, so the backend knows which provider to introspect it against. The access token is only sent alongside an id token, as X-Access-Token, and only when the two differ. A duplicate would fail the auth outright.

A single-JWT integration never needs this callback. When both callbacks are given, authCredentialsCallback wins.

The SDK refreshes credentials on its own, 30 seconds before they expire, using whichever is earliest of the backend's reported expiry, your expiresAt, and the exp claim of the bearer. If none is known the credentials are treated as non-expiring, which is a trap for opaque tokens, so set expiresAt there.

When the identity changes rather than the token, tell the SDK:

await KindlySDK.authenticate();     // user signed in, or switched account
await KindlySDK.deauthenticate();   // user signed out

authenticate() re-binds fresh credentials to the chat that is already open, keeping the conversation. deauthenticate() unbinds the identity on the backend and clears the stored credentials; the chat carries on anonymously with its history intact, and calling it again when the chat is already anonymous does nothing.

Custom Theme

await KindlySDK.setCustomTheme(
  background: Colors.white,
  botMessageBackground: Colors.grey[200],
  botMessageText: Colors.black,
  userMessageBackground: Colors.blue,
  userMessageText: Colors.white,
  buttonBackground: Colors.blue,
  buttonText: Colors.white,
  navBarBackground: Colors.blue,
  navBarText: Colors.white,
  inputBackground: Colors.grey[100],
  inputText: Colors.black,
);

// Revert to default
await KindlySDK.clearCustomTheme();

Context Data

await KindlySDK.setNewContext({
  'userId': '12345',
  'userName': 'John Doe',
  'email': '[email protected]',
  'plan': 'premium',
});

await KindlySDK.clearNewContext();

Trigger Specific Dialogues

// Launch chat with a specific dialogue
await KindlySDK.launchChat(triggerDialogueId: 'welcome_dialogue');

// Or trigger a dialogue inside an active chat
await KindlySDK.triggerDialogue('help_dialogue');

// Clear any pending trigger (Android only)
await KindlySDK.clearTriggerDialogue();

Deep links

The SDK recognises kindly://chat/dialogue/{id} URLs.

final handled = await KindlySDK.handleUrl('kindly://chat/dialogue/welcome');

Programmatic Message Send

Send a message on behalf of the user. The SDK renders the bubble locally and reconciles the server-assigned id when the POST returns — do not also display the message yourself.

final reconciled = await KindlySDK.sendMessage(
  'Hello there',
  newContext: {'priority': 'high'},
);
print(reconciled?['id']); // server id

Handover to a Human Agent

Initiate a handover and receive a callback when the handover begins.

await KindlySDK.callHandover(() {
  print('Handover initiated');
});

Push Notifications

iOS

await KindlySDK.setAPNSDeviceToken(deviceToken);
await KindlySDK.handleNotification(notificationData);
final isKindly = await KindlySDK.isKindlyNotification(notificationData);

Android

await KindlySDK.saveNotificationToken(fcmToken);
await KindlySDK.handleNotification(remoteMessage.data);
final isKindly = await KindlySDK.isKindlyNotification(remoteMessage.data);

Other Features

// Check chat UI state (iOS only)
final isDisplayed = await KindlySDK.isChatDisplayed;

// Update language for the active session
await KindlySDK.setLanguage('no');

// Save a JWT to the platform keychain (iOS only)
await KindlySDK.saveAuthToken('jwt-here');

// Toggle SDK logging / Sentry crash reporting
await KindlySDK.setVerboseLogging(true);
await KindlySDK.setCrashReporting(true);

// Close UI without ending the session
await KindlySDK.closeChat();

// End the active session (clears messages + token, dismisses UI)
await KindlySDK.endChat();

// Tear the SDK down completely — must call start() again before reuse
await KindlySDK.kill();

API Reference

Lifecycle

start({botKey, market, languageCode?, authTokenCallback?, authCredentialsCallback?}) — initialise the SDK. First call before anything else. market is required (Markets feature); the SDK loads that market's settings with no fallback. Use authCredentialsCallback for identity providers that issue more than a single JWT.

displayChat({languageCode?, triggerDialogueId?}) — show the chat UI.

launchChat({triggerDialogueId?}) — connect (if needed) and show the chat UI. Recommended on Android; routed to displayChat on iOS.

closeChat() — dismiss the UI without ending the session.

endChat() — end the active session, clear messages + token, dismiss UI.

kill() — fully tear down the SDK; start() must be called again before reuse.

setLanguage(languageCode) — change language for the current session.

Authentication

authenticate(): re-authenticate the live chat with fresh credentials, for a sign-in mid-session. Expiry is handled by the SDK on its own

deauthenticate(): sign out of the chat without ending it. History is kept and the chat continues anonymously

Messaging

sendMessage(text, {newContext?}) — send a message programmatically; resolves with {id, text, created, sender, ...}.

setNewContext(context) — stage Map<String, String> context for the next message or click.

clearNewContext() — clear staged context.

triggerDialogue(dialogueId) — trigger a dialogue by id (must be connected).

clearTriggerDialogue() — clear pending trigger (Android only).

handleUrl(url) — handle kindly://chat/dialogue/{id} deep links; returns bool.

callHandover(callback) — request handover to a human agent (Android only).

Theme

setCustomTheme({...colors}) — override individual theme slots (background, botMessageBackground, botMessageText, userMessageBackground, userMessageText, buttonBackground, buttonText, buttonOutline, buttonSelectedBackground, navBarBackground, navBarText, inputBackground, inputText, inputCursor, chatLogElements, defaultShadow, maintenanceHeaderBackground).

clearCustomTheme() — revert to the default / API theme.

Push

setAPNSDeviceToken(token) — register the APNS token (iOS only).

saveNotificationToken(token) — register the FCM token (Android only).

handleNotification(data) — forward a push to the SDK.

isKindlyNotification(data) — true if the push originated from Kindly.

State & settings

isChatDisplayed — Future<bool>; iOS only (Android always returns false — track via host UI state).

saveAuthToken(token) — persist a JWT to the platform keychain (iOS).

setVerboseLogging(bool) — toggle verbose logging.

setCrashReporting(bool) — toggle Sentry crash reporting.

License

This project is licensed under the MIT License — see the LICENSE file for details.