Suggestions

close search

Getting started with Stringee Live Chat API

Prepare

To use Stringee Live Chat API, you need to have a widget key which will be used to identify your portal. You can get that key by doing the following steps:

1. Login to your StringeeX account as an admin
2. In the Setting → Chat Management → Chat Widget → Embed web widget, get the key in the URL

Adding the Stringee Plugin

Install stringee-plugin from pub.dev by running the following command from the project root:

$ flutter pub add stringee_plugin:^1.3.2

Check out plugin's documentation for more information.

Setup

Android

Stringee Plugin 1.3.2 requires JDK 17 and Android API 21 or later. Set compileSdk to 36 and minSdk to 21 or later in android/app/build.gradle.

1. The Stringee Android SDK requires some permissions from your app's AndroidManifest.xml file:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
   <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
   <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
   <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

   Only add and request permissions required by attachment features in your app.

2. ProGuard/R8 rules for Stringee and WebRTC are included in the plugin. Keep your application's existing minification configuration; you do not need to enable minification specifically for Stringee.

iOS

Stringee Plugin 1.3.2 requires iOS 13.0 or later. Set platform :ios, '13.0' in ios/Podfile.

1. From the command line run following command:

   pod install --repo-update

2. After running CocoaPods, open the generated .xcworkspace file.

Customer

Step 1: Initialize StringeeClient, StringeeChat

import 'dart:async';
import 'package:stringee_plugin/stringee_plugin.dart';
...
final StringeeClient client = StringeeClient();
final StringeeChat chat = StringeeChat(client);
StreamSubscription? clientSubscription;
StreamSubscription? chatSubscription;
String? queueId;
StringeeConversation? conversation;
StringeeChatRequest? chatRequest;
bool isClientConnected = false;

The StringeeClient class is defined in the Stringee Plugin. It includes methods interacting with Stringee Server. The StringeeChat class is defined in the chat section in the Stringee Plugin. It includes methods interacting with Stringee Server.

Step 2: Get chat profile

Chat Profile is an object that will let you know:

• Configuration information about the user interface that you should display to customers.
• Queue information (queue is where you will route live chat conversations to)

chat.getChatProfile('YOUR_WIDGET_KEY').then((value) {
    print("getChatProfile: " + value.toString());
    bool status = value['status'];
    if (status) {
        List queueList = value['body']['queues'];
        if (queueList.isNotEmpty) {
            queueId = queueList.first['id'];
        }
    }
});

Step 3: Generate access token for customers

To chat with your agents, your customers have to connect to Stringee server first. But they are not users in your system, they can be anybody, so you need to generate a token for them. Call getLiveChatToken(...) on the StringeeChat object:

late String token;
...
chat.getLiveChatToken('YOUR_WIDGET_KEY', 'YOUR_CUSTOMER_NAME', 'YOUR_CUSTOMER_EMAIL').then((value) {
    print("getLiveChatToken: " + value.toString());
    bool status = value['status'];
    if (status) {
    token = value['body'];
    }
});

In which:

• YOUR_WIDGET_KEY: your portal's widget key
• YOUR_CUSTOMER_NAME, YOUR_CUSTOMER_EMAIL: you can ask your customer to supply it

Step 4: Connect to Stringee Server

Next, we will connect to Stringee Server. You must do this before you can start a live chat conversation.

