> ## Documentation Index
> Fetch the complete documentation index at: https://docs.g-tateth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK

> Client-facing guide for integrating the g-tateth mobile chat SDK in Flutter apps.

The official Flutter SDK for integrating g-tateth chat into Android and iOS apps.

## Overview

With the Flutter SDK, clients can:

* Initialize a chat session from mobile
* Send and receive messages in real time
* Display a native chat UI component
* Reuse existing widget/chat backend APIs

## Prerequisites

* Flutter 3.19+ (Dart 3.3+)
* A `tenantDomain` provided by G-tateth for your integration
* Backend API URL (production: `https://api.g-tateth.com`)

> Note: G-tateth will provide your `tenantDomain` during integration setup.

## Installation

Add the package to your Flutter app:

```yaml theme={null}
dependencies:
  gtateth_flutter_sdk: ^0.1.10
```

If using a private/local package source, replace with your internal installation method.
Clients do not need to install websocket/http helpers manually for basic SDK usage.

## Quick Integration

Use the `tenantDomain` provided by g-tateth during onboarding. g-tateth will share this value with your team.

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:gtateth_flutter_sdk/gtateth_flutter_sdk.dart';

class SupportPage extends StatelessWidget {
  const SupportPage({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-tenant-domain.com',
          ),
          customer: ChatCustomer(
            firstName: currentUser.firstName,
            lastName: currentUser.lastName,
            email: currentUser.email,
          ),
        ),
      ),
    );
  }
}
```

## Full Integration Example

Use this pattern to open chat from your app and allow in-app customization:

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:gtateth_flutter_sdk/gtateth_flutter_sdk.dart';

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Support')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            Navigator.push(
              context,
              MaterialPageRoute(builder: (_) => const SupportPage()),
            );
          },
          child: const Text('Open Support'),
        ),
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Support Chat')),
      body: GtatethChatWidget(
        config: const WidgetClientConfig(
          baseUrl: 'https://api.g-tateth.com',
          tenantDomain: 'your-tenant-domain.com',
        ),
        customer: ChatCustomer(
          firstName: 'Jane',
          lastName: 'Doe',
          email: 'jane@example.com',
        ),
        allowInAppCustomization: true,
        persistInAppCustomization: true,
        onBackPressed: () => Navigator.pop(context),
        backButtonLabel: 'BACK',
      ),
    );
  }
}
```

## In-app Customization

By default, `GtatethChatWidget` fetches tenant widget settings from `/api/widget/settings` and applies them at runtime.

That lets you change mobile widget appearance/behavior from tenant settings without shipping a new app build.

Use `ChatWidgetSettings` to configure tenant-facing widget labels and UI behavior in-app:

```dart theme={null}
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,
);
```

Enable full in-app customization page on mobile:

```dart theme={null}
GtatethChatWidget(
  config: const WidgetClientConfig(
    baseUrl: 'https://api.g-tateth.com',
    tenantDomain: 'your-tenant-domain.com',
  ),
  allowInAppCustomization: true,
  persistInAppCustomization: true, // default true
)
```

When enabled, tenants can open a settings page from the chat header and customize:

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

Behavior parity with web:

* Greeting priority: `chatbot.greetingMessage` then `behavior.greetingMessage`
* `behavior.showTypingIndicator` controls typing emit behavior
* `availability.showAvailabilityStatus` controls connection indicator visibility
* `chatbot.advanced.chatbotShowsOnline` can keep status online while chatbot is active
* Chat UI now shows `Agent is typing...` and chatbot typing states in mobile

Persistence behavior:

* In-app mobile customizations are persisted locally by default
* Saved customizations are restored after refresh/restart
* Load priority: local defaults -> tenant settings -> persisted in-app customization
* When `useTenantSettings` is true, tenant `title` and chatbot assistant/greeting stay authoritative

To disable server-driven settings and keep local-only values:

```dart theme={null}
GtatethChatWidget(
  config: const WidgetClientConfig(
    baseUrl: 'https://api.g-tateth.com',
    tenantDomain: 'your-tenant-domain.com',
  ),
  useTenantSettings: false,
  settings: const ChatWidgetSettings(title: 'Support Chat'),
)
```

## Required Configuration

* `baseUrl`: your API host
  * Production: `https://api.g-tateth.com`
* `tenantDomain`: provided by G-tateth during onboarding

## Local Testing

For Android emulator testing:

* Use backend URL: `http://10.0.2.2:3001`
* Keep backend running on port `3001`
* Use the `tenantDomain` provided by G-tateth

## Production Checklist

Before shipping to clients:

1. Use HTTPS API URL only.
2. Confirm the provided `tenantDomain` is correct.
3. Verify chatbot and handoff behavior per tenant settings.
4. Test reconnect behavior on poor mobile networks.
5. Ensure support/ops teams can monitor chat events and errors.

## Troubleshooting

* `Tenant not found`
  * Verify the `tenantDomain` value provided by G-tateth.
* `Failed to fetch`
  * Confirm backend URL is reachable from device/emulator.
  * Emulator must use `10.0.2.2` for localhost backend.
* No bot response
  * Check tenant chatbot settings and plan/feature access.
  * Confirm backend logs for chatbot gating and realtime emissions.

## Support

* [Support Center](https://support.g-tateth.com)
* [API Reference](/api-reference)
* [Chat Widget Guide](/guides/chat-widget)
* [Python SDK](/sdks/python)
* [PHP SDK](/sdks/php)