Zukko Chat Flutter SDK

A native Flutter chat screen for Zukko Chat. Drop in one widget and your users can talk to your support team or AI agent in real time, with text, photos, files and voice messages. iOS and Android.

Styles

Pick a look with ZukkoChatOptions.style. Each style has light and dark variants.

Smooth Silk

Tonal bubbles that blend into the background, floating composer (default).

Full-quality video

class SmoothSilkScreen extends StatelessWidget {
  const SmoothSilkScreen({super.key, required this.user});

  final ZukkoChatUser user; // from your login, see "User identity"

  @override
  Widget build(BuildContext context) {
    return ZukkoChat(
      title: 'Support',
      options: ZukkoChatOptions(
        baseUrl: const String.fromEnvironment('ZUKKO_BASE_URL'),
        websiteToken: const String.fromEnvironment('ZUKKO_WEBSITE_TOKEN'),
        style: ZukkoChatStyle.smoothSilk,
        l10n: ZukkoChatL10n.uzLatn,
        user: user,
        theme: ZukkoChatTheme(brightness: Theme.of(context).brightness),
      ),
      interactions: ZukkoChatInteractions(onMorePressed: () {}),
    );
  }
}

Minimal Clean

Agent replies as plain text, only the user's messages in bubbles.

Full-quality video

class MinimalCleanScreen extends StatelessWidget {
  const MinimalCleanScreen({super.key, required this.user});

  final ZukkoChatUser user; // from your login, see "User identity"

  @override
  Widget build(BuildContext context) {
    return ZukkoChat(
      title: 'Support',
      options: ZukkoChatOptions(
        baseUrl: const String.fromEnvironment('ZUKKO_BASE_URL'),
        websiteToken: const String.fromEnvironment('ZUKKO_WEBSITE_TOKEN'),
        style: ZukkoChatStyle.minimalClean,
        l10n: ZukkoChatL10n.uzLatn,
        user: user,
        theme: ZukkoChatTheme(brightness: Theme.of(context).brightness),
      ),
      interactions: ZukkoChatInteractions(onMorePressed: () {}),
    );
  }
}

Thread Feed

Full-width rows with avatar and name, no bubbles.

Full-quality video

class ThreadFeedScreen extends StatelessWidget {
  const ThreadFeedScreen({super.key, required this.user});

  final ZukkoChatUser user; // from your login, see "User identity"

  @override
  Widget build(BuildContext context) {
    return ZukkoChat(
      title: 'Support',
      options: ZukkoChatOptions(
        baseUrl: const String.fromEnvironment('ZUKKO_BASE_URL'),
        websiteToken: const String.fromEnvironment('ZUKKO_WEBSITE_TOKEN'),
        style: ZukkoChatStyle.threadFeed,
        l10n: ZukkoChatL10n.uzLatn,
        user: user,
        theme: ZukkoChatTheme(brightness: Theme.of(context).brightness),
      ),
      interactions: ZukkoChatInteractions(onMorePressed: () {}),
    );
  }
}

Features

