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

# Flutter

> Add the Talqui chat to your Flutter app on iOS and Android with one controller and one widget.

> [card] [GitHub](https://github.com/talqui-oss/talqui-sdk-flutter)
>
> Source, issues and changelog

> [card] [pub.dev](https://pub.dev/packages/talqui_sdk_flutter)
>
> Package and versions

> [card] [Example app](https://github.com/talqui-oss/talqui-sdk-flutter/tree/main/example)
>
> `flutter run` and go

![Unread count in the host app](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/flutter/screenshot-1-unread.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=d04b3b3a6319677f0db16c07cc19ad5d)

![Full screen chat with text, an image and a voice message](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/flutter/screenshot-2-fullscreen.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=a3b473c1a2698b4f7196bf1a184bdad5)

![The chat inline in a tab](https://mintcdn.com/talqui/rN_YKMK5183esTyQ/images/guides/chat-sdks/flutter/screenshot-3-inline-tab.png?fit=max\&auto=format\&n=rN_YKMK5183esTyQ\&q=85\&s=8dd3cce8fca792087cf2ed9016601eeb)

## Requirements

Flutter 3.24 (Dart 3.5) or later, iOS 13, Android 7.0 (API 24).

## 1. Install

```bash theme={null}
flutter pub add talqui_sdk_flutter
```

> [!TIP]
>
> Using an AI coding agent? Point it to [`AGENT_INSTRUCTIONS.md`](https://github.com/talqui-oss/talqui-sdk-flutter/blob/main/AGENT_INSTRUCTIONS.md): a step-by-step install it can follow and validate on its own.

## 2. Permissions

Attachments, photos and voice messages need these entries.

> [tab] iOS (ios/Runner/Info.plist)
>
> ```xml theme={null}
> <key>NSCameraUsageDescription</key>
> <string>Take photos to send in the support chat.</string>
> <key>NSMicrophoneUsageDescription</key>
> <string>Record voice messages for the support chat.</string>
> <key>NSPhotoLibraryUsageDescription</key>
> <string>Choose photos to send in the support chat.</string>
> ```

> [tab] Android (AndroidManifest.xml)
>
> ```xml theme={null}
> <uses-permission android:name="android.permission.INTERNET" />
> <uses-permission android:name="android.permission.CAMERA" />
> <uses-permission android:name="android.permission.RECORD_AUDIO" />
> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
> ```
>
> Keep `android:windowSoftInputMode="adjustResize"` on your activity (the Flutter default) so the keyboard never covers the message box.

## 3. Create the controller

Create it once, with the values from [Get your IDs](https://docs.talqui.chat/guides/chat-sdks/get-your-ids.md), and reuse it everywhere (a top-level variable, Provider, Riverpod, GetIt…):

```dart theme={null}
import 'package:talqui_sdk_flutter/talqui_sdk_flutter.dart';

final talqui = TalquiController(
  tenantId: 'YOUR_TENANT_ID',
  connectionId: 'YOUR_CONNECTION_ID',
);
```

## 4. Open the chat

```dart theme={null}
FilledButton(
  onPressed: () => talqui.open(context),
  child: const Text('Talk to us'),
)
```

The chat opens in a full-screen route and closes with the header button or the back gesture. The conversation keeps running while it is closed.

### Or inline, in a tab

```dart theme={null}
TalquiChat(controller: talqui, hideCloseButton: true)
```

`hideCloseButton` removes the header's close button, which has nothing to close in a tab.

## 5. Identify the user

```dart theme={null}
await talqui.identify(TalquiUser(
  name: 'Ana Souza',
  email: 'ana@example.com',
  phone: '+5511999990000',
  userHash: hashFromYourBackend, // optional: history across devices
));
```

The pre-chat form is skipped and your team sees who is talking. [How to compute `userHash` →](https://docs.talqui.chat/guides/chat-sdks/identify-users)

## 6. Send context

```dart theme={null}
talqui.setContactMeta({'plan': 'pro', 'seats': 12});
talqui.setSessionMeta({'order_id': '4821', 'step': 'checkout'});
```

[Rules and where it shows up →](https://docs.talqui.chat/guides/chat-sdks/metadata.md)

## 7. Events and unread badge

```dart theme={null}
talqui.events
    .where((event) => event.name == 'messageReceived')
    .listen((event) => print(event.payload['preview']));

ValueListenableBuilder<int>(
  valueListenable: talqui.unreadCount,
  builder: (context, unread, _) => Badge(
    isLabelVisible: unread > 0,
    label: Text('$unread'),
    child: const Icon(Icons.chat_bubble_outline),
  ),
);
```

Call `talqui.preload()` early (after login, for example) so replies are counted before the user first opens the chat. [All events →](https://docs.talqui.chat/guides/chat-sdks/events.md)

## 8. Logout

```dart theme={null}
await talqui.logout();
```

Forgets the user on this device, clears everything you set, unlinks the push token and starts a fresh anonymous visitor.

## 9. Push notifications

Optional: notify the user when a reply arrives while they are away. Set up Firebase and hand the device token to the SDK. See [Push notifications for mobile apps](https://docs.talqui.chat/guides/push-notifications/mobile-apps.md).

## API reference

### `TalquiController`

| Member | |
| - | - |
| `TalquiController({tenantId, connectionId, onOpenUrl, debug})` | `tenantId` and `connectionId` are required. `onOpenUrl` handles links tapped in the chat (default: external browser). `debug` logs every message exchanged with the chat. |
| `open(context)` / `close()` | Show or hide the full-screen chat. |
| `preload()` | Loads the chat ahead of time so `open` is instant and replies are counted. |
| `identify(user)` | Sets who the user is (`TalquiUser`: `name`, `email`, `phone`, `userHash`). |
| `setContact({name, email, phone})` | Updates the contact details. |
| `setContactMeta(meta)` / `setSessionMeta(meta)` | Custom data, see [Metadata](https://docs.talqui.chat/guides/chat-sdks/metadata.md). |
| `prefill(text)` | Puts text in the message box. The user still decides to send it. |
| `logout()` | Forgets the user and starts a fresh visitor. |
| `setPushToken(token)` | The device's FCM token, see [Push notifications](https://docs.talqui.chat/guides/push-notifications/mobile-apps.md). |
| `handlePush(context, data)` | Opens the chat for a tapped Talqui notification. `TalquiController.isTalquiPush(data)` tells Talqui pushes apart from yours. |
| `events` | `Stream<TalquiEvent>` with `name` and `payload`. |
| `unreadCount`, `isReady` | `ValueNotifier<int>`, `ValueNotifier<bool>`. |
| `isOpen` | Whether the full-screen chat is showing. |
| `dispose()` | Releases the chat. Call it if you create the controller inside a `State`. |

### `TalquiChat`

| Parameter | Type | |
| - | - | - |
| `controller` | `TalquiController` | Required. |
| `loading` | `Widget?` | Replaces the loading indicator. |
| `error` | `Widget Function(VoidCallback retry)?` | Replaces the screen shown when the chat cannot load. |
| `hideCloseButton` | `bool` | Hides the header's close button. Default `false`. |

## Example app

```bash theme={null}
git clone https://github.com/talqui-oss/talqui-sdk-flutter
cd talqui-sdk-flutter/example
flutter run
```

It has an "Open chat" button, a "Chat" tab with an unread badge, and buttons for identify, metadata, prefill and logout, connected to the Talqui demo workspace.

Something not working? See [Troubleshooting](https://docs.talqui.chat/guides/chat-sdks/troubleshooting.md#flutter).


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