README.md

Integrate Chatwoot with Flutter app

Requirements for 0.1.0

• Dart 3.9 or newer and Flutter 3.35 or newer for consumers. The minimum-consumer check resolves without overrides and covers the public API and Hive upgrade. SDK development, generation and the checked-in lockfiles use Flutter 3.44.8.
• Android API 23 or newer, or the minimum required by your Flutter version, whichever is higher. Build with Java 17.
• iOS 13 or the higher minimum required by your Flutter version or Xcode SDK. Set the deployment target in your Podfile and Xcode project. For example, Xcode 27 requires iOS 15 targets; this does not validate iOS 13 behavior.

Migrating from 0.0.8

The official package is chatwoot_client_sdk, published by chatwoot.com. If you used a Git revision named chatwoot_sdk, update its dependency key and imports to chatwoot_client_sdk. Use the entry point package:chatwoot_client_sdk/chatwoot_client_sdk.dart.

Version 0.1.0 uses InAppWebView for the website widget's native file picker. If you used ChatwootWidget from an earlier Git revision, remove its onAttachFile argument. Apply the Android FileProvider and iOS permission settings below. File selection is handled by the native WebView.

The deprecated ChatwootChat, ChatwootChatDialog, ChatwootChatTheme, and ChatwootL10n classes have been removed. Use ChatwootWidget for the website channel, or build a custom UI around ChatwootClient for an API channel.

Hive has been replaced by Hive CE. The SDK keeps the existing box names and adapter IDs; test upgrades with existing persisted conversations. Android secure storage 10 migrates the previous encrypted preferences automatically by default. Do not clear existing app storage as part of an upgrade.

Integrate Chatwoot flutter client into your flutter app and talk to your visitors in real time. Chatwoot helps you to chat with your visitors and provide exceptional support in real time. To use Chatwoot in your flutter app, follow the steps described below.

1. Add the package to your project

Run the command below in your terminal

flutter pub add chatwoot_client_sdk

or

Add chatwoot_client_sdk:<<version>> to your project's pubspec.yml file. You can check here for the latest version.

2. How to use

a. Using ChatwootWidget

• Create a website channel in chatwoot server by following the steps described here https://www.chatwoot.com/docs/channels/website
• Replace websiteToken prop and baseUrl

import 'dart:io';

import 'package:chatwoot_client_sdk/chatwoot_client_sdk.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key key, this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("Chatwoot Example"),
      ),
      body: ChatwootWidget(
        websiteToken: "websiteToken",
        baseUrl: "https://app.chatwoot.com",
        user: ChatwootUser(
          identifier: "test@test.com",
          name: "Tester test",
          email: "test@test.com",
        ),
        locale: "fr",
        closeWidget: () {
          if (Platform.isAndroid) {
            SystemNavigator.pop();
          } else if (Platform.isIOS) {
            exit(0);
          }
        },
        onLoadStarted: () {
          print("loading widget");
        },
        onLoadProgress: (int progress) {
          print("loading... ${progress}");
        },
        onLoadCompleted: () {
          print("widget loaded");
        },
      ),
    );
  }
}

• To better support file attachments, for android define a FileProvider in AndroidManifest.xml under the <application> tag. Replace ${applicationId} with your application id

<provider
   android:name="androidx.core.content.FileProvider"
   android:authorities="${applicationId}.flutter_inappwebview_android.fileprovider"
   android:exported="false"
   android:grantUriPermissions="true">
   <meta-data
       android:name="android.support.FILE_PROVIDER_PATHS"
       android:resource="@xml/file_paths" />
</provider>

• Under <manifest> tag in AndroidManifest.xml. Add files access permissions:

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

• Then in res/xml/file_paths.xml

<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <cache-path name="cache" path="." />
    <external-path name="external_files" path="." />
</paths>

• For iOS declare Usage Description Keys in Info.plist. Add:

<key>NSCameraUsageDescription</key>
<string>This app requires camera access to upload photos.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app requires access to your photo library to upload files.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app requires microphone access for recording audio.</string>

Horray! You're done.

Available Parameters

Name	Default	Type	Description
websiteToken	-	String	Website inbox channel token
baseUrl	-	String	Installation url for chatwoot
user	-	ChatwootUser	User information about the user like email, username and avatar_url
locale	en	String	User locale
closeWidget	-	void Function()	widget close event
customAttributes	-	dynamic	Additional information about the customer
onLoadStarted	-	void Function()	Widget load start event
onLoadProgress	-	void Function(int)	Widget Load progress event
onLoadCompleted	-	void Function()	Widget Load completed event

b. Using Chatwoot Client

• Create an Api inbox in Chatwoot. Refer to Create API Channel document.
• Create your own customized chat ui and use ChatwootClient to load and sendMessages. Messaging events like onMessageSent and onMessageReceived will be triggered on ChatwootCallback argument passed when creating the client instance.

NB: This chatwoot client uses Hive for local storage.

final chatwootCallbacks = ChatwootCallbacks(
      onWelcome: (){
        print("on welcome");
      },
      onPing: (){
        print("on ping");
      },
      onConfirmedSubscription: (){
        print("on confirmed subscription");
      },
      onConversationStartedTyping: (){
        print("on conversation started typing");
      },
      onConversationStoppedTyping: (){
        print("on conversation stopped typing");
      },
      onPersistedMessagesRetrieved: (persistedMessages){
        print("persisted messages retrieved");
      },
      onMessagesRetrieved: (messages){
        print("messages retrieved");
      },
      onMessageReceived: (chatwootMessage){
        print("message received");
      },
      onMessageDelivered: (chatwootMessage, echoId){
        print("message delivered");
      },
      onMessageSent: (chatwootMessage, echoId){
        print("message sent");
      },
      onError: (error){
        print("Ooops! Something went wrong. Error Cause: ${error.cause}");
      },
    );

    ChatwootClient.create(
        baseUrl: widget.baseUrl,
        inboxIdentifier: widget.inboxIdentifier,
        user: widget.user,
        enablePersistence: widget.enablePersistence,
        callbacks: chatwootCallbacks
    ).then((client) {
        client.loadMessages();
    }).onError((error, stackTrace) {
      print("chatwoot client creation failed with error $error: $stackTrace");
    });

Available Parameters

Name	Default	Type	Description
baseUrl	-	String	Installation url for chatwoot
inboxIdentifier	-	String	Identifier for target chatwoot inbox
enablePersistance	true	bool	Enables persistence of chatwoot client instance's contact, conversation and messages to disk for convenience. true - persists chatwoot client instance's data(contact, conversation and messages) to disk. To clear persisted data call ChatwootClient.clearData or ChatwootClient.clearAllData false - holds chatwoot client instance's data in memory and is cleared as soon as chatwoot client instance is disposed Setting
user	null	ChatwootUser	Custom user details to be attached to chatwoot contact
callbacks	null	ChatwootCallbacks	Callbacks for handling chatwoot events