widget_chat is live on pub.dev: drop-in AI chat for Flutter, FlutterFlow, iOS, Android, React & Web. Start free →

← Back to Blog
Chatbase Alternative for Flutter: WebView vs Native Widget

Chatbase Alternative for Flutter: WebView vs Native Widget

chatbaseflutterwebviewai chatbotflutterflowwidget_chat

Your Chatbase agent already answers questions on your website, and now the same bot has to live inside your Flutter app. Search pub.dev for a Chatbase Flutter package and you will not find an official one. Chatbase's docs list two mobile SDKs, Android (Kotlin, marked Alpha) and iOS (Swift, marked Beta), and both are for teams that build their own native chat UI. For everything else, including Flutter, the documented route is a WebView that loads the chat page.

That route works, and this post shows it with real code. Then it goes criterion by criterion through what a WebView costs you inside an app, next to a native AI chatbot Flutter package such as widget_chat, which is what Widget-Chat ships.

Chatbase mobile app integration: the documented route

The Chatbase iframe guide has a "Mobile apps" section. The WebView loads the chat URL directly, with no HTML of your own:

https://www.chatbase.co/chatbot-iframe/YOUR_AGENT_ID

The page talks to its host only through postMessage. Your app injects a small bridge script that forwards chat events to Dart and sends identify when the chat posts iframeReady. Chatbase's own Flutter sample uses flutter_inappwebview, because that plugin can inject a script at document start. Many apps already ship webview_flutter, so here is the same bridge on the official plugin.

User taps HelpWebView loads chatbot-iframe URLBridge script listens for postMessageJavaScriptChannelDart handler
Dart handlerrunJavaScript(window.postMessage)Chat page

Embed Chatbase in a Flutter app with webview_flutter

  1. Add packagesflutter pub add webview_flutter webview_flutter_android webview_flutter_wkwebview url_launcher permission_handler
  2. Declare permissionsRECORD_AUDIO on Android and NSMicrophoneUsageDescription on iOS, only needed for voice or dictation.
  3. Inject the bridgeForward every chat event to a JavaScriptChannel and send identify on iframeReady.
  4. Grant web permissionsAnswer the WebView's microphone request in onPermissionRequest.
  5. Open links outsideSend any URL that is not the chat host to the system browser.

Platform setup

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- ios/Runner/Info.plist -->
<key>NSMicrophoneUsageDescription</key>
<string>Talk to our support assistant.</string>

The screen

import 'dart:convert';
import 'dart:io';

import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';

const agentUrl = 'https://www.chatbase.co/chatbot-iframe/YOUR_AGENT_ID';

class ChatbaseScreen extends StatefulWidget {
  const ChatbaseScreen({super.key, this.token});

  /// JWT signed by YOUR server. Never sign it in the app.
  final String? token;

  @override
  State<ChatbaseScreen> createState() => _ChatbaseScreenState();
}

class _ChatbaseScreenState extends State<ChatbaseScreen> {
  late final WebViewController _controller;

  String get _bridge => '''
    if (!window.__cbBridge) {
      window.__cbBridge = true;
      const TOKEN = ${jsonEncode(widget.token)};
      window.addEventListener('message', (e) => {
        if (e.source !== window || !e.data?.type) return;
        if (e.data.type === 'iframeReady') {
          window.postMessage({ type: 'identify', params: { token: TOKEN, publicAttributes: {} } }, location.origin);
          window.postMessage({ windowInnerWidth: window.innerWidth }, location.origin);
        }
        ChatbaseFlutter.postMessage(JSON.stringify(e.data));
      });
    }
  ''';

