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

# Add chat to your Flutter app

> Install the Osvi AI chat SDK for Flutter and open a chat with your agent

The Flutter SDK (`osvi_chat`, on [pub.dev](https://pub.dev/packages/osvi_chat)) puts one of your chat agents in a Flutter app. It talks to the same agent, dashboard settings and conversations as the [website chat](https://docs.osvi.ai/website-chat/overview.md), 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](https://docs.osvi.ai/flutter/server-mode.md) 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](https://docs.osvi.ai/website-chat/dashboard-settings.md).

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

```sh theme={null}
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.

```dart theme={null}
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](https://docs.osvi.ai/flutter/customise.md).

Both widgets use Material, so they need a `MaterialApp` above them.

> [!NOTE]
>
> `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](https://docs.osvi.ai/flutter/server-mode.md) |
| "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](https://docs.osvi.ai/website-chat/error-codes.md); 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:

```dart theme={null}
import 'package:osvi_chat/osvi_chat.dart' hide Divider;
```

## Next

* Change the colours, header and text: [Customise](https://docs.osvi.ai/flutter/customise.md).
* Connect the chat to signed-in customers: [Logged-in users](https://docs.osvi.ai/flutter/server-mode.md).
* Build your own interface on the client: [Headless client](https://docs.osvi.ai/flutter/headless.md).
* Before going live, read [Security and limits](https://docs.osvi.ai/website-chat/security.md). The limits for anonymous chat are the same in an app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.