When to use Qiscus Multichannel Widget
The **Qiscus Multichannel Widget** brings a complete, production‑ready chat interface to any Flutter application with a single dependency. Powered by the Qiscus omnichannel platform, the widget handles real‑time messaging, file attachments, typing indicators, read receipts and agent routing out of the box. Its UI follows Material Design guidelines while remaining fully themeable, so developers can keep a consistent look across the rest of the app. By abstracting the low‑level socket handling and message persistence, the package lets you focus on business logic instead of building a chat client from scratch.
Use this widget when you need a reliable customer‑support or sales chat channel that works across multiple communication mediums—web, mobile, and desktop. It is especially valuable for e‑commerce stores, SaaS dashboards, and service‑oriented apps that want to boost conversion rates and loyalty through instant, in‑app conversations. The widget supports multiple channels (live chat, bot, and human agents) and can be instantiated multiple times, allowing you to embed separate support rooms for different product lines or user groups.
From an architectural standpoint, the widget lives in the presentation layer and communicates with the Qiscus backend through a thin Dart SDK that ships with the package. Because the widget does not enforce a specific state‑management solution, it can be paired with Provider, Riverpod, Bloc, GetX, or any custom architecture you prefer. The widget exposes streams for events such as `onMessageReceived`, `onAgentJoined`, and `onError`, making it straightforward to integrate with clean‑architecture or MVVM patterns. Its internal caching mechanism stores recent messages locally, reducing latency and enabling offline read‑only mode without additional code.
Getting started is simple. First, add the dependency with `flutter pub add qiscus_multichannel_widget`. Then, initialize the Qiscus client in your `main.dart` using your App ID and secret, and optionally configure a custom theme. After that, drop the `QiscusMultichannelWidget` into any screen, passing the required `channelId` and optional callbacks. Platform‑specific steps include adding internet permissions to AndroidManifest.xml and configuring App Transport Security for iOS if you use non‑HTTPS endpoints. The package also supports WebSocket fallback for browsers that block native sockets.
When moving to production, keep a few cautions in mind. The widget relies on a persistent WebSocket connection, so monitor network changes and gracefully handle reconnections. Use the provided `onError` callback to surface connectivity issues to users. For large chat histories, consider enabling server‑side pagination to avoid memory bloat; the widget’s `loadMore` method can fetch older messages on demand. Customize the theme sparingly to maintain performance, as excessive widget rebuilding can affect frame rates on low‑end devices. Finally, secure your Qiscus credentials by storing them on a backend and fetching short‑lived tokens at runtime rather than hard‑coding them.
A beginner‑friendly example is a single‑screen support chat. After initializing the Qiscus client, you create a `Scaffold` with an `AppBar` and place `QiscusMultichannelWidget(channelId: 'support')` in the body. The widget instantly shows the conversation, handles sending text and images, and updates the UI as agents reply. This minimal setup can be expanded with custom avatars, message bubbles, or integration with analytics events, giving you a solid foundation for a full‑featured support experience without writing a chat engine yourself.
Pros
- quick integration
- full‑featured UI out of the box
- cross‑platform support
- local message cache
- extensible event streams
Watch outs
- tied to Qiscus backend
- limited deep UI customization without fork
- requires server‑side token handling
Setup notes
1. Run `flutter pub add qiscus_multichannel_widget`. 2. Import the package: `import 'package:qiscus_multichannel_widget/qiscus_multichannel_widget.dart';` 3. Initialize the Qiscus client early, e.g., in `main()`: ```dart await Qiscus.init(appId: 'YOUR_APP_ID', secret: 'YOUR_SECRET'); ``` 4. Add required platform permissions: - Android: `<uses-permission android:name="android.permission.INTERNET"/>` in AndroidManifest.xml. - iOS: Ensure App Transport Security allows your endpoint or use HTTPS. 5. Insert `QiscusMultichannelWidget(channelId: 'your_channel')` into your widget tree. 6. (Optional) Provide a custom `QiscusTheme` to match your app’s branding.
Requires Flutter 3.0 or newer. Supports Android (API 21+), iOS 11+, Web, macOS, Linux and Windows. The package depends on `web_socket_channel` and `http` which are compatible with all Dart platforms. For Web, ensure the server supports WebSocket fallback. No native iOS/Android SDKs are required, but proper internet permissions are mandatory.
import 'package:flutter/material.dart';
import 'package:qiscus_multichannel_widget/qiscus_multichannel_widget.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Qiscus.init(appId: 'YOUR_APP_ID', secret: 'YOUR_SECRET');
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Support Chat',
theme: ThemeData.light(),
home: const SupportScreen(),
);
}
}
class SupportScreen extends StatelessWidget {
const SupportScreen({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Live Support')),
body: QiscusMultichannelWidget(
channelId: 'support',
onMessageSent: (msg) => debugPrint('Sent: ${msg.text}'),
onError: (e) => ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text('Error: $e')),
),
),
);
}
}