Add chat to your Flutter app

The Flutter SDK (osvi_chat, on pub.dev) puts one of your chat agents in a Flutter app. It talks to the same agent, dashboard settings and conversations as the website chat, and gives you a ready-made chat screen, a launcher button, and a headless client if you want your own interface. It runs on iOS, Android, web, macOS, Windows and Linux, with no native code. It needs Flutter 3.24 or later. This guide uses anonymous chat. For signed-in customers, see Logged-in users after this.

1. Turn it on

In the chat agent, open Channels → Web widget and switch Anonymous usage on, then press Save. The same switch controls the website widget, the share link and anonymous chat in your app. Every setting is explained in Dashboard settings. You do not need to add anything to Allowed websites for an iOS, Android or desktop app. That list is checked against the Origin header a browser sends, and native apps send none. A Flutter web build runs in a browser, so add its origin, as for any website.

2. Install the package

flutter pub add osvi_chat

Then allow network access where the platform requires it:

Platform	What to add
Android	`<uses-permission android:name="android.permission.INTERNET"/>` in `android/app/src/main/AndroidManifest.xml`, above `<application>`. Debug builds have it already; release builds need it
macOS	`<key>com.apple.security.network.client</key><true/>` in both `macos/Runner/DebugProfile.entitlements` and `Release.entitlements`
iOS, Windows, Linux, web	Nothing

3. Add the launcher

Create the client once, for example in a State or your app’s dependency setup, and give it to the launcher. Use your agent’s ID: the agent_… value shown under the agent name in the dashboard.

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

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

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  OsviChatClient? _chat;

  @override
  void initState() {
    super.initState();
    OsviChatClient.create(agentId: 'agent_yourAgentId').then((client) {
      if (mounted) setState(() => _chat = client);
    });
  }

  @override
  void dispose() {
    _chat?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final chat = _chat;
    return Scaffold(
      appBar: AppBar(title: const Text('My app')),
      body: const Center(child: Text('Hello')),
      floatingActionButton: chat == null ? null : OsviChatLauncher(client: chat),
    );
  }
}

The launcher is a floating button with an unread badge. Tapping it opens the chat full screen. To open the chat from your own button instead, call OsviChatLauncher.open(context, client: chat). To place the chat inside a screen, use OsviChatView(client: chat); see Customise. Both widgets use Material, so they need a MaterialApp above them.

OsviChatClient.create remembers the visitor and their current conversation on the device with shared_preferences, so a returning visitor picks up where they left off. Uninstalling the app or clearing its data starts a fresh visitor.

4. Check it works

Run the app, tap the launcher and send a message. If the chat shows an error instead:

What you see	What to do
”This chat is no longer available”	Switch on Anonymous usage and press Save, or use server mode
”This chat is unavailable.”	Check the `agent_…` ID, and that the agent is active
”This chat is not enabled for this website.”	Only on a Flutter web build: add the page’s origin to Allowed websites
The chat never connects and shows Try again	Check the device is online. On Android release builds, add the `INTERNET` permission; on macOS, add the network entitlement

Every error code is listed in Error codes; the Flutter SDK uses the same codes.

Name clashes with Material

The package exports the transcript types Message and Divider. If a file that imports osvi_chat also uses Material’s Divider widget, hide the SDK’s one:

import 'package:osvi_chat/osvi_chat.dart' hide Divider;

Change the colours, header and text: Customise.
Connect the chat to signed-in customers: Logged-in users.
Build your own interface on the client: Headless client.
Before going live, read Security and limits. The limits for anonymous chat are the same in an app.

Get Started

Going Deeper

Chat SDK

API Reference

Add chat to your Flutter app

1. Turn it on

2. Install the package

3. Add the launcher

4. Check it works

Name clashes with Material

Next

​1. Turn it on

​2. Install the package

​3. Add the launcher

​4. Check it works

​Name clashes with Material

​Next

1. Turn it on

2. Install the package

3. Add the launcher

4. Check it works

Name clashes with Material

Next