  @override
  void initState() {
    super.initState();

    late final PlatformWebViewControllerCreationParams params;
    if (WebViewPlatform.instance is WebKitWebViewPlatform) {
      params = WebKitWebViewControllerCreationParams(
        allowsInlineMediaPlayback: true,
        mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
      );
    } else {
      params = const PlatformWebViewControllerCreationParams();
    }

    _controller = WebViewController.fromPlatformCreationParams(
      params,
      // The page asks for the mic (voice, dictation). Without this it is denied.
      onPermissionRequest: (request) => request.grant(),
    )
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..addJavaScriptChannel('ChatbaseFlutter', onMessageReceived: _onEvent)
      ..setNavigationDelegate(
        NavigationDelegate(
          onPageStarted: (_) => _controller.runJavaScript(_bridge),
          onNavigationRequest: (request) {
            final uri = Uri.parse(request.url);
            if (uri.host == Uri.parse(agentUrl).host) {
              return NavigationDecision.navigate;
            }
            launchUrl(uri, mode: LaunchMode.externalApplication);
            return NavigationDecision.prevent;
          },
        ),
      );

    final platform = _controller.platform;
    if (platform is AndroidWebViewController) {
      platform.setMediaPlaybackRequiresUserGesture(false);
    }

    _open();
  }

  Future<void> _open() async {
    // Android: granting the web request is not enough, the app itself
    // needs the OS permission first. Skip this if you do not use voice.
    if (Platform.isAndroid) await Permission.microphone.request();
    await _controller.loadRequest(Uri.parse(agentUrl));
  }

  void send(Map<String, dynamic> message) {
    _controller.runJavaScript(
      'window.postMessage(${jsonEncode(message)}, location.origin)',
    );
  }

  void _onEvent(JavaScriptMessage message) {
    final event = jsonDecode(message.message) as Map<String, dynamic>;
    switch (event['type']) {
      case 'close':
        Navigator.of(context).maybePop();
      case 'CHATBOT_TOOL_CALL':
        _runTool(event['toolName'] as String, event['args']);
    }
  }

  void _runTool(String toolName, dynamic args) {
    if (toolName == 'open_orders') {
      Navigator.of(context).pushNamed('/orders');
    }
    send({
      'type': 'CHATBOT_TOOL_RESULT',
      'toolName': toolName,
      'result': {'status': 'success', 'data': {}},
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Support')),
      body: SafeArea(child: WebViewWidget(controller: _controller)),
    );
  }
}

One more setting to know: the WebView opens the iframe link directly, so the dashboard option "Block direct access to the iframe link" must stay off, or the WebView shows an error instead of the chat.

What the Chatbase WebView costs you in a Flutter app

The code above is about 100 lines and it runs. The cost shows up in the parts of a chat screen that a browser tab handles for free and an app does not.

Keyboard insets

Two layers react to the keyboard: Scaffold resizes its body, and the web page lays itself out against its own viewport. On iOS, WKWebView also scrolls a focused input into view by itself. The Chatbase guide does not cover keyboard behaviour in a WebView, so you own the testing on both platforms, and resizeToAvoidBottomInset is the first thing to toggle if the composer hides behind the keyboard or jumps.

Image attachments and the camera

Chatbase's docs say the Chat Bubble accepts PNG, JPG and PDF when attachments are turned on. A web chat picks files through an HTML file input. On Android, webview_flutter does nothing with that input until you call AndroidWebViewController.setOnShowFileSelector and return file URIs yourself, usually by wiring image_picker or file_picker. Taking a photo from the camera means your own capture code and the camera permission on top.

Callbacks into the app

Chatbase does support them: client-side Custom Actions arrive as CHATBOT_TOOL_CALL messages and you answer with CHATBOT_TOOL_RESULT. In a WebView that means JSON strings through a JavaScript channel, parsed by hand, as in _runTool above. The docs also note that results are matched by tool name, so two simultaneous calls to the same tool can receive each other's result, and a call fails after 60 seconds.

Microphone plumbing

Voice needs three things to line up: the manifest or Info.plist entry, the OS runtime permission, and the WebView's own permission request answered in onPermissionRequest. Miss one and the mic fails inside the page, where your Dart code sees nothing but a voice-error event.

Theming

The look of the chat is set in the Chatbase dashboard. The runtime options the iframe guide lists are text and behaviour fields (display name, placeholder, footer, suggested messages), and the guide lists no message to switch between light and dark. The page does not read your Flutter ThemeData.

Signed identity

JWT identity works in the WebView and is verified on Chatbase's server. You pass the token when the chat opens, inside the 500 ms window, and the docs state there is no event that confirms identification: you check a conversation in the dashboard.

Chatbase WebView next to a native Flutter widget

Criterion Chatbase in a WebView widget_chat package
Integration WebView plus a bridge script you maintain One Flutter widget
Rendering Web page in a platform view Flutter widgets
Keyboard Scaffold and web viewport both react, you test and tune Laid out by Flutter like any screen
Image attachments File selector callback to write on Android Camera or gallery built in
Callbacks into the app postMessage JSON through a JS channel Dart callback, onRichContentCallback(callbackId, payload)
Theme Set in the Chatbase dashboard Light, dark and system modes
Signed identity JWT sent by the bridge, 500 ms window HMAC-signed user identity
Voice Supported, three permission layers Mic button in the same widget, host app declares the mic permission
Channels beyond the app Website, WhatsApp, Messenger, Instagram, email, Slack Flutter, FlutterFlow, iOS and Android SDKs, web embed

Chatbase WebView in Flutter

