Drop-in Flutter widgets for Chataptor — real-time, auto-translated customer support chat.

Chataptor is free, forever. Auto-translate customer conversations across 100+ languages and reach anyone, anywhere — no credit card, no trial. Create your account →

What you get

In practice

👤  Customer in Tokyo
     注文した商品がまだ届いていません
        ↓  auto-translated, in real time
🎧  Your agent reads
     "My order hasn't arrived yet."

🎧  Your agent replies in English
     "Sure, let me check your order."
        ↓  auto-translated, in real time
👤  Customer reads in Japanese
     もちろん、ご注文を確認します

Same chat. No language switching, no copy-paste, no Google Translate.

Contents

• Install
• Quickstart
• Theming
• Custom UI
• Testing
• Documentation

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

Install

dependencies:
  chataptor_flutter: ^0.2.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(),
)

English and Polish are bundled out of the box. 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.

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));
  });
}

Requirements

Documentation

License

MIT © 2026 Chataptor