Getting started with Stringee Live Chat API

Step 1: Prepare

The Stringee Live Chat API requires a widget key, which identifies your portal. You can obtain that key by following the steps below:

Log in to your StringeeX account as an administrator.
Go to Setting -> Chat Management -> Chat Widget -> Embed web widget and get the key from the URL.

Step 2: Adding the Stringee SDK

Stringee Android SDK is distributed through Maven Central and requires Android API 21 or later.

Make sure google() and mavenCentral() are included in your repositories.

Add the dependencies to the app-level build.gradle:

android {
   ...
   compileOptions {
       sourceCompatibility JavaVersion.VERSION_17
       targetCompatibility JavaVersion.VERSION_17
   }
}

dependencies {
   implementation 'com.stringee.sdk.android:stringee-android-sdk:2.1.13'
   implementation 'io.github.webrtc-sdk:android:144.7559.09'
}

Sync your project.

Step 3: Permissions and ProGuard

Add the following permissions to your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- Only needed when your chat UI lets users select attachments directly. -->
<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 request media, camera, microphone, contact, or location permissions required by features in your application. Request dangerous permissions at runtime on supported Android versions.

If your project uses R8/ProGuard, add the following rules to proguard-rules.pro:

-dontwarn org.webrtc.**
-keep class org.webrtc.** { *; }
-keep class com.stringee.** { *; }
-keepattributes Signature
-keepattributes *Annotation*

Step 4: Get chat profile

A chat profile provides:

User interface configuration that can be displayed to customers.
Queue information used to route live chat conversations.

Create a StringeeClient, then request the profile with your widget key:

private StringeeClient stringeeClient;
private String queueId;
private Conversation conversation;

stringeeClient = new StringeeClient(this);
stringeeClient.getChatProfile("YOUR_WIDGET_KEY", new CallbackListener<ChatProfile>() {
    @Override
    public void onSuccess(ChatProfile profile) {
        List<Queue> queues = profile.getQueues();
        if (queues != null && !queues.isEmpty()) {
            queueId = queues.get(0).getId();
        }
    }

    @Override
    public void onError(StringeeError error) {
    }
});

Step 5: Generate an access token for customers

Customers must connect to Stringee Server before communicating with agents. Because a live chat visitor may not be a system user, request a visitor access token with the widget key and customer information:

stringeeClient.getLiveChatToken(
    "YOUR_WIDGET_KEY",
    "YOUR_CUSTOMER_NAME",
    "YOUR_CUSTOMER_EMAIL",
    new CallbackListener<String>() {
        @Override
        public void onSuccess(String accessToken) {
            connect(accessToken);
        }

        @Override
        public void onError(StringeeError error) {
        }
    }
);

In which:

YOUR_WIDGET_KEY: Your portal's widget key.
YOUR_CUSTOMER_NAME, YOUR_CUSTOMER_EMAIL: Information supplied by the customer.

Step 6: Connect to Stringee Server

private void connect(String accessToken) {
    stringeeClient.addConnectionListener(new StringeeConnectionListener() {
        @Override
        public void onConnectionConnected(StringeeClient client, boolean isReconnecting) {
            // The client is now ready. Start the live chat flow from here.
            startLiveChat();
        }

        @Override
        public void onConnectionDisconnected(StringeeClient client, boolean isReconnecting) {
        }

        @Override
        public void onIncomingCall(StringeeCall call) {
        }

        @Override
        public void onIncomingCall2(StringeeCall2 call) {
        }

        @Override
        public void onConnectionError(StringeeClient client, StringeeError error) {
        }

        @Override
        public void onRequestNewToken(StringeeClient client) {
        }

        @Override
        public void onCustomMessage(String from, JSONObject message) {
        }

        @Override
        public void onTopicMessage(String from, JSONObject message) {
        }
    });

    stringeeClient.addChangeEventListener(new ChangeEventListener() {
        @Override
        public void onChangeEvent(StringeeChange change) {
        }
    });

    stringeeClient.addLiveChatEventListener(new LiveChatEventListener() {
        @Override
        public void onReceiveChatRequest(ChatRequest request) {
        }

        @Override
        public void onReceiveTransferChatRequest(ChatRequest request) {
        }

        @Override
        public void onHandleOnAnotherDevice(ChatRequest request, ChatRequest.State state) {
        }

        @Override
        public void onTimeoutAnswerChat(ChatRequest request) {
        }

        @Override
        public void onTimeoutInQueue(Conversation conversation) {
        }

        @Override
        public void onConversationEnded(Conversation conversation, User endedBy) {
        }
    });

    stringeeClient.connect(accessToken);
}

Step 7: Start a live chat conversation

Only start a live chat after StringeeConnectionListener.onConnectionConnected is invoked and a queue has been selected from the chat profile. The example above calls the following startLiveChat() method from onConnectionConnected:

private void startLiveChat() {
    if (queueId == null) {
        return;
    }

    stringeeClient.updateUser("USER_NAME", "USER_EMAIL", "USER_AVATAR", new StatusListener() {
        @Override
        public void onSuccess() {
            stringeeClient.createLiveChat(queueId, new CallbackListener<Conversation>() {
                @Override
                public void onSuccess(Conversation result) {
                    conversation = result;
                }

                @Override
                public void onError(StringeeError error) {
                }
            });
        }

        @Override
        public void onError(StringeeError error) {
        }
    });
}

In which:

queueId: The ID of the queue to which the conversation will be routed.
stringeeClient.updateUser(...) updates customer information.
stringeeClient.createLiveChat(...) creates the live chat conversation.
The returned Conversation object is saved to conversation for messaging and ending the chat.

Step 8: Messages

Follow the Messages guide.

Step 9: End a live chat conversation

End the chat from its Conversation object:

if (conversation == null) {
    return;
}
conversation.endChat(stringeeClient, new StatusListener() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(StringeeError error) {
    }
});

Step 10: Create a ticket when live chat is unavailable

Create a customer ticket when live chat is unavailable, for example outside business hours:

stringeeClient.createLiveChatTicket(
    "YOUR_WIDGET_KEY",
    "CUSTOMER_NAME",
    "CUSTOMER_EMAIL",
    "TICKET_DESCRIPTION",
    new StatusListener() {
        @Override
        public void onSuccess() {
        }

        @Override
        public void onError(StringeeError error) {
        }
    }
);

Sample

You can view the latest Android chat sample on GitHub: ChatSample

Suggestions