gtateth_flutter_sdk

Native Flutter SDK and UI components for integrating g-tateth chat on mobile.

0.1.10 Executive Summary

The Flutter SDK now supports full in-app chat widget customization on mobile with web-style behavior parity, built-in persistence, chatbot assistant naming, and host app back-navigation hooks.

  • Tenants can open a settings page from a gear icon inside chat.
  • They can customize Appearance, Behavior, and Chatbot settings directly on mobile.
  • Saved changes persist across refresh and app restart by default.
  • Mobile now follows web logic for greeting priority, typing indicator behavior, offline messaging, and status indicator behavior.
  • Chatbot assistant display names can be configured and synced from tenant settings.
  • Host apps can provide a custom back action and label for embedded support screens.

Features

  • Typed client for /api/widget/* endpoints
  • Session initialization and token handling
  • Send/fetch messages
  • Online agents and settings fetch
  • Conversation lifecycle helpers
  • Socket.IO realtime support
  • Ready-to-use native Flutter chat widget
  • Chat widget settings for tenant-level customization
  • Automatic tenant settings sync from /api/widget/settings

Install

Add to your app pubspec.yaml:

dependencies:
  gtateth_flutter_sdk: ^0.1.10

For local development in this monorepo, you can still use a path dependency:

dependencies:
  gtateth_flutter_sdk:
    path: ../sdks/flutter

Quick Start

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Support')),
      body: Padding(
        padding: const EdgeInsets.only(bottom: 20.0),
        child: GtatethChatWidget(
          config: const WidgetClientConfig(
            baseUrl: 'https://api.g-tateth.com',
            tenantDomain: 'your-domain',
          ),
          customer: ChatCustomer(
            firstName: currentUser.firstName,
            lastName:  currentUser.lastName,
            email: currentUser.email,
          ),
        ),
      ),
    );
  }
}

Chat Widget Settings

By default, GtatethChatWidget loads tenant widget settings from the backend and applies them automatically at runtime.

This means you can customize the mobile chat widget from your admin/settings panel without rebuilding the app.

Use ChatWidgetSettings to customize SDK chat UI behavior per tenant/app:

const settings = ChatWidgetSettings(
  title: 'Support Chat',
  emptyStateText: 'Welcome! How can we help?',
  messageInputHintText: 'Type your question',
  showConnectionIndicator: true,
  showAgentNames: true,
  showErrorBanner: true,
  showTypingIndicator: true,
  chatbotEnabled: true,
  chatbotAssistantName: 'AI Assistant',
  chatbotGreetingMessage: 'Hi, I am your AI assistant.',
  chatbotShowsOnline: true,
  offlineMessage: 'We are currently offline. Please leave a message.',
  messageMaxWidth: 360,
  composerMinLines: 1,
  composerMaxLines: 6,
);

If you want to use only local hardcoded settings and skip server-driven customization:

GtatethChatWidget(
  config: const WidgetClientConfig(
    baseUrl: 'https://api.g-tateth.com',
    tenantDomain: 'your-domain',
  ),
  useTenantSettings: false,
  settings: const ChatWidgetSettings(
    title: 'Support Chat',
  ),
)

To let users/admins customize directly on mobile from the chat header, enable in-app customization:

GtatethChatWidget(
  config: const WidgetClientConfig(
    baseUrl: 'https://api.g-tateth.com',
    tenantDomain: 'your-domain',
  ),
  allowInAppCustomization: true,
  persistInAppCustomization: true, // default true
  onThemeChanged: (theme) {
    // Optional: persist to storage/backend
  },
  onSettingsChanged: (settings) {
    // Optional: persist to storage/backend
  },
)

When enabled, the settings icon in the chat header opens a dedicated mobile Chat Widget Settings page where tenants can edit:

  • Appearance: header/background/bubble/border/input colors
  • Behavior: title, empty state, input hint, indicators, offline message, message width
  • Chatbot: chatbot enable toggle, assistant name, greeting message, and chatbot online status

Behavior parity with web settings:

  • If chatbot is enabled, greeting priority is chatbot.greetingMessage, then behavior.greetingMessage.
  • behavior.showTypingIndicator controls typing events from composer input.
  • availability.showAvailabilityStatus controls the connection dot visibility.
  • chatbot.advanced.chatbotShowsOnline can keep the indicator online when chatbot is active.

Persistence behavior:

  • In-app changes are now saved locally by default and restored after app restart/refresh.
  • You can disable this with persistInAppCustomization: false.
  • You can isolate saved settings per app/screen with customizationStorageKey.
  • Load priority is: local widget defaults -> tenant settings (useTenantSettings) -> local persisted customization.

Low-level API usage

final client = WidgetClient(
  config: const WidgetClientConfig(
    baseUrl: 'https://api.g-tateth.com',
    tenantId: 'YOUR_TENANT_ID',
  ),
);

final session = await client.initSession(sessionId: 'device-session-123');
final messages = await client.getMessages(
  conversationId: session.conversationId,
  bearerToken: session.token,
);

await client.sendMessage(
  conversationId: session.conversationId,
  text: 'Hello from Flutter',
  bearerToken: session.token,
);

Realtime example

final realtime = WidgetRealtimeClient(
  RealtimeConfig(
    baseUrl: 'https://api.g-tateth.com',
    token: session.token,
    conversationId: session.conversationId,
  ),
);

await realtime.connect();
realtime.messages.listen((message) {
  debugPrint('new-message: ${message.text}');
});

Notes

  • baseUrl should point to your backend API host, for example https://api.g-tateth.com.
  • If your backend identifies tenants by domain, provide tenantDomain; otherwise use tenantId.
  • The SDK is designed to work with the existing widget backend endpoints in this repository.
  • customer should be the signed-in end user in the client app (not your support agent record).

Local Testing

Use this SDK from your own Flutter app and point it to your local backend.

  1. Set:
  • baseUrl to your local API URL
  • tenantDomain (or tenantId) to a valid tenant
  1. Run your app on emulator/device and verify:
  • App loads chat UI
  • Session initializes
  • You can send a message
  • Incoming agent/chatbot message appears in real-time

Libraries

gtateth_flutter_sdk