SDK · Stable

Flutter / Dart SDK

v0.1.0 · Stable

Official Flutter & Dart SDK for FluxChat. Drop an AI assistant into any mobile, desktop, or Dart web app in minutes — typed API client, a floating FAB widget, and a full-screen chat page, all built on Material 3.

View on GitHub pub.dev

Installation

Requires Flutter ≥ 3.16 and Dart ≥ 3.0.

From GitHub (v0.1.0)

pubspec.yaml

dependencies:
  fluxchat_sdk:
    git:
      url: https://github.com/benflux-company/fluxchat-sdk.git
      path: sdk/dart
      ref: sdk/dart/v0.1.0

terminal

flutter pub get

From pub.dev (coming soon)

terminal

flutter pub add fluxchat_sdk

Quickstart

Core SDK (pure Dart)

main.dart

import 'package:fluxchat_sdk/fluxchat_sdk.dart';

final fluxchat = FluxChat(apiKey: 'fc_live_your_key');

final res = await fluxchat.ask(AskOptions(
  message: 'What are your opening hours?',
));
print(res.reply);
print(res.conversationId); // persist for follow-up turns

FAB widget — floating bubble over the whole app

main.dart

import 'package:fluxchat_sdk/widget.dart';

MaterialApp(
  // The FAB floats above every route automatically — zero per-screen setup.
  builder: FluxChatOverlay.builder(
    options: FluxChatOptions(
      apiKey: 'fc_live_your_key',
      assistantName: 'Léa',
      clientName: 'Acme Bank',
    ),
  ),
  home: const MyHomePage(),
)

Authentication

All requests require an apiKey. For Knowledge Base write operations (create, update, delete) you also need a jwtToken. The client handles both automatically once configured.

dart

// API key only (read + Ask)
final client = FluxChat(apiKey: Platform.environment['FLUXCHAT_API_KEY']!);

// API key + JWT (read + Ask + KB write)
final adminClient = FluxChat(
  apiKey: Platform.environment['FLUXCHAT_API_KEY']!,
  jwtToken: Platform.environment['FLUXCHAT_JWT']!,
);

Ask (chat)

Send a message and get an answer grounded on your knowledge base.

dart

final res = await fluxchat.ask(AskOptions(
  message: 'How do I reset my password?',
  // Optional: keep conversation state across multiple turns
  conversationId: previousRes?.conversationId,
  sessionId: 'session-user-42',
));

print(res.reply);
print(res.conversationId); // save this for follow-up messages

Per-request context

Mobile replacement for window.fluxchatContext. Pass live user data (name, plan, current screen, cart…) so the assistant always answers with full context — without the widget needing to know about your state management.

dart

FluxChatOverlay.builder(
  options: FluxChatOptions(
    apiKey: 'fc_live_your_key',
    assistantName: 'Léa',
    // Called before every message — always fresh
    contextBuilder: () => jsonEncode({
      'user':    currentUser.name,
      'plan':    currentUser.plan,
      'screen':  currentRoute,
      'balance': accountBalance,
    }),
  ),
)

Flutter widgets

Three independent integration modes built on the same FluxChatController. Pick the one that fits your UX — all share the same options and state.

Widget	When to use
FluxChatOverlay	Recommended — wraps MaterialApp.builder; FAB floats above all routes
FluxChatFab	Manual Stack placement — drop the FAB wherever you want in a single screen
FluxChatPage	Full-screen chat navigated to as a regular route (push/pop)

FluxChatOverlay (Option A — recommended)

Wraps MaterialApp.builder. The FAB + chat panel float above every route automatically — no per-screen setup needed.

main.dart

import 'package:flutter/material.dart';
import 'package:fluxchat_sdk/widget.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      builder: FluxChatOverlay.builder(
        options: FluxChatOptions(
          apiKey: 'fc_live_your_key',
          assistantName: 'Léa',
          clientName: 'Acme Bank',
          primaryColor: const Color(0xFF4F46E5),
          contextBuilder: () => 'User is signed in.',
        ),
      ),
      home: const HomeScreen(),
    );
  }
}

FluxChatFab (Option B — manual placement)

Drop the FAB widget into any Stack for per-screen control.

dart

import 'package:fluxchat_sdk/widget.dart';

Scaffold(
  body: Stack(
    children: [
      const MyContent(),
      FluxChatFab(
        options: FluxChatOptions(
          apiKey: 'fc_live_your_key',
          assistantName: 'Léa',
        ),
      ),
    ],
  ),
)

FluxChatPage (Option C — full-screen route)

Navigate to a full-screen chat experience as a regular route.

dart

import 'package:fluxchat_sdk/widget.dart';

// From any widget:
Navigator.push(context, MaterialPageRoute(
  builder: (_) => FluxChatPage(
    options: FluxChatOptions(
      apiKey: 'fc_live_your_key',
      assistantName: 'Léa',
      clientName: 'Acme Bank',
    ),
  ),
));

FluxChatController

A ChangeNotifier that drives the widget programmatically — open, close, send messages, and clear history from a button, a deep link, or a push notification.

dart

import 'package:fluxchat_sdk/widget.dart';

// Create once, share everywhere
final controller = FluxChatController();

// Inject into the widget
FluxChatOverlay.builder(
  options: FluxChatOptions(apiKey: 'fc_live_your_key'),
  controller: controller,
)

// Drive from anywhere
ElevatedButton(
  onPressed: () {
    controller.open();
    controller.sendMessage('Hi! I need help with my order.');
  },
  child: const Text('Chat with us'),
)

// Clean up
@override
void dispose() {
  controller.dispose();
  super.dispose();
}

Knowledge base

Full CRUD for knowledge articles. Requires a jwtToken in the client.

dart

final client = FluxChat(
  apiKey: 'fc_live_your_key',
  jwtToken: 'eyJhbGci...',
);

// List all articles
final articles = await client.knowledge.list();

// Create
final article = await client.knowledge.create(KnowledgeArticle(
  title: 'Return policy',
  content: 'Items can be returned within 30 days of purchase.',
  category: 'support',
));

// Partial update
await client.knowledge.update(article.id, KnowledgeArticle(
  title: 'Return policy v2',
));

// Delete
await client.knowledge.delete(article.id);

Error handling

All errors are typed. Catch the base class or the specific subtype.

dart

import 'package:fluxchat_sdk/fluxchat_sdk.dart';

try {
  final res = await fluxchat.ask(AskOptions(message: 'Hello'));
  print(res.reply);
} on FluxChatApiException catch (e) {
  // 4xx / 5xx from the FluxChat API
  print('API error ${e.statusCode}: ${e.message}');
} on FluxChatNetworkException catch (e) {
  // Connectivity issues, timeouts
  print('Network error: ${e.message}');
} on FluxChatConfigException catch (e) {
  // Missing or invalid API key
  print('Config error: ${e.message}');
} on FluxChatException catch (e) {
  // All other FluxChat errors
  print('FluxChat error: ${e.message}');
}

FluxChatOptions reference

Option	Type	Description
apiKey	String	Required. Your FluxChat API key.
assistantName	String?	Display name for the bot in the widget header.
clientName	String?	Your app / brand name shown in the widget.
primaryColor	Color?	Accent colour for the FAB, header, and sent bubbles.
contextBuilder	String Function()?	Called before every send — returns live user/page data.
baseUrl	String?	Override the API base URL (default: https://dev-api.fluxchat-corp.com/api/v2).
connectTimeout	Duration?	Connection timeout (default: 10s).
receiveTimeout	Duration?	Response timeout (default: 30s).

SDK Author

@baruka99cloud-debug

Designed and built the Flutter / Dart SDK for FluxChat.