flutter_chat2desk

Flutter plugin for integrating Chat2Desk. Connect with your customers via popular messengers (WhatsApp, Telegram, VK, Instagram and more) directly from your app.

Features

  • Real-time chat with your customers right inside your Flutter app
  • Type-safe platform communication between Dart, Kotlin (Android) and Swift (iOS) generated with Pigeon
  • Incoming and outgoing messages with attachments and buttons
  • Full-text search and query search across the message history
  • Sending client info (name, phone and custom fields)
  • Delivery status tracking and read receipts
  • Typing indicator and operator info
  • Error reporting via a dedicated stream

Platforms

Platform Support
Android ✅ (minSdk 24)
iOS ✅

Getting started

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  flutter_chat2desk: ^1.0.0

Android setup

The plugin uses Chat2Desk SDK under the hood. No additional permissions are required — just make sure your app's minSdkVersion is at least 24.

iOS setup

No additional configuration is required.

Usage

Create a Chat2Desk instance with your Settings and follow the lifecycle:

  1. init() — initialize the SDK with your credentials
  2. start() — start the chat session
  3. Listen to streams and interact with the chat
  4. stop() — stop the session
  5. dispose() — release the SDK resources
import 'package:flutter_chat2desk/flutter_chat2desk.dart';

final chat2desk = Chat2Desk(
  settings: Settings(
    authToken: 'YOUR_AUTH_TOKEN',
    baseHost: 'YOUR_BASE_HOST',
    wsHost: 'YOUR_WS_HOST',
    storageHost: 'YOUR_STORAGE_HOST',
  ),
);

// 1. Initialize
await chat2desk.init();

// 2. Listen to streams
chat2desk.connectionStatus().listen((status) {
  // ConnectionState.connecting, .connected, .closing, .closed
});

chat2desk.messages().listen((messages) {
  // List<Message>
});

chat2desk.operator().listen((operator) {
  // Operator? — name, avatar, typing
});

chat2desk.customFields().listen((fields) {
  // List<CustomField>
});

chat2desk.error().listen((error) {
  // Chat2DeskException
});

// 3. Start the session
await chat2desk.start();

// 4. Interact with the chat
await chat2desk.sendMessage(msg: 'Hello, Chat2Desk!');

// 5. Clean up
await chat2desk.stop();
await chat2desk.dispose();

API

Settings

Configuration required to initialize the plugin.

Field Type Description
authToken String Chat2Desk authorization token
baseHost String Base API host
wsHost String WebSocket host for real-time
storageHost String Storage host for attachments

Methods

Method Description
init() Initializes the SDK with the provided Settings.
start({String? clientId}) Starts the chat session, optionally reusing a known clientId.
clientPhone() Returns the phone number of the current client.
sendMessage({required String msg, AttachedFile? attachedFile}) Sends a text message, optionally with an attached file.
resendMessage({required Message message}) Re-sends a previously failed message.
fetchMessages({bool? loadMore, bool? clear}) Fetches the message history.
fetchNewMessages() Fetches new messages.
read() Marks the current dialog as read.
delivery({String? id}) Confirms delivery of a message.
sendClientParams({required String name, required String phone, required Map<int, String> fieldSet}) Sends client name, phone and custom fields.
searchByQuery({required String query, SearchOptions? options}) Searches messages by query.
fullTextSearch({required String query}) Performs full-text search.
flushAll() Clears all local data and stops the session.
stop() Stops the chat session.
dispose() Releases the SDK resources.

Streams

Stream Emits
connectionStatus() ConnectionState? changes.
messages() List<Message> on each chat update.
operator() Operator? — current operator info, including typing state.
customFields() List<CustomField> configured for the account.
error() Chat2DeskException when an error occurs.

Message

A chat message with a convenient MessageExtension:

Message message = ...;

DateTime? date = message.date; // converts dateInt to DateTime
message.date = DateTime.now(); // and back

bool isIncoming = message.inMessage(); // true for income / ratingIn types
Field Type Description
id String Message id
realId int Real message id on the server
read ReadStatus unread / read
status DeliveryStatus sending, sent, delivered, notDelivered
text String? Message text
type MessageType income, outcome, auto, system, ratingIn, ratingOut, comment
dateInt int? Timestamp (milliseconds since epoch)
attachments List<Attachment>? Attached files
buttons List<Button>? Quick-reply buttons

Exceptions

Chat2DeskException is a sealed class. Handle concrete subtypes for granular error handling:

Exception Meaning
NotInitializedException Called a method before init().
NotStartedException Called a method before start().
ClientIsNotAuthorizedException Client is not authorized.
MissedConnectionException Connection to the server was missed.
NetworkException Network failure (code contains the HTTP error code).
UnknownFieldSetException Sent custom field ids that are not configured (unknownFields).
MapperException Failed to map a native object to Dart.
UnknownException Unexpected error.

Example

Check the example app for a complete chat implementation — a working chat screen with message list, input field, file attachments and connection state handling.

Changelog

See the CHANGELOG for the release history.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Libraries

flutter_chat2desk