Chatasist Flutter

Native Flutter widget SDK for Chatasist chat with a simple initialize then present integration flow, fully powered by Chatasist Widget APIs.

Features

  • Native chat UI (chat list, thread, composer)
  • Session bootstrap with JWT persistence; optional server-minted JWT before first session
  • File/image/video/audio attachments (multipart to /api/widget/messages)
  • Realtime integration via Pusher (/api/widget/broadcasting/auth)
  • Voice/video call signaling support using WebRTC + widget call endpoints
  • In-thread CSAT survey flows (rating + feedback) aligned with the web widget
  • Rich HTML in widget surfaces via flutter_html; links opened with url_launcher
  • Home, messages, news, and help tabs with consistent layout tokens
  • Global plugin singleton + unread/incoming call notifiers

SDK and Platform Support

  • SDK: Flutter package
  • Platforms: Android, iOS, Web (host app support depends on your app/plugin stack)
  • Tested package baseline:
    • Flutter 3.35+
    • Dart 3.11+

Requirements

  • Flutter 3.35+
  • Backend endpoints under /api/widget/*
  • Required request header: X-Chatasist-Channel: {channel_uuid}
  • Optional identity support through /api/widget/session

Install

Add chatasist_flutter only; HTML and URL handling dependencies are pulled in transitively (you do not add flutter_html or url_launcher to your app unless you use them yourself).

From pub.dev (use the current version from the package page):

dependencies:
  chatasist_flutter: ^1.0.11

For local development:

dependencies:
  chatasist_flutter:
    path: ../chatasist-flutter

Quick start

By default the widget opens as a bottom card (sheet over a dimmed backdrop). Use presentation: ChatasistWidgetPresentation.fullscreen for a classic full-screen modal.

final navigatorKey = GlobalKey<NavigatorState>();

await chatasistFlutter.initialize(
  ChatasistWidgetOptions(
    baseUrl: 'https://chatasist.com',
    channelId: '00000000-0000-0000-0000-000000000001',
    language: 'en',
    navigatorKey: navigatorKey,
    // Optional: bind the first session to a server-minted customer JWT
    // initialSessionJwt: widgetJwtFromYourBackend,
    // Optional: ChatasistWidgetPresentation.fullscreen
  ),
);

await chatasistFlutter.setIdentity('visitor@example.com');
await chatasistFlutter.present();

Usage

Import package:chatasist_flutter/chatasist_flutter.dart and use the singleton:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final navigatorKey = GlobalKey<NavigatorState>();

  await chatasistFlutter.initialize(
    ChatasistWidgetOptions(
      baseUrl: 'https://chatasist.com',
      channelId: 'YOUR_WIDGET_CHANNEL_UUID',
      language: 'en',
      navigatorKey: navigatorKey,
    ),
  );

  runApp(MyApp(navigatorKey: navigatorKey));
}

ChatasistWidgetOptions

Field Required Description
baseUrl no Base URL of your Chatasist backend (widget APIs). Defaults to https://app.chatasist.com.
channelId yes Widget channel UUID (X-Chatasist-Channel).
language no Preferred language code for session bootstrap.
navigatorKey no Strongly recommended: root navigator used by present() / dismiss().
initialSessionJwt no Optional JWT from your backend (e.g. POST /api/v1/widget/session-jwt) so the first session binds to an API-created customer.
presentation no ChatasistWidgetPresentation.card (default) or .fullscreen.
debug no Verbose diagnostics for local debugging.

Common runtime actions

  • Initialize once at app startup.
  • Optionally set visitor identity with setIdentity.
  • After minting or rotating a widget JWT on the server, call setSessionJwt to persist it and reload session/chats.
  • Open the messenger with present(). Prefer a configured navigatorKey; otherwise pass a BuildContext with access to a Navigator (see API below).
  • When the user logs out of your app or you tear down the SDK, call dispose() to release listeners and internal state.

Android Setup

Ensure your Android app has required permissions for network, attachments, and call/media features.

Recommended permissions in AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Notes:

  • Keep AndroidX enabled in Gradle settings.
  • Confirm your app minSdk is compatible with transitive plugin requirements (especially media/WebRTC plugins).
  • Request runtime permissions where needed (camera, microphone, storage/media).

iOS Setup

Add usage descriptions in Info.plist for features your app enables:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for voice and video calls.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to attach media.</string>

Notes:

  • Ensure your iOS deployment target is compatible with dependency requirements.
  • Request permissions before launching related features.
  • If chat content opens non-https URL schemes, you may need to declare them under LSApplicationQueriesSchemes per url_launcher iOS documentation.

Push Notification Setup

This package handles in-app realtime via widget APIs/Pusher. For background push notifications, integrate native push infrastructure in the host app (for example firebase_messaging) and route notification taps into opening Chatasist.

Typical flow:

  1. Configure push notifications in your Flutter host app (firebase_messaging, APNS/FCM setup).
  2. Use your backend to deliver notification payloads for new widget messages/calls.
  3. On notification tap, call chatasistFlutter.present() to open the widget.

Current scope:

  • In-app realtime events are supported by this package.
  • Push token registration and push delivery orchestration are handled by your app/backend stack.

API

Plugin (chatasistFlutter)

  • Future<void> initialize(ChatasistWidgetOptions options)
  • Future<void> setIdentity(String? identity) — sets or clears visitor identity and reboots session state.
  • Future<void> setSessionJwt(String? jwt) — updates the stored widget JWT and reloads session/chats.
  • Future<void> present({BuildContext? context}) — presents the widget route. Uses navigatorKey from options when set; otherwise context (root navigator).
  • void dismiss() — pops the widget route when the navigator key allows it.
  • Future<void> refresh() — reloads session and chats from the backend.
  • Future<void> dispose() — disposes controller, realtime, and notifiers; call before dropping the plugin for the app lifetime.
  • unreadCount — ValueNotifier<int> for unread messages across chats.
  • hasIncomingCall — ValueNotifier<bool> for incoming call presence.

Types

  • ChatasistWidgetPresentation — card | fullscreen.

Backend endpoint mapping

  • POST /api/widget/session
  • GET /api/widget/chats
  • GET /api/widget/chats/{id}
  • POST /api/widget/messages
  • POST /api/widget/broadcasting/auth
  • POST /api/widget/chats/{chat}/calls/start
  • POST /api/widget/chats/{chat}/calls/{call}/answer
  • POST /api/widget/chats/{chat}/calls/{call}/ice
  • POST /api/widget/chats/{chat}/calls/{call}/end

Reference

  • Flutter package page structure inspiration: pub.dev

Libraries

chatasist_flutter
Public entrypoint for the Chatasist Flutter plugin package.