  • About 100 lines of Dart and JavaScript bridge
  • Events arrive as JSON strings
  • File picker and mic permissions wired by hand
  • Web page look, styled in the Chatbase dashboard

Native widget_chat

  • One ChatWidget in the widget tree
  • Typed Dart callback for buttons and cards
  • Camera and gallery attachments included
  • Light, dark and system themes
Line count is from the worked example in this post.

When Chatbase is the better pick

Say it plainly: if your team is website-first and the bot's main job is a web bubble, Chatbase is the better choice. Its docs cover channels Widget-Chat does not have (WhatsApp, Messenger, Instagram, email, Slack), plus tickets and Stripe Actions. If the in-app chat is a secondary help screen and you already run a Chatbase agent, the WebView above keeps one agent, one dashboard and one conversation history, and that is a fair trade.

If you have native iOS and Android apps and want to build your own chat UI, Chatbase's Swift and Kotlin SDKs exist for that, with the Alpha and Beta labels their docs give them.

A Chatbase alternative for Flutter makes sense when the chat is a core screen of the app: users attach photos, the bot opens screens and paywalls, and the UI has to feel like the rest of your Flutter code.

The native route: widget_chat

Widget-Chat is a drop-in AI chat widget for Flutter and FlutterFlow. You train the assistant on your own content in a no-code dashboard, add the package, and the whole chat screen is there. There is no chat backend to build or host.

flutter pub add widget_chat
import 'package:widget_chat/widget_chat.dart';

ChatWidget(
  configuration: BotConfiguration(
    projectSecretKey: 'your-project-secret-key',
    userID: 'user-123',
  ),
  onRichContentCallback: (callbackId, payload) {
    switch (callbackId) {
      case 'open_orders':
        Navigator.of(context).pushNamed('/orders');
    }
  },
)

The button the assistant shows lands in your Dart code with no bridge script. Image attachments from camera or gallery, chat history, 46 UI locales and replies in 100+ languages come with the widget. Live voice is in the same package: declare NSMicrophoneUsageDescription and RECORD_AUDIO in the host app. FlutterFlow users add widget_chat as a custom pub dependency in a custom widget.

  • Chatbase has native SDKs (Android Alpha, iOS Beta) and no Flutter package
  • The documented Flutter route is a WebView with a postMessage bridge
  • The WebView works, and you own keyboard, file picker, mic and bridge code
  • Website-first team with a web bubble: stay on Chatbase
  • Chat as a core app screen: use a native Flutter widget

The free plan needs no credit card. Create a project and get your key at app.widget-chat.com.

Chatbase's iframe guide, whose Mobile apps section documents the WebView route

Chatbase's SDK overview: Android (Alpha) and iOS (Beta), no Flutter package

The widget_chat package on pub.dev

Add an AI chat to your Flutter app without building it

Widget-Chat is a drop-in chat widget for Flutter and FlutterFlow. Add the package, pass your project key, and the whole chat screen is there. You set up the assistant in a no-code dashboard.

flutter pub add widget_chat

Free plan, no credit card.

Widget-Chat

About the author

Widget-Chat is built by a small team of Flutter developers. We write about the problems we hit while shipping AI chat in production apps.