Ruut Flutter Chat SDK Documentation

A simple and powerful Flutter SDK to integrate real-time chat into your Flutter app using Ruut. Connect with your visitors instantly and provide exceptional support.

Overview

The Ruut Flutter Chat SDK allows you to add a fully-featured chat interface to your Flutter app. It supports real-time messaging, file attachments, customizable themes, and offline message storage.

Key Features

Real-time messaging with WebSocket support
File and image attachments
Customizable UI themes
Offline message persistence
Typing indicators
User avatars and names
Message status (sending, delivered, read)
Customer Satisfaction (CSAT) surveys

Installation

Add Dependency
Add the ruut_flutter package to your pubspec.yaml file. Check the latest version.
```
dependencies:
  ruut_flutter: ^latest_version
```
Install Dependencies
Run the following command in your terminal:
```
flutter pub get
```

Basic Setup

Create an API Channel
Follow the steps here to create an API channel on the Ruut server and get your inboxIdentifier.

Implement RuutChat Widget
Add the RuutChat widget to your app:

import 'package:flutter/material.dart';
import 'package:ruut_flutter/ruut_chat.dart';
import 'package:ruut_flutter/data/local/entity/ruut_user.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Ruut Chat Demo',
      home: Scaffold(
        body: RuutChat(
          inboxIdentifier: 'your_inbox_identifier',
          user: RuutUser(
            identifier: 'user_123',
            name: 'John Doe',
            email: '[email protected]',
          ),
        ),
      ),
    );
  }
}

Replace your_inbox_identifier with the inbox identifier from your Ruut API channel.

Note: The SDK uses Hive for local storage.

Configuration

Required Parameters

inboxIdentifier: Your Ruut inbox identifier (String, required).

Optional Parameters

Parameter Type Default Description enablePersistence bool true Enables saving messages and conversations to disk for offline access. user RuutUser null Custom user details (e.g., name, email, avatar). theme RuutChatTheme Default Customizes the chat UI (colors, fonts, icons). callbacks RuutCallbacks null Handles real-time events (e.g., message received, typing started).

Custom User Setup

RuutChat(
  inboxIdentifier: 'your_inbox_identifier',
  user: RuutUser(
    identifier: 'unique_user_id',
    name: 'Jane Doe',
    email: '[email protected]',
    avatarUrl: 'https://example.com/avatar.jpg',
    customAttributes: {
      'plan': 'premium',
      'signup_date': '2024-01-01',
    },
  ),
)

Theme Customization

RuutChat(
  inboxIdentifier: 'your_inbox_identifier',
  theme: RuutChatTheme(
    primaryColor: Colors.blue,
    backgroundColor: Colors.white,
    inputBackgroundColor: Colors.grey[100],
    userAvatarNameColors: [Colors.black, Colors.white],
    attachmentButtonIcon: Icon(Icons.image_outlined, color: Colors.grey),
  ),
)

Callbacks

Use RuutCallbacks to handle real-time events:

RuutChat(
  inboxIdentifier: 'your_inbox_identifier',
  callbacks: RuutCallbacks(
    onMessageReceived: (ruutMessage) {
      print('New message: ${ruutMessage.content}');
    },
    onMessageSent: (ruutMessage, echoId) {
      print('Message sent: ${ruutMessage.content}');
    },
    onError: (error) {
      print('Error: ${error.cause}');
    },
    onConversationStartedTyping: () {
      print('Agent is typing...');
    },
    onConversationIsOnline: () {
      print('Agent is online');
    },
  ),
)

Available Callbacks

Callback Description onWelcome Connection established. onMessageReceived New message from agent. onMessageSent Message sent successfully. onMessageDelivered Message delivered to server. onConversationStartedTyping Agent started typing. onConversationStoppedTyping Agent stopped typing. onConversationIsOnline Agent is online. onConversationIsOffline Agent is offline. onError Error occurred.

Troubleshooting

Common Issues

Chat Not Connecting

Verify your inboxIdentifier and Ruut server URL.

Example:

RuutClient.create(
  baseUrl: 'https://app.ruut.chat',
  inboxIdentifier: 'correct_identifier',
);

File Upload Fails

Check file size limits and network connection.

Handle errors:

onError: (error) {
  if (error.type == RuutClientExceptionType.SEND_MESSAGE_FAILED) {
    print('Upload failed. Check connection and retry.');
  }
}

Messages Not Persisting

Ensure enablePersistence is set to true:

RuutChat(
  inboxIdentifier: 'your_inbox_identifier',
  enablePersistence: true,
)

Theme Not Applied

Verify theme properties:

RuutChat(
  theme: RuutChatTheme(
    primaryColor: Colors.blue,
    backgroundColor: Colors.white,
  ),
)

Enable Debug Mode

Add debug logging for troubleshooting:

void initState() {
  super.initState();
  debugPrint('Ruut Chat initialized');
}

Error Handling

RuutChat(
  callbacks: RuutCallbacks(
    onError: (error) {
      switch (error.type) {
        case RuutClientExceptionType.CREATE_CLIENT_FAILED:
          print('Failed to initialize chat');
          break;
        case RuutClientExceptionType.SEND_MESSAGE_FAILED:
          print('Message failed to send');
          break;
        default:
          print('Unknown error: ${error.cause}');
      }
    },
  ),
)

If issues persist, contact us at [email protected].

Best Practices

Error Handling: Implement robust error handling for all callbacks.
User Feedback: Show loading states and error messages to users.

Performance: Use pagination for large message histories:

RuutChat(
  onEndReachedThreshold: 0.75,
  onEndReached: () async {
    await ruutClient?.loadMessages();
  },
)

Security: Validate user inputs and handle sensitive data securely.
Testing: Test on various devices and network conditions.

Updating the SDK

Check for Updates:
```
flutter pub outdated
```
Update Dependencies:
```
flutter pub upgrade
```
Review Changelog: Check for breaking changes and test after updates.

Support

Check example implementations on GitHub.
For issues, contact [email protected].

How to Integrate the Ruut Flutter SDK