1. Register the client's events and chat's events.

   clientSubscription = client.eventStreamController.stream.listen((event) {
       Map<dynamic, dynamic> map = event;
       switch (map['eventType']) {
           case StringeeClientEvents.didConnect:
               handleDidConnectEvent();
               break;
           case StringeeClientEvents.didDisconnect:
               handleDidDisconnectEvent();
               break;
           case StringeeClientEvents.didFailWithError:
               int code = map['body']['code'];
               String msg = map['body']['message'];
               handleDidFailWithErrorEvent(code,msg);
               break;
           case StringeeClientEvents.requestAccessToken:
               handleRequestAccessTokenEvent();
               break;
           case StringeeClientEvents.didReceiveCustomMessage:
               handleDidReceiveCustomMessageEvent(map['body']);
               break;
           case StringeeClientEvents.timeoutInQueue:
               handleTimeoutInQueueEvent(map['body']);
               break;
           case StringeeClientEvents.conversationEnded:
               handleConversationEndedEvent(map['body']);
               break;
           case StringeeClientEvents.userBeginTyping:
               handleUserBeginTypingEvent(map['body']);
           break;
               case StringeeClientEvents.userEndTyping:
               handleUserEndTypingEvent(map['body']);
           break;
           default:
               break;
           }
       }); 
   ...
   chatSubscription = chat.eventStreamController.stream.listen((event) {
       Map<dynamic, dynamic> map = event;
       if (map['eventType'] == StringeeChatEvents.didReceiveObjectChange) {
           handleDidReceiveObjectChangeEvent(map['body']);
       }
   });
   ...
   /// Invoked when the StringeeClient is connected
   void handleDidConnectEvent() {
       isClientConnected = true;
   }
   
   /// Invoked when the StringeeClient is disconnected
   void handleDidDisconnectEvent() {}
   
   /// Invoked when the StringeeClient connection fails
   void handleDidFailWithErrorEvent(int code, String message) {}
   
   /// Invoked when your token is expired
   void handleRequestAccessTokenEvent() {}
   
   /// Invoked when get Custom message
   void handleDidReceiveCustomMessageEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when no agent answer this chat and time out route in queue
   void handleTimeoutInQueueEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when conversation ended
   void handleConversationEndedEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a user sends a begin typing event
   void handleUserBeginTypingEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a user sends an end typing event
   void handleUserEndTypingEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a chat change event is received
   void handleDidReceiveObjectChangeEvent(StringeeObjectChange stringeeObjectChange) {}

2. Call connect(...) on the StringeeClient object:

   ...
   client.connect(token);
   ...

Step 5: Start a live chat conversation

Before starting a live chat conversation, you can update the customer information to Stringee Server, so your agent can know more about your customer (where is the customer from? what type of cell phone the customer using?...). Call updateUserInfo(...) on the StringeeChat object:

if (!isClientConnected || queueId == null) {
    return;
}
chat.updateUserInfo(
    name: 'USER_NAME',
    email: 'USER_EMAIL',
    avatar: 'USER_AVATAR',
).then((value) {
    bool status = value['status'];
    if (status) {
    }
});

After StringeeClientEvents.didConnect is received and queueId has been selected from the profile, start a live chat conversation by calling chat.createLiveChatConversation(...):

chat.createLiveChatConversation(queueId!).then((value) {
    bool status = value['status'];
    if (status) {
        conversation = value['body'];
    }
});

In which:

• queueId: The queue's id which you will route the live chat conversation to

Step 6: Messages

Follow this instruction Messages

Step 7: End a live chat conversation

To end the live chat conversation, call endChat() on the StringeeConversation object:

final activeConversation = conversation;
if (activeConversation == null) {
    return;
}
activeConversation.endChat().then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Agent

Step 1: Connect to Stringee Server

Next, we will connect to Stringee Server. You must do this before you can start a live chat conversation.

