Suggestions

close search

Getting started with Stringee Live Chat API

Prepare

In order 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 Flutter Plugin

  1. Add stringee-flutter-plugin into your pubspec.yaml file
    dependencies:
    ...
    stringee_flutter_plugin:
        git:
            url: https://github.com/stringeecom/stringee_flutter_plugin.git
  2. Install the plugin by running the following command from the project root:
    $ flutter pub get

Setup

Android

  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" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  2. ProGuard

If your project uses ProGuard, you may have to add the following settings to the ProGuard configuration file to ensure Stringee builds correctly:

iOS

  1. From the command line run following command:
    pod install --repo-update
  2. After run cocoapods command, open project file .xcworkspace
  3. In the Build Settings tab -> Other linker flags add $(inherited) flag
  4. In the Build Settings tab -> Enable bitcode select NO
  5. In the Build Settings tab -> Allow Non-modular includes in Framework Modules select YES

Customer

Step 1: Initialize StringeeClient, StringeeChat

```
import 'package:stringee_flutter_plugin/stringee_flutter_plugin.dart';
...
StringeeClient client = StringeeClient();
StringeeChat chat = new StringeeChat(client);
```

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

Step 2: Get chat profile

Chat Profile is an object which will let you know:

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

Step 3: Generate access token for customers

In order 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. In order to do that, call the following function:

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:

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.

    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;
            }
        }); 
    ...
    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 StringeeClient connect false
    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 user send begin typing event
    void handleUserBeginTypingEvent(Map<dynamic, dynamic> map) {}
    
    /// Invoked when user send end typing event
    void handleUserEndTypingEvent(Map<dynamic, dynamic> map) {}
    
    /// Invoked when receive an chat change event
    void handleDidReceiveObjectChangeEvent(StringeeObjectChange stringeeObjectChange) {}
  2. Connect by calling:

    ...
    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?...). In order to do that, call the following function:

chat.updateUserInfo("USER_NAME", "USER_EMAIL", "USER_AVATAR").then((value) {
    bool status = value['status'];
    if (status) {
    }
});

Then start a live chat conversation by calling:

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

In which:

Step 6: Messages

Follow this instruction Messages

Step 7: End a live chat conversation

In order to end the live chat conversation, you call the following method:

conversation.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.

    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;
            }
        }); 
    ...
    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 StringeeClient connect false
    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 chatRequest) {}
    
    /// Invoked when receive transfer chat request from other agent
    void handleDidReceiveTransferChatRequestEvent(StringeeChatRequest chatRequest) {}
    
    /// Invoked when time out chat request for agent
    void handleTimeoutAnswerChatEvent(StringeeChatRequest chatRequest) {}
    
    /// Invoked when conversation ended
    void handleConversationEndedEvent(Map<dynamic, dynamic> map) {}
    
    /// Invoked when user send begin typing event
    void handleUserBeginTypingEvent(Map<dynamic, dynamic> map) {}
    
    /// Invoked when user send end typing event
    void handleUserEndTypingEvent(Map<dynamic, dynamic> map) {}
    
    /// Invoked when receive an chat change event
    void handleDidReceiveObjectChangeEvent(StringeeObjectChange stringeeObjectChange) {}
  2. Connect by calling:
    String token = '';
    ...
    client.connect(token);
    ...

Step 2: Accept/ Reject

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

Accept

For accept chat request, call the following function:

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

After accept chat request success, you can get conversation by conversationId from chat request

Reject

For accept chat request, call the following function:

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

Step 3: Messages

Follow this instruction Messages

Step 4: End a live chat conversation

In order to end the live chat conversation, you call the following method:

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

Extra

Create a ticket for a miss chat

For agent want to create a ticket for a missed live chat conversation, you call:

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

Chat Transcript

If you wanna send chat's content to an email at any time, you can use the following function:

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: https://github.com/stringeecom/stringee_flutter_plugin/tree/master/example