• One widget (ZukkoChat) or a headless client (ZukkoChatClient) if you build your own UI.
• Three looks, each with light and dark variants: smoothSilk (default), minimalClean, threadFeed.
• Real-time messages, typing indicator, online status, connection banner, automatic reconnect with missed-message catch-up.
• Attachments (photos, files) and hold-to-record voice messages.
• Markdown in agent and AI replies (the visitor's own messages stay plain text).
• Link previews (optional).
• Secure user identity (HMAC) so a user keeps the same history on every device.
• Encrypted on-device cache of the session and the newest 20 messages (optional).
• Localization: English, Russian, Uzbek (Latin and Cyrillic), Turkish, Karakalpak.
• No storage or media permissions: the system pickers are used.

Contents

1. Styles
2. Requirements
3. Installation
4. Platform setup
5. Get your baseUrl and websiteToken
6. Quick start
7. User identity (HMAC)
8. Logout
9. Configuration reference
10. Callbacks and errors
11. Behavior details
12. Headless client
13. Troubleshooting / FAQ
14. Example app
15. License

Requirements

Installation

Add the package:

dependencies:
  zukko_chat_flutter: ^1.0.0

flutter pub get

(For local testing a path: dependency pointing at a checkout of this repository works too.)

import 'package:zukko_chat_flutter/zukko_chat_flutter.dart';

Platform setup

Android

Open android/app/src/main/AndroidManifest.xml and add, inside <manifest>:

<uses-permission android:name="android.permission.INTERNET"/>
<!-- Only if you keep voice messages enabled (enableVoiceMessages: true). -->
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

The microphone permission is requested at runtime by the system the first time the user records.

iOS

1. In ios/Podfile make sure the platform is at least 15.0:

   platform :ios, '15.0'
   

2. In ios/Runner/Info.plist add the microphone usage text (only needed when voice messages are enabled; without it iOS terminates the app when recording starts):

   <key>NSMicrophoneUsageDescription</key>
   <string>Record voice messages in chat.</string>
   

3. Run cd ios && pod install (or just flutter run).

No storage permissions

The SDK never needs READ_MEDIA_* or READ/WRITE_EXTERNAL_STORAGE. Photos and files are chosen through the system pickers.

If you do not use voice messages, set enableVoiceMessages: false and skip the microphone entries.

Get your baseUrl and websiteToken

1. Open the Zukko Chat admin panel.
2. Go to Settings, then Inboxes, then your website inbox, then Configuration.
3. The web widget snippet shown there contains both values: websiteToken and BASE_URL.

Rules:

• baseUrl must be https://.... Plain http, even for localhost, is rejected (an ArgumentError is thrown).
• websiteToken is public. It identifies the inbox and is not a secret.

Keep both outside your source with --dart-define:

flutter run \
  --dart-define=ZUKKO_BASE_URL=https://chat.example.com \
  --dart-define=ZUKKO_WEBSITE_TOKEN=your-website-token

const baseUrl = String.fromEnvironment('ZUKKO_BASE_URL');
const websiteToken = String.fromEnvironment('ZUKKO_WEBSITE_TOKEN');

Quick start

Minimal, anonymous visitor:

import 'package:flutter/material.dart';
import 'package:zukko_chat_flutter/zukko_chat_flutter.dart';

void openSupport(BuildContext context) {
  Navigator.of(context).push(
    MaterialPageRoute<void>(
      builder: (_) => const ZukkoChat(
        options: ZukkoChatOptions(
          baseUrl: 'https://chat.example.com',
          websiteToken: 'your-website-token',
        ),
      ),
    ),
  );
}

ZukkoChat is a full-screen page. It creates the client, connects, loads history and disposes everything when it leaves the tree. A back button is shown automatically when the page can be popped.

Full example with every parameter:

import 'package:flutter/material.dart';
import 'package:intl/intl.dart';
import 'package:zukko_chat_flutter/zukko_chat_flutter.dart';

const baseUrl = String.fromEnvironment('ZUKKO_BASE_URL');
const websiteToken = String.fromEnvironment('ZUKKO_WEBSITE_TOKEN');

Widget buildChat({required String userId, required String userHash}) {
  return ZukkoChat(
    title: 'Support', // header title; default is the localized "Support"
    options: ZukkoChatOptions(
      baseUrl: baseUrl, // https only
      websiteToken: websiteToken, // inbox token (public)
      enablePersistence: true, // encrypted on-device cache; false = memory only
      user: ZukkoChatUser(
        identifier: userId, // stable and unique per user in your system
        identifierHash: userHash, // HMAC computed by YOUR backend
        name: 'Aziz Karimov',
        email: 'aziz@example.com',
        phoneNumber: '+998901234567', // E.164
        avatarUrl: 'https://example.com/avatars/aziz.png',
        customAttributes: {'plan': 'pro'},
      ),
      style: ZukkoChatStyle.smoothSilk, // smoothSilk | minimalClean | threadFeed
      theme: const ZukkoChatTheme(
        brightness: Brightness.light, // light or dark variant
        accentColor: Color(0xFF0A7AFF), // send button, links
        horizontalPadding: 16,
      ),
      l10n: ZukkoChatL10n.uzLatn, // omit to follow the app locale
      timeFormat: DateFormat.Hm(), // message time format
      enableAttachments: true, // photo / file button
      enableVoiceMessages: true, // hold-to-record microphone
      enableLinkPreviews: true, // fetch preview cards for links
    ),
    callbacks: ZukkoChatCallbacks(
      onError: (e) => debugPrint('chat error: ${e.type.wire} ${e.cause}'),
      onMessageReceived: (m) => debugPrint('new message from an agent'),
      onConnectionStateChanged: (s) => debugPrint('connection: $s'),
    ),
    interactions: ZukkoChatInteractions(
      onMessageTap: (message) {},
      onSendPressed: (text) {},
      onMorePressed: () {}, // shows the header menu button
    ),
  );
}

User identity (HMAC)

[zukko_chat] ERROR: Identity validation is enabled for this inbox, but identifierHash is missing for user.identifier. Compute HMAC-SHA256(<inbox HMAC token>, identifier) on your backend and pass it as ZukkoChatUser.identifierHash.

printf '%s' 'user-42' | openssl dgst -sha256 -hmac 'YOUR_HMAC_TOKEN'

Without a user the visitor is anonymous. To tie the chat to one of your users, pass a ZukkoChatUser:

identifierHash and customAttributes are never written to the device.

Why the hash matters

1. It proves the user is who they say. Without it anyone could send someone else's identifier, appear as that customer to agents and the AI, and overwrite their name, email and phone.
2. With a verified identity the same user sees the same history on a new phone, after reinstall, and after logout then login. Without a hash each device starts with an empty conversation.

How to produce it

1. Find the HMAC token: Zukko Chat admin, Settings, Inboxes, your inbox, Configuration, "Identity validation".
2. Compute HMAC-SHA256(hmacToken, identifier) as a hex string on your backend. The HMAC token must never be shipped in the app or fetched by it.
3. Return the hash to the app with your login response and pass it as identifierHash.

Node.js:

const crypto = require('crypto');
const hash = crypto.createHmac('sha256', process.env.ZUKKO_HMAC_TOKEN)
  .update(String(user.id)).digest('hex');

Python:

import hmac, hashlib
h = hmac.new(HMAC_TOKEN.encode(), str(user.id).encode(), hashlib.sha256).hexdigest()

PHP:

$hash = hash_hmac('sha256', (string) $user->id, $hmacToken);

Quick check from a terminal:

printf '%s' 'user-42' | openssl dgst -sha256 -hmac 'YOUR_HMAC_TOKEN'

"Enforce identity validation" setting

Session token

The SDK obtains the session token (JWT) itself and keeps it encrypted in the local database; the encryption key lives in the iOS Keychain / Android Keystore. Your app never handles or sees it.

Logout

When your user logs out:

1. Close the chat (pop the ZukkoChat page, or call dispose() on a headless client).
2. Forget the user's local data:

await zukkoChatSignOut(
  baseUrl: baseUrl,
  websiteToken: websiteToken,
  user: currentUser, // the same ZukkoChatUser passed to the chat
);

This removes the cached session, conversation and messages of that identifier, whatever hash it was stored with. Other users and inboxes are untouched. After the next login with a correct hash the user gets the server-side history back.

If the chat was ever opened without a user (anonymous), wipe everything instead:

await ZukkoChatClient.clearAllData();

Both can be called before any chat was created.

Configuration reference

ZukkoChat

ZukkoChatOptions

If options changes with the same baseUrl, websiteToken, enablePersistence and user, the running connection is kept; changing any of those starts a new client.

ZukkoChatTheme

If options.theme is null, the theme registered in ThemeData.extensions is used, else one derived from the ambient ThemeData (so dark mode follows your app).

Helpers: ZukkoChatTheme.fromColorScheme(scheme), ZukkoChatTheme.fromThemeData(theme).

ZukkoChatInteractions

Localization

Built in: ZukkoChatL10n (English, the default), ZukkoChatL10n.ru, .uzLatn, .uzCyrl, .tr, .kaa (Karakalpak). ZukkoChatL10n.forLocale(locale) picks one (Uzbek is Latin unless the locale script is Cyrl). Leave l10n null to follow the app locale automatically, or pass one explicitly. Every text of the UI is a field of ZukkoChatL10n, so you can build your own with the constructor.

Limits (ZukkoChatUpload)

The UI shows a localized message when a limit is hit.

Callbacks and errors

ZukkoChatCallbacks

All optional. A callback that throws never breaks the SDK.

Errors

ZukkoChatException has cause (human text, never secrets), type (ZukkoChatExceptionType), data (for a failed send: the message's echoId), and optional error / stackTrace. type.wire is a stable string code.

Behavior details

• History paging. On open the newest 20 messages are loaded; older pages load automatically as the user scrolls to the top. Only the newest 20 are cached on the device; older pages are kept in memory only and are fetched again on the next open. The app has nothing to do.
• Auto-scroll. A new message scrolls the list to the end when it is the user's own, or when the user is within about one screen of the end. A user reading far up history is not moved.
• Markdown. Agent and AI messages render Markdown; the visitor's own messages are always plain text.
• Connection banner. Offline and reconnecting states are shown in the chat; on reconnect the SDK refetches what was missed.
• Footer. The "Powered by zukko.ai" line under the composer is always shown and not configurable.
• Voice. The microphone button appears only when enableVoiceMessages is true and the inbox allows voice messages (audio_messaging_enabled is not false).
• Debug log. In debug builds the SDK prints lines prefixed [zukko_chat] at three levels: ERROR: (something you must fix, for example a wrong identity hash), WARNING: (recoverable) and plain info. Release builds print nothing. Tokens, JWTs and hashes are never logged.

Headless client

Use ZukkoChatClient to build your own UI or to react to messages without a screen.

final client = await ZukkoChatClient.create(
  baseUrl: baseUrl,
  websiteToken: websiteToken,
  user: user,
  enablePersistence: true,
  callbacks: ZukkoChatCallbacks(
    onMessageReceived: (m) => debugPrint('new message'),
    onError: (e) => debugPrint(e.toString()),
  ),
);

await client.loadMessages();
await client.sendMessage(content: 'Hello', echoId: 'tmp-1');
// ...
await client.dispose();

Troubleshooting / FAQ

The chat shows "Your account could not be verified". Identity validation is enforced on the inbox and identifierHash is missing or wrong. Compute HMAC-SHA256 of the exact identifier string with the inbox HMAC token on your backend, hex-encoded. The debug log says which one it is ("missing" or "wrong").

ArgumentError about baseUrl. Only https:// is accepted, including for local development. Use an https tunnel or certificate for a dev server.

The microphone button is missing. Either enableVoiceMessages is false, or voice messages are disabled for the inbox on the server (audio_messaging_enabled: false).

The app crashes (iOS) or recording fails when I tap the microphone. Add NSMicrophoneUsageDescription (iOS) and RECORD_AUDIO (Android), see Platform setup.

A user has no history on a new phone. Without a valid identifierHash each device is a separate visitor. Pass the hash from your backend.

The chat is empty after logout and login. Expected: zukkoChatSignOut removes the local cache. With a verified identity the history comes back from the server on the next login.

No debug output in release. By design, logging is debug-only.

I need to see what the SDK does. Run a debug build and filter the console for [zukko_chat].

Example app

A runnable app lives in example/: example/lib/main.dart and the live chat screen example/lib/live/live_chat_screen.dart. How to run it and where to get each value: example/README.md. On pub.dev see the "Example" tab.

cd example
flutter run \
  --dart-define=ZUKKO_BASE_URL=https://chat.example.com \
  --dart-define=ZUKKO_WEBSITE_TOKEN=your-website-token \
  --dart-define=ZUKKO_USER_ID=user-42 \
  --dart-define=ZUKKO_USER_HASH=hex-hmac-of-user-id

ZUKKO_USER_ID and ZUKKO_USER_HASH are optional; without them the visitor is anonymous.

License

MIT, see LICENSE.