1. Register the client's events and chat's events.

   clientSubscription = client.eventStreamController.stream.listen((event) {
       Map<dynamic, dynamic> map = event;
       switch (map['eventType']) {
           case StringeeClientEvents.didConnect:
               handleDidConnectEvent();
               break;
           case StringeeClientEvents.didDisconnect:
               handleDidDisconnectEvent();
               break;
           case StringeeClientEvents.didFailWithError:
               int code = map['body']['code'];
               String msg = map['body']['message'];
               handleDidFailWithErrorEvent(code,msg);
               break;
           case StringeeClientEvents.requestAccessToken:
               handleRequestAccessTokenEvent();
               break;
           case StringeeClientEvents.didReceiveCustomMessage:
               handleDidReceiveCustomMessageEvent(map['body']);
               break;
           case StringeeClientEvents.didReceiveChatRequest:
               handleDidReceiveChatRequestEvent(map['body']);
               break;
           case StringeeClientEvents.didReceiveTransferChatRequest:
               handleDidReceiveTransferChatRequestEvent(map['body']);
               break;
           case StringeeClientEvents.timeoutAnswerChat:
               handleTimeoutAnswerChatEvent(map['body']);
               break;
           case StringeeClientEvents.conversationEnded:
               handleConversationEndedEvent(map['body']);
               break;
           case StringeeClientEvents.userBeginTyping:
               handleUserBeginTypingEvent(map['body']);
           break;
               case StringeeClientEvents.userEndTyping:
               handleUserEndTypingEvent(map['body']);
           break;
           default:
               break;
           }
       }); 
   ...
   chatSubscription = chat.eventStreamController.stream.listen((event) {
       Map<dynamic, dynamic> map = event;
       if (map['eventType'] == StringeeChatEvents.didReceiveObjectChange) {
           handleDidReceiveObjectChangeEvent(map['body']);
       }
   });
   ...
   /// Invoked when the StringeeClient is connected
   void handleDidConnectEvent() {}
   
   /// Invoked when the StringeeClient is disconnected
   void handleDidDisconnectEvent() {}
   
   /// Invoked when the StringeeClient connection fails
   void handleDidFailWithErrorEvent(int code, String message) {}
   
   /// Invoked when your token is expired
   void handleRequestAccessTokenEvent() {}
   
   /// Invoked when get Custom message
   void handleDidReceiveCustomMessageEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when receive chat request
   void handleDidReceiveChatRequestEvent(StringeeChatRequest request) {
       chatRequest = request;
   }
   
   /// Invoked when receive transfer chat request from other agent
   void handleDidReceiveTransferChatRequestEvent(StringeeChatRequest request) {
       chatRequest = request;
   }
   
   /// Invoked when time out chat request for agent
   void handleTimeoutAnswerChatEvent(StringeeChatRequest chatRequest) {}
   
   /// Invoked when conversation ended
   void handleConversationEndedEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a user sends a begin typing event
   void handleUserBeginTypingEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a user sends an end typing event
   void handleUserEndTypingEvent(Map<dynamic, dynamic> map) {}
   
   /// Invoked when a chat change event is received
   void handleDidReceiveObjectChangeEvent(StringeeObjectChange stringeeObjectChange) {}

2. Call connect(...) on the StringeeClient object:

   String token = '';
   ...
   client.connect(token);
   ...

Step 2: Accept/ Reject

After receiving a chat request, agent can accept or reject this chat request.

Accept

To accept the chat request, call accept() on the StringeeChatRequest object:

final request = chatRequest;
if (request == null) {
    return;
}
request.accept().then((value) {
    bool status = value['status'];
    if (status) {
        chat.getConversationById(request.convId).then((value) {
            conversation = value['body'];
        });
    }
});

After the chat request is accepted, get its conversation by using the conversation ID from the request.

Reject

To reject the chat request, call reject() on the StringeeChatRequest object:

final request = chatRequest;
if (request == null) {
    return;
}
request.reject().then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Step 3: Messages

Follow this instruction Messages

Step 4: End a live chat conversation

To end the live chat conversation, call endChat() on the StringeeConversation object:

final activeConversation = conversation;
if (activeConversation == null) {
    return;
}
activeConversation.endChat().then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Extra

Create a ticket when live chat is unavailable

Customers can create a ticket when live chat is unavailable, for example outside business hours. Call createLiveChatTicket(...) on the StringeeChat object:

chat.createLiveChatTicket('YOUR_WIDGET_KEY', 'CUSTOMER_NAME', 'CUSTOMER_EMAIL', 'TICKET_DESCRIPTION').then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Chat Transcript

To send the chat content by email, call sendChatTranscript(...) on the StringeeConversation object:

conversation.sendChatTranscript('EMAIL', 'DOMAIN').then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Sample

You can view a completed version of this sample app on GitHub: Stringee Flutter plugin example