chataptor_flutter 0.1.0

Drop-in Flutter widgets for real-time, auto-translated customer support chat. Official Chataptor SDK with built-in theming, localization, and lifecycle. Free early access.

chataptor_flutter

Official Flutter widgets for Chataptor — real-time multilingual customer support chat with built-in auto-translation.

Early Adopter Program: 6 months free, dedicated support, and a price-lock guarantee after the free period. Check available spots →

This package provides the Chataptor singleton, ready-to-use chat widgets, theming, and localization. It re-exports the full chataptor core, so you only need this one dependency.

Install

dependencies:
  chataptor_flutter: ^0.1.0

flutter pub get

Quickstart

1. Initialise at app start

Call Chataptor.init once before runApp. Both siteId and widgetKey are found in the Chataptor admin console under Settings → API.

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Chataptor.init(
    siteId: 'your-site-id',
    widgetKey: 'pk_xxx',
  );

  runApp(const MyApp());
}

2. Add localization delegates

Wire ChataptorLocalizations into your MaterialApp:

MaterialApp(
  localizationsDelegates: const [
    ChataptorLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  supportedLocales: ChataptorLocalizations.supportedLocales,
  home: const HomeScreen(),
)

v0.1.0 ships English and Polish. Ten additional locales arrive in v0.5.0.

3. Open the chat screen

ChataptorChatScreen is a full-page widget. Push it with the standard Navigator:

Navigator.of(context).push(
  MaterialPageRoute(builder: (_) => const ChataptorChatScreen()),
);

The screen connects to Chataptor on mount and disconnects when popped — no lifecycle management required on your side.

Theming

ChataptorTheme controls all visual aspects of the chat UI. Two factory constructors cover the most common cases:

// Stand-alone defaults (purple accent, light backgrounds)
ChataptorTheme.light()

// Derives from the ambient Material theme — blends with your app automatically
ChataptorTheme.matching(context)

Override individual tokens via copyWith:

ChataptorTheme.light().copyWith(
  primaryColor: Colors.teal,
  bubbleRadius: const BorderRadius.all(Radius.circular(8)),
)

Pass the theme to ChataptorChatScreen:

ChataptorChatScreen(
  theme: ChataptorTheme.matching(context).copyWith(
    primaryColor: Theme.of(context).colorScheme.secondary,
  ),
)

Custom UI

For full control over the UI, use the core ChataptorClient directly. Access the process-wide instance via Chataptor.instance, or inject a specific client with ChataptorScope:

// Access the singleton
final client = Chataptor.instance;

// Or inject a specific client into a subtree
ChataptorScope(
  client: myClient,
  child: const MyChatWidget(),
)

Subscribe to streams directly:

final client = Chataptor.instance;

// Incoming messages
client.messages.listen((message) {
  setState(() => _messages.add(message));
});

// Connection state
client.connectionState.listen((state) {
  if (state is Connected) _setReady();
});

// Per-language site config (welcome message, team name, offline mode)
client.siteConfigStream.listen((config) {
  setState(() => _teamName = config.activeHeaderTitle('pl'));
});

// Live roster of currently-online agents (id, name, avatar URL, initials)
client.onlineAgentsStream.listen((agents) {
  setState(() => _onlineAgents = agents);
});

// Send
final result = await client.sendMessage('Hello!');

The drop-in ChataptorChatScreen already consumes these streams to render ChataptorChatHeader (avatar stack of online agents, team name from SiteConfig.activeHeaderTitle, live Online/Offline indicator) — matching the production web widget on chataptor.com sites. Headless integrations get the same data so a custom header can show the same presence info.

Testing

Inject a FakeChataptorClient via ChataptorScope to test your UI without a network connection:

import 'package:chataptor/chataptor.dart';
import 'package:chataptor/testing.dart';
import 'package:chataptor_flutter/chataptor_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('chat screen mounts with connected client', (tester) async {
    TestWidgetsFlutterBinding.ensureInitialized();

    final fake = FakeChataptorClient(
      initialConnectionState: const Connected(),
    );

    await tester.pumpWidget(
      ChataptorScope(
        client: fake,
        child: const MaterialApp(home: ChataptorChatScreen()),
      ),
    );

    expect(find.byType(ChataptorChatScreen), findsOneWidget);

    // Simulate a connection drop
    fake.inject.connectionState(
      const Disconnected(DisconnectReason.networkError),
    );
    await tester.pump(const Duration(milliseconds: 100));
  });
}

Use fake.inject to drive the client into any state, and fake.recorded to assert on what the UI sent.

Requirements

	Minimum
Flutter	3.35.0
Dart	3.9.0
iOS	12.0
Android	API 21

License

MIT © 2026 